# Stats Stats are numerical values on characters that drive combat and gameplay mechanics. Health, Mana, Strength, Agility, Armor, and Attack Power are all stats. The stat system is one of the most powerful and flexible systems in Spark. ## Creating a Stat Open the Spark Editor, go to **Combat > Stats** and click **Create New**. Each stat entry has: | Field | Description | | -------------------- | --------------------------------------------------------- | | Display Name | Stat name shown in UI (e.g., "Strength"). | | Description | Tooltip text explaining the stat. | | Icon | Sprite for the character sheet. | | Stat Type | Either **Value Stat** or **Resource Stat** (see below). | | Show In UI | Whether the stat appears in the character sheet. | | UI Prefix | Text displayed before the stat value (e.g., "$", "Lv. "). | | UI Suffix | Text displayed after the stat value (e.g., "%", " HP"). | | UI Category | Which UI category this stat belongs to. | | Damage Type Scaling | List of damage type scaling entries for this stat. | | Healing Type Scaling | List of healing type scaling entries for this stat. | | Stat Bonuses | List of bonuses this stat grants to other stats. | ## Stat Types Every stat is one of two types, each with different behavior and properties. ### Value Stats Value stats represent a single number — like Strength, Agility, or Armor. They have one property: `value`. | Field | Description | | ----------------- | ------------------------------------------------ | | Default Value | Starting value for this stat. | | Has Min Value | Whether the stat has a minimum. | | Min Value | Minimum value (if enabled). | | Has Max Value | Whether the stat has a maximum. | | Max Value | Maximum value (if enabled). | | Auto Clamp Values | Automatically clamp the value to min/max bounds. | ### Resource Stats Resource stats have two properties: `current` and `maximum`. They represent depletable resources like Health, Mana, or Stamina. | Field | Description | | ------------------------- | ------------------------------------------------------------- | | Default Maximum | The default maximum value. | | Min Maximum | The minimum the maximum can be reduced to. | | Initialize Current To Max | Whether current starts equal to maximum. | | Default Current | Override starting current value (if not initializing to max). | #### Time-Based Changes (Regeneration / Degeneration) Resource stats can automatically change over time. This is configured per stat: | Field | Description | | ------------------- | -------------------------------------------------------------------------------------------------------------- | | Enable Time Changes | Turn on automatic regeneration or degeneration. | | Disable In Combat | Pause time-based changes while the entity is in combat. | | Change Direction | **Regeneration** (increase over time) or **Degeneration** (decrease over time). | | Change Type | **Fixed Amount** (add/subtract a flat number per tick) or **Percentage** (add/subtract a percentage per tick). | | Change Amount | The amount per tick. | | Percentage Basis | For percentage mode: calculate based on **Current** value or **Maximum** value. | | Change Interval | Seconds between each tick. | For example, you could set Health to regenerate 2% of maximum every 3 seconds, but only out of combat. #### On Value Reached Triggers Resource stats can fire triggers when their current value reaches a specific threshold. This is configured as a list of trigger conditions on the stat: | Field | Description | | --------------- | ---------------------------------------------------------------------------------------------------------------- | | Value | The threshold value to check against. | | Comparison Type | **Equal**, **Not Equal**, **Greater Than**, **Greater Than Or Equal**, **Less Than**, or **Less Than Or Equal**. | | Trigger Entry | The Spark trigger to execute when the condition is met. | | Execute Once | If true, the trigger fires only once. If false, it fires every time the condition is met. | This system enables game mechanics like "when Health reaches 0, execute a death trigger" or "when Mana drops below 10, play a warning effect." ## Stat Modifiers Stat modifiers change stat values temporarily or permanently. Each modifier targets a specific stat and property. | Field | Description | | --------------- | -------------------------------------------------- | | Target Stat | Which stat to modify. | | Target Property | Which property (`value`, `current`, or `maximum`). | | Modifier Type | How the modification is applied (see below). | | Value | The modifier amount. | | Duration | Duration in seconds (0 = permanent until removed). | ### Modifier Types Modifiers are applied in a specific order during stat recalculation: | Type | Priority | Description | | --------------------- | ------------- | -------------------------------------------------------------- | | **Override** | 1st (highest) | Sets the stat to an exact value, ignoring all other modifiers. | | **Additive** | 2nd | Adds a flat amount to the base value. | | **Percentage** | 3rd | Adds a percentage of the base + additive value. | | **Percentage Of Max** | 4th | Adds a percentage of a reference maximum value. | | **Multiplicative** | 5th (lowest) | Multiplies the final result by a factor. | | **Conditional** | Special | Only applies if a condition on another stat is met. | Conditional modifiers let you create effects like "increase Attack Power by 20% while Health is below 30%." Each conditional modifier specifies a condition stat, property, comparison type, and threshold value. ## Stat Bonuses Stats can grant bonuses to other stats. For example, every point of Strength could add 2 points to Attack Power. Bonuses are configured on the source stat entry. Each bonus specifies: | Field | Description | | --------------- | ------------------------------ | | Target Stat | Which stat receives the bonus. | | Target Property | Which property to modify. | | Bonus Type | How the bonus is calculated. | ### Bonus Types | Type | Description | | -------------- | --------------------------------------------------------------------------- | | **Flat** | Each point of the source stat adds a flat amount to the target. | | **Percentage** | Each point of the source stat adds a percentage of the target's base value. | | **Multiplier** | Each point of the source stat multiplies the target by a factor. | | **Formula** | A custom nCalc formula determines the bonus amount. | Bonuses are calculated in this order: flat bonuses first, then percentage, then multiplier, then formula. The final calculation is: `(baseValue + flatBonus) × (1 + percentageBonus/100) × multiplier`. Spark automatically prevents circular dependencies — if stat A gives a bonus to stat B, and stat B gives a bonus to stat A, Spark uses the raw value (without bonuses) of the source stat to avoid infinite loops. ## Damage and Healing Type Scaling Stats can provide scaling bonuses to abilities based on their damage or healing type. Each stat entry has lists for damage type scaling and healing type scaling. See [Damage Types](/documentation/user-guide/plugins/combat/damage-types.md) and [Healing Types](/documentation/user-guide/plugins/combat/healing-types.md) for full details. ## UI Categories UI categories organize stats into groups in the character sheet. Create them in **Combat > Stats > UI Categories**. Each category has a display name and a sort order (lower numbers display first). Examples: "Primary Attributes," "Defensive Stats," "Offensive Stats." ## Stat Templates Stat templates bundle a set of stat values into a reusable configuration. Create them in **Combat > Stats > Templates**. Each template defines a list of stat configurations: | Field | Description | | ------------- | ------------------------------------------- | | Stat Entry | Which stat. | | Value | Initial value (for value stats). | | Current Value | Initial current value (for resource stats). | | Maximum Value | Initial maximum value (for resource stats). | Assign a stat template to a character entry to give them a starting stat profile. For example, a "Warrior Template" might have high Strength and Health, while a "Mage Template" has high Intelligence and Mana. ## Stat Entity Add a **StatEntity** component to a character's GameObject to give them stats. | Field | Description | | ------------------------- | ----------------------------------------------------------------------------- | | Auto Initialize All Stats | Automatically create instances for every stat in the database. | | Stat Entries | Manual list of specific stats this entity has (if not using auto-initialize). | | Enable Time Based Changes | Enable regeneration and degeneration for resource stats. | | Pause When Disabled | Pause time-based changes when the GameObject is disabled. | The StatEntity manages all stat instances at runtime, handles modifier application and removal, processes time-based changes, checks on-value-reached triggers, and caches calculated values with bonuses for performance. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.sparkframework.dev/documentation/user-guide/plugins/combat/stats.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.