> 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-status-effect-system/core-concepts.md). # Core Concepts The Roo Status Effect System manages temporary or persistent gameplay effects applied to an Actor. Status Effects can be used to create: * Attribute increases or reductions * Periodic damage * Periodic healing * Temporary Stat changes * Shields * Movement restrictions * Combat states * Gameplay markers Each Status Effect is stored as a reusable Data Asset and identified by a Gameplay Tag. ### Status Effect Tag Every Status Effect requires a unique Gameplay Tag. When a Status Effect is created through the Stats Designer, its tag is generated automatically from its entry name and category path. All Status Effect Tags are created under: ``` .Stats.StatusEffect ``` Examples: ``` MyProject.Stats.StatusEffect.Bleeding MyProject.Stats.StatusEffect.Poison MyProject.Stats.StatusEffect.Haste MyProject.Stats.StatusEffect.Shield ``` Categories create additional levels in the tag path. ``` MyProject.Stats.StatusEffect.Damage.Bleeding MyProject.Stats.StatusEffect.Damage.Poison MyProject.Stats.StatusEffect.Support.Haste ``` The Ultimate Stats Framework Component uses this tag to find the corresponding Status Effect Data Asset at runtime. ### Type `Type` classifies the Status Effect for gameplay logic and UI filtering. The available options are: #### Neutral A Status Effect that is neither positive nor negative. Use `Neutral` for states, markers, or gameplay effects that should not be treated as a benefit or penalty. Examples: ``` Combo Window Stealth State Interaction State Quest State Gameplay Marker ``` #### Positive A Status Effect that is beneficial to the affected Actor. This is commonly called a Buff, but the actual Type option is named `Positive`. Examples: ``` Attack Increase Movement Speed Increase Shield Health Regeneration Mana Regeneration ``` #### Negative A Status Effect that is harmful to the affected Actor. This is commonly called a Debuff, but the actual Type option is named `Negative`. Examples: ``` Bleeding Poison Burning Slow Stun ``` `Type` only classifies the Status Effect. It does not automatically create any gameplay behavior. The actual behavior is defined by its Actions and lifecycle events. ``` Type = Negative ``` This does not automatically deal damage. A Tick Action must still be configured to reduce Health. Type can also be used with: ``` Clear Status Effects By Type ``` For example, clearing `Negative` effects removes all active Status Effects whose Type is set to `Negative`. ### Max Stack `Max Stack` defines the maximum number of active stacks that the Status Effect can hold. ``` Max Stack = 1 ``` Only one stack can be active. ``` Max Stack = 3 ``` Up to three stacks can be active. If the evaluated Max Stack is `0` or lower, the Status Effect cannot be added. #### Max Stack Value Source Max Stack can use one of three value sources. **Constant** Uses a fixed number. ``` Source = Constant Constant Value = 3 ``` The Status Effect can hold three stacks. **Stat** Reads the value of a Stat from the affected Actor. ``` Source = Stat Stat Tag = MyProject.Stats.Stat.BleedingResistance ``` The resulting value is converted to an integer and used as the maximum stack count. **Formula** Calculates the maximum stack count from a Formula Data Asset. ``` Source = Formula Formula = DA_Formula_BleedingMaxStack ``` The Formula result is converted to an integer. ### Overflow Policy `Overflow Policy` determines what happens when a new stack is added after the Status Effect has reached Max Stack. The available options are: #### Reject New Stack The new stack is rejected. The existing stacks and their timers remain unchanged. ``` Current Stack Count = 3 Max Stack = 3 Add another stack ↓ Stack Count remains 3 ``` No Add Actions or `On Add` event run for the rejected stack. #### Refresh Duration Only The system does not add another stack. Instead, it refreshes an existing duration and broadcasts `On Status Effect Refreshed`. For Shared Duration, the shared timer is refreshed. For Independent Per Stack, the timer of the most recently added stack is refreshed. ``` Current Stack Count = 3 Max Stack = 3 Add another stack ↓ Stack Count remains 3 Duration is refreshed ``` This option does not run Add Actions or `On Add`. #### Replace Oldest Stack The oldest stack is removed before the new stack is added. ``` Current Stack Count = 3 Max Stack = 3 Add another stack ↓ Remove the oldest stack ↓ Add the new stack ↓ Stack Count remains 3 ``` Removing the oldest stack runs its removal lifecycle. The new stack then runs its normal addition lifecycle. ### Has Duration `Has Duration` determines whether the Status Effect expires automatically. #### Disabled ``` Has Duration = false ``` The Status Effect has no automatic expiration time. It remains active until it is removed through gameplay logic. #### Enabled ``` Has Duration = true Duration = 5 ``` The Status Effect expires after its configured duration. Enabling this option also displays the Duration Mode settings. ### Duration `Duration` defines how long the Status Effect remains active. ``` Duration = 5 ``` The duration is five seconds. Duration can use one of three value sources. #### Constant Uses a fixed duration. ``` Source = Constant Constant Value = 5 ``` #### Stat Reads the duration from a Stat on the affected Actor. ``` Source = Stat Stat Tag = MyProject.Stats.Stat.EffectDuration ``` #### Formula Calculates the duration from a Formula Data Asset. ``` Source = Formula Formula = DA_Formula_BleedingDuration ``` The Duration value is evaluated when the stack is added. ### Duration Mode `Duration Mode` determines whether every stack has its own timer or all stacks share one timer. The available options are: #### Independent Per Stack Each stack stores its own Start Time and Duration. ``` Stack 1 = 2 seconds remaining Stack 2 = 4 seconds remaining Stack 3 = 5 seconds remaining ``` Each stack expires independently. Use this for effects where every application should have its own lifetime. Examples: ``` Bleeding Poison Burning Stackable Damage-over-Time ``` When using Independent Per Stack, the `Display Progress Policy` option becomes available. #### Shared By All Stacks All active stacks use one shared Start Time and Duration. ``` Stack Count = 3 Shared Duration = 5 seconds ``` The complete Status Effect group is controlled by one timer. Use this for effects that behave as one state with multiple stack levels. Examples: ``` Shield Charges Combo Stacks Attack Boost Stacks Shared Aura Effects ``` When using Shared By All Stacks, the following options become available: ``` Duration Refresh Policy Expiration Policy ``` ### Duration Refresh Policy This setting is available when Duration Mode is `Shared By All Stacks`. It determines whether adding a new stack refreshes the shared duration. #### Never Refresh Adding a stack does not change the current shared timer. ``` Time Remaining = 2 seconds Add a stack ↓ Time Remaining = 2 seconds ``` #### Refresh On Add Adding a stack restarts the shared duration. ``` Time Remaining = 2 seconds Configured Duration = 5 seconds Add a stack ↓ Time Remaining = 5 seconds ``` This setting applies while the effect is still below Max Stack. When Max Stack has already been reached, `Overflow Policy` controls what happens. ### Expiration Policy This setting is available when Duration Mode is `Shared By All Stacks`. It determines what happens when the shared duration expires. The available options are: #### Remove Expired Stack This option exists in the current configuration. Because every stack shares the same expiration timer, the current runtime implementation clears all active stacks when the shared duration expires. In the current implementation, this produces the same result as `Clear Entire Stack`. #### Clear Entire Stack Removes every active stack when the shared duration expires. ``` Stack Count = 3 Shared Duration expires ↓ Stack Count = 0 ``` Each removed stack runs its removal lifecycle. #### Remove One And Refresh Duration Removes the oldest stack when the shared duration expires. If stacks remain, the shared duration is restarted. ``` Stack Count = 3 Shared Duration expires ↓ Stack Count = 2 ↓ Shared Duration restarts ``` This repeats until no stacks remain. ### Display Progress Policy This setting is available when Duration Mode is `Independent Per Stack`. It determines which stack is represented by the single-effect UI functions: ``` Get Status Effect Display Remaining Time Get Status Effect Display Progress ``` The available options are: #### Next Stack Expiration Uses the stack with the shortest remaining duration. ``` Stack 1 = 2 seconds remaining Stack 2 = 4 seconds remaining Stack 3 = 5 seconds remaining Displayed Time = 2 seconds ``` Use this when the UI should show when the next stack will disappear. #### Entire Effect Lifetime Uses the stack with the longest remaining duration. ``` Stack 1 = 2 seconds remaining Stack 2 = 4 seconds remaining Stack 3 = 5 seconds remaining Displayed Time = 5 seconds ``` Use this when one UI icon should remain active until the final stack expires. Shared-duration effects always display their shared timer, so Display Progress Policy is not required for them. ### Tick Interval `Tick Interval` defines how often Tick Actions execute. ``` Tick Interval = 1.0 ``` Tick Actions execute every second. ``` Tick Interval = 0.0 ``` Periodic execution is disabled. Use Tick Actions for effects such as: ``` Bleeding Damage Poison Damage Health Regeneration Mana Regeneration Periodic Shield Loss ``` ### Tick Execution Policy This setting is available when Tick Interval is greater than `0`. It determines how periodic Actions are executed when multiple stacks are active. The available options are: #### Once Per Stack Every stack uses its own Tick timer. Each stack executes `On Tick` and Tick Actions independently. ``` Stack Count = 3 Damage Per Stack = 3 Each completed stack Tick: Health -3 ``` Because the stacks have independent timers, they may Tick at different times. #### Once Per Effect The complete Status Effect group uses one shared Tick timer. `On Tick` and Tick Actions execute once per interval, regardless of the number of stacks. ``` Stack Count = 3 Damage = 3 Each Tick: Health -3 ``` Stack count does not multiply the Tick Action. The Source ID from the first active stack is used for the Tick execution. #### Once Per Stack, Shared Period All stacks use one shared Tick timer. When the shared interval is reached, every active stack executes `On Tick` and Tick Actions once. ``` Stack Count = 3 Damage Per Stack = 3 Each Shared Tick: Health -3 Health -3 Health -3 Total = 9 damage ``` This option is useful when every stack should contribute to the result, but all stacks should Tick at the same time. ### Period Reset Policy This setting is available when Tick Interval is greater than `0`. It determines whether adding a stack restarts the existing Tick schedule. The available options are: #### Never Reset Adding a stack does not reset the Tick timers of existing stacks. Existing stacks keep their current Tick schedule. A newly created independent stack starts with its own new Tick timer. #### Reset On Add Adding a stack resets the Tick timer for the entire Status Effect group and all active stacks. ``` Time Until Next Tick = 0.2 seconds Add a stack ↓ Tick timer restarts ``` Use this when adding a stack should delay the next Tick. ### Hidden `Hidden` is an optional configuration flag. ``` Hidden = true ``` The Status Effect can be marked as internal or hidden for supported editor and UI workflows. In the current runtime implementation, this flag does not disable the Status Effect and does not prevent it from being added, updated, or removed. ### Action Lists A Status Effect contains three Action lists: ``` Add Actions Tick Actions Remove Actions ``` #### Add Actions Run when a new stack is successfully added. Example: ``` Add Modifier Target Tag = MyProject.Stats.Stat.MoveSpeed Value = 20 ``` #### Tick Actions Run whenever the configured Tick Interval is reached. Example: ``` Change Value Target Tag = MyProject.Stats.Attribute.Health Value = -3 ``` #### Remove Actions Run when a stack is removed manually, replaced, cleared, or expired. Example: ``` Remove Modifier Target Tag = MyProject.Stats.Stat.MoveSpeed Value = 20 ``` ### Action Type Each Action has an `Action Type`. The available options are: #### Change Base For a Stat target, adds the configured value to the Stat's Base Value. For an Attribute target, adds the configured value to its current value. #### Change Value For a Stat target, adds the configured value to its calculated value and writes the result back as its Base Value. For an Attribute target, adds the configured value to its current value. Use this for periodic damage and healing. ``` Target Tag = MyProject.Stats.Attribute.Health Value = -3 ``` #### Set Value Sets the target to the configured value. For a Stat, the value is written to its Base Value. For an Attribute, the value becomes its current value and is clamped to its valid range. #### Add Modifier Adds a Modifier to a Stat. This Action only works when Target Tag identifies a Stat. When Modifier Channel Tag is empty, the Action creates a Constant Modifier. #### Remove Modifier Removes one matching Modifier from a Stat. This Action only works when Target Tag identifies a Stat. The Target Tag, Modifier Channel, and Value should match the Modifier that was previously added. ### Target Tag `Target Tag` selects the Stat or Attribute affected by an Action. Examples: ``` MyProject.Stats.Stat.MoveSpeed MyProject.Stats.Stat.Attack MyProject.Stats.Attribute.Health MyProject.Stats.Attribute.Mana ``` The selected Action Type determines whether the Target Tag must identify a Stat or may identify either a Stat or Attribute. ### Action Value Type Action values provide two visible options: #### Constant Number Uses a fixed number. ``` Value Type = Constant Number Number = -3 ``` #### Constant Formula Calculates the Action value from a Formula Data Asset. ``` Value Type = Constant Formula Formula = DA_Formula_BleedingDamage ``` The Formula is evaluated against the Actor receiving the Status Effect. ### Modifier Channel Tag `Modifier Channel Tag` is used by `Add Modifier` and `Remove Modifier`. Leave it empty to use a standard Constant Modifier. Select a channel when the Modifier should use a custom calculation channel from the Stat Calculation Profile. ### Lifecycle Order A successfully added stack follows this order: ``` On Add ↓ Add Actions ↓ On Status Effect Added ``` A periodic execution follows this order: ``` On Tick ↓ Tick Actions ↓ On Status Effect Ticked ``` Removing one stack follows this order: ``` On Remove ↓ Remove Actions ↓ On Status Effect Removed ``` When a duration ends naturally, the removal lifecycle runs first. The component then broadcasts: ``` On Status Effect Expired ``` When `Refresh Duration Only` handles an overflow, no new stack is created. The component broadcasts: ``` On Status Effect Refreshed ``` ### Source ID Every active stack stores a Source ID. The Source ID identifies what applied that stack. Examples: ``` Skill_BleedingStrike Weapon_PoisonSword Enemy_Spider Item_HastePotion ``` If no Source ID is provided, the system generates a unique Source ID automatically. Source IDs allow different applications of the same Status Effect to keep their runtime changes separate. ### Example: Bleeding ``` Status Effect Tag: MyProject.Stats.StatusEffect.Bleeding Type: Negative Max Stack: 3 Has Duration: true Duration: 5 Duration Mode: Independent Per Stack Overflow Policy: Replace Oldest Stack Tick Interval: 1 Tick Execution Policy: Once Per Stack Period Reset Policy: Never Reset ``` Tick Action: ``` Action Type: Change Value Target Tag: MyProject.Stats.Attribute.Health Value Type: Constant Number Number: -3 ``` Result: ``` 1 Stack = 3 damage per second 2 Stacks = 6 damage per second 3 Stacks = 9 damage per second ```