Class EntityStats

Namespace

ElectricDrill.AstraRpgFramework.Stats

Assembly

com.electricdrill.astra-rpg-framework.Runtime.dll

Component that manages the statistics of an entity in the game. It handles base stats, flat stat modifiers, stat to stat modifiers, and percentage stat modifiers.
Base stats can either be fixed or come from the entity's class (if one is available on the Game Object). When stats change because of a modifier of any kind, the assigned StatChangedGameEvent is raised.

[DisallowMultipleComponent]
[RequireComponent(typeof(EntityCore))]
public class EntityStats : MonoBehaviour, IHasStatSet, IValueProvider<StatSO, long>, IStatReader, IValueContainer<StatSO>, IHasEntity, IEventRegistrar

Inheritance

object

Object

Component

Behaviour

MonoBehaviour

EntityStats

Implements

IHasStatSet

IValueProvider<StatSO, long>

IStatReader

IValueContainer<StatSO>

IHasEntity

IEventRegistrar

Extension Methods

ComponentUtils.GetOrCache<T>(MonoBehaviour, ref T)

Fields

_entityClass

protected IClassSource _entityClass

Field Value

IClassSource

_flatModifiers

protected StatSetInstance _flatModifiers

Field Value

StatSetInstance

_percentageModifiers

protected StatSetInstance _percentageModifiers

Field Value

StatSetInstance

Properties

Entity

The primary EntityCore associated with this object. For entity components this is the owning entity; for context payloads this is the primary affected subject (e.g. the event target).

public EntityCore Entity { get; }

Property Value

EntityCore

EntityClass

The class source of the entity. In most cases, this is the EntityClass component attached to the entity.

public IClassSource EntityClass { get; }

Property Value

IClassSource

EntityCore

The entity core associated with this stats component.

public EntityCore EntityCore { get; }

Property Value

EntityCore

OnStatChanged

Event raised when a Stat changes.

public StatChangedGameEvent OnStatChanged { get; }

Property Value

StatChangedGameEvent

StatSet

The stat set used to calculate the entity's stats.

public virtual StatSetSO StatSet { get; }

Property Value

StatSetSO

If _useBaseStatsFromClass is true, it returns the stat set of the entity's class. Otherwise, it returns the fixed base stats stat set.

UseClassBaseStats

Gets or sets whether to use the base stats from the entity's class. If true, the base stats are taken from the EntityClass. If false, the base stats are taken from the fixed base stats defined in this component.

public bool UseClassBaseStats { get; }

Property Value

bool

Methods

AddFlatModifier(StatSO, long)

Adds a flat modifier to a stat. Dependent stats (those that use stat as a stat-to-stat source) are captured via the reverse index and their old values stored in a stack-allocated or pooled buffer — no per-call dictionary allocation.

public void AddFlatModifier(StatSO stat, long value)

Parameters

stat StatSO

The stat to add the flat modifier to.

value long

The value of the flat modifier.

AddPercentageModifier(StatSO, Percentage)

Adds a Percentage modifier to a stat. Such modifiers consider the base value of the stat, the flat modifiers, and the stat-to-stat modifiers.

public void AddPercentageModifier(StatSO stat, Percentage value)

Parameters

stat StatSO

The stat to add the percentage modifier to.

value Percentage

The value of the percentage modifier.

AddStatToStatModifier(StatSO, StatSO, Percentage)

Adds a stat-to-stat modifier. Such modifiers add a percentage of the source stat to the target stat. Such modifiers consider the base value and the flat modifiers of the source stat.

public void AddStatToStatModifier(StatSO target, StatSO source, Percentage percentage)

Parameters

target StatSO

The target stat.

source StatSO

The source stat.

percentage Percentage

The Percentage of the source stat to add to the target stat.

BeginBulk()

Opens a bulk-update bracket. While the bracket is open, stat-changed events are deferred: each affected stat is recorded in a dirty set with its pre-mutation snapshot, and a single OnStatChanged event (plus callback) is raised per genuinely-changed stat when the outermost bracket disposes. Nested brackets are supported; flush happens only on the outermost dispose.

public EntityStats.BulkUpdateScope BeginBulk()

Returns

EntityStats.BulkUpdateScope

Remarks

Intended for broad mutations such as level-up/down, class swap, or RefundAll cascades. The dirty set and snapshot dictionary are reused across brackets — no per-bracket heap allocation.

ComputeFinalAt(StatSO, int)

Computes the stat's final value as it would be at the specified entity level, without touching the runtime cache. Used to snapshot old/new values around level changes and by any consumer that needs a per-level projection.

public long ComputeFinalAt(StatSO stat, int level)

Parameters

stat StatSO

The stat to compute.

level int

The level at which to evaluate the stat.

Returns

long

The clamped final value at the given level, or 0 if the component is disabled.

Remarks

Pure and cache-free: safe to interleave with Get(StatSO). Disabled components always return 0. Dependent flat values (for stat-to-stat modifiers) are also evaluated at the same level so the cascade stays internally consistent.

Contains(StatSO)

Returns whether stat is tracked by this component's stat set.

public bool Contains(StatSO stat)

Parameters

stat StatSO

Returns

bool

Get(StatSO)

The final value of a stat, considering all the modifiers. Calculation is done in the following order:

1. Base value
   
2. Flat modifiers
   
3. Stat to stat modifiers
   
4. Percentage modifiers
   

public virtual long Get(StatSO stat)

Parameters

stat StatSO

The stat to get the final value of.

Returns

long

The final value of the stat if the component is enabled (clamped to min/max values); otherwise, 0

GetBase(StatSO)

The base value is the value of the stat without any modifiers. If UseClassBaseStats is true, it returns the value from the entity's class. Otherwise, it returns the value from the fixed base stats.

public long GetBase(StatSO stat)

Parameters

stat StatSO

The stat to get the base value of.

Returns

long

The base value of the stat (clamped to the stat's min and max values) if enabled; otherwise, 0

OnLevelDown(EntityLevelChangedContext)

Callback method called when the entity levels down. Symmetric to OnLevelUp(EntityLevelChangedContext): snapshots old values at the pre-change level, invalidates the cache inside a bulk scope, and defers event raising until the bracket closes.

protected virtual void OnLevelDown(EntityLevelChangedContext context)

Parameters

context EntityLevelChangedContext

The context of the level down event.

OnLevelUp(EntityLevelChangedContext)

Callback method called when the entity levels up. Opens a bulk scope, pre-snapshots every stat's final value at the previous level via ComputeFinalAt(StatSO, int), then invalidates the cache so the flush recomputes against the new level. One OnStatChanged event is raised per stat whose value actually changed across the level transition.

protected virtual void OnLevelUp(EntityLevelChangedContext context)

Parameters

context EntityLevelChangedContext

The context of the level up event.

RebuildDependencyIndex()

Forces the reverse dependency indices (attribute -> dependent stats, source stat -> dependent stats) to be rebuilt on the next access. Call after mutating scaling maps or the StatSet at runtime so cascade propagation stays correct.

public void RebuildDependencyIndex()

SetFixed(StatSO, long)

Sets the value of a fixed base stat. This is only applicable when UseClassBaseStats is false.

public void SetFixed(StatSO stat, long value)

Parameters

stat StatSO

The stat to set.

value long

The value to set.

Subscribe<TEvent>(TEvent)

Registers gameEvent on the channel matching TEvent.

public void Subscribe<TEvent>(TEvent gameEvent) where TEvent : ScriptableObject

Parameters

gameEvent TEvent

Type Parameters

TEvent

Exceptions

ArgumentException

Thrown when no channel is registered for TEvent.

TryGet(StatSO, out long)

Tries to get the final value of a stat. Returns true if the stat is contained in the stat set; otherwise, false.

public bool TryGet(StatSO stat, out long value)

Parameters

stat StatSO

The stat to get.

value long

When this method returns, contains the final value of the stat if the stat is contained in the stat set; otherwise, 0.

Returns

bool

true if the stat is contained in the stat set; otherwise, false.

TryGetBase(StatSO, out long)

Tries to get the base value of a stat (before any modifiers are applied). Returns true if the stat is contained in the stat set; otherwise, false.

public bool TryGetBase(StatSO stat, out long value)

Parameters

stat StatSO

The stat to get the base value of.

value long

When this method returns, contains the base value of the stat if the stat is contained in the stat set; otherwise, 0.

Returns

bool

true if the stat is contained in the stat set; otherwise, false.

Unsubscribe<TEvent>(TEvent)

Removes gameEvent from the channel matching TEvent.

public void Unsubscribe<TEvent>(TEvent gameEvent) where TEvent : ScriptableObject

Parameters

gameEvent TEvent

Type Parameters

TEvent

Exceptions

ArgumentException

Thrown when no channel is registered for TEvent.

Events

OnStatChangedCallback

Entity-local C# event raised whenever a stat value changes on this component. Fired alongside OnStatChanged (SO-based) for each stat change. Use this for direct code subscriptions where a ScriptableObject event reference is inconvenient (Currently reserved for future use with EntityModifiers stat-driven max stacks trimming).

public event Action<StatChangeInfo> OnStatChangedCallback

Event Type

Action<StatChangeInfo>