> For the complete documentation index, see [llms.txt](https://roogame.gitbook.io/roogame/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://roogame.gitbook.io/roogame/roo-gameplay-framework/core-concepts/stats-attributes-and-runtime-ownership.md).

# Stats, Attributes and Runtime Ownership

Roo Gameplay Framework separates calculated values from current resources.

## Stats

A Stat is a value such as MaxHealth, AttackPower, Defense, Level, or MoveSpeed.

A Stat Data Asset defines:

* StatTag
* BaseValue
* Optional Formula
* Hidden flag

At runtime, Roo Stats Component stores the Stat's base value and modifiers. The final value is calculated when queried.

Calculation order:

```
Formula result or Base Value
+ Constant modifiers
then Percent modifiers
= Final Stat Value
```

Percent modifiers use numeric ratios. For example, 0.25 means plus 25 percent. User-facing percentages in your UI may still be represented as whole numbers when that is your project convention; document that convention consistently.

## Attributes

An Attribute is a current resource such as Health or Mana.

An Attribute Data Asset defines:

* AttributeTag
* MinValue
* MaxStat
* StartPercent
* Hidden flag

The maximum is read from the explicitly assigned MaxStat asset. The current value is clamped between MinValue and the calculated maximum.

Initialization:

```
Attribute Value = Min + (Max - Min) * StartPercent
```

Stats initialize before Attributes, allowing an Attribute to read its configured MaxStat during startup.

## Stats Sets

A Stats Set groups the Stat and Attribute definitions owned by one component. Assign a Stats Set to Roo Stats Component through Stat Value Config.

One Actor can use one Roo Stats Component with one active Stats Set configuration. Calling Set Stat Value Config replaces the configuration and reinitializes runtime state.

## Runtime ownership

Runtime bases, current Attribute values, modifiers, and active Status Effects belong to the component instance. Editing a Data Asset changes configuration, not an already-running component unless you explicitly reinitialize it.

Reinitialize Stats clears current runtime Stats, Attributes, modifiers, and Status Effects, then rebuilds them from Stat Value Config.

## Events

Use component delegates to update UI and game logic:

* On Stat Changed
* On Attribute Changed
* On Modifier Added
* On Modifier Removed
* On Status Effect Added
* On Status Effect Removed
* On Status Effect Refreshed

Prefer events for UI updates instead of polling every frame.