> 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/ultimate-stats-framework/creating-your-attribute-system/core-concepts.md).
# Core Concepts
The Roo Attribute System separates values that describe an entity from values that change during gameplay.
For example, a character may have a maximum health value of `100`, while their current health changes from `100` to `75` after taking damage.
```
Stat: HealthMax = 100
Attribute: Health = 75 / 100
```
This separation makes it easier to build combat, healing, equipment, buffs, UI bars, and progression systems.
#### Stat
A **Stat** is a calculated value that describes an entity.
Stats are commonly used for values such as:
* Attack
* Defense
* Max Health
* Max Mana
* Movement Speed
* Experience
* Level
* Critical Chance
A Stat has a base value and can optionally be calculated by a Formula.
```
Attack = 10
HealthMax = 100
MoveSpeed = 600
```
Stats are usually used as inputs for other gameplay systems.
For example:
```
Damage = Attacker Attack - Target Defense
Health Attribute Max Value = HealthMax Stat
```
#### Attribute
An **Attribute** is a runtime resource value.
Attributes are commonly used for values such as:
* Current Health
* Current Mana
* Current Stamina
* Current Shield
* Current Energy
Unlike a Stat, an Attribute has a current value, a minimum value, and a maximum value.
```
Health = Current Value / Maximum Value
Health = 75 / 100
```
The maximum value of an Attribute is usually provided by a Stat.
```
Health Attribute
Min Value: 0
Max Stat: HealthMax
```
This means the Health Attribute automatically uses the current value of the `HealthMax` Stat as its upper limit.
#### Stat and Attribute Relationship
A Stat and an Attribute often work together.
```
HealthMax Stat
↓
Health Attribute Maximum Value
↓
Current Health Value
```
Example:
```
HealthMax = 100
Health = 75 / 100
```
If an equipment modifier increases `HealthMax` to `150`, the Health Attribute maximum value also becomes `150`.
```
HealthMax = 150
Health = 75 / 150
```
The current Attribute value is clamped when it exceeds the new maximum value.
```
Before: Health = 120 / 150
HealthMax changes to 100
After: Health = 100 / 100
```
Changing a maximum Stat does not automatically restore the Attribute to full value.
```
Before: Health = 75 / 100
HealthMax changes to 150
After: Health = 75 / 150
```
If you want the character to recover health after increasing `HealthMax`, modify the Health Attribute separately.
#### Current Value and Maximum Value
Use an Attribute when the value is expected to change frequently during gameplay.
```
Taking damage → Modify Health
Healing → Modify Health
Casting a spell → Modify Mana
Sprinting → Modify Stamina
```
Use a Stat when the value represents a calculated capability or limit.
```
Equipping a sword → Modify Attack
Leveling up → Modify HealthMax
Applying a slow effect → Modify MoveSpeed
```
A useful rule is:
> Modify an Attribute for resource changes. Modify a Stat for capability or limit changes.
#### Data Assets and Runtime Values
The system uses Data Assets to define reusable configurations.
```
Stat Data Asset
Defines a Stat, such as Attack or HealthMax.
Attribute Data Asset
Defines an Attribute, such as Health or Mana.
Stat Value Data Asset
Groups multiple Stats and Attributes into one character configuration.
```
For example, a player character and an enemy can use the same `Health` Attribute definition while having different maximum health values.
```
Player HealthMax = 100
Enemy HealthMax = 300
```
At runtime, `RooStatsComponent` creates independent values for each owner.
This means changing one character's Health does not affect another character's Health.
```
Player Health = 75 / 100
Enemy Health = 300 / 300
```
#### Gameplay Tags
Each Stat and Attribute is identified by a Gameplay Tag.
Example tags:
```
RooGame.Stats.Stat.Attack
RooGame.Stats.Stat.HealthMax
RooGame.Stats.Attribute.Health
RooGame.Stats.Attribute.Mana
```
Gameplay Tags allow gameplay code and Blueprints to access values without requiring direct references to individual Data Assets.
For example:
```
GetAttributeValueByTag(RooGame.Stats.Attribute.Health)
ModifyAttributeValueByTag(
RooGame.Stats.Attribute.Health,
-10
)
```
#### Attribute Ratio
An Attribute Ratio represents the current value as a percentage of its maximum value.
```
Ratio = Current Value / Maximum Value
```
Example:
```
Health = 75 / 100
Health Ratio = 0.75
```
This is useful for UI.
```
Health Ratio → Progress Bar Percent
Mana Ratio → Progress Bar Percent
```
#### Example: Health System
A basic Health system can be defined as follows:
```
Stat:
RooGame.Stats.Stat.HealthMax
Base Value = 100
Attribute:
RooGame.Stats.Attribute.Health
Min Value = 0
Max Stat = HealthMax
Start Percent = 1
```
When the character is created:
```
Health = 100 / 100
```
After taking 25 damage:
```
Health = 75 / 100
```
After receiving 10 healing:
```
Health = 85 / 100
```
After equipping an item that adds 50 maximum health:
```
HealthMax = 150
Health = 85 / 150
```
