> For the complete documentation index, see [llms.txt](https://malbersanimations.gitbook.io/animal-controller/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://malbersanimations.gitbook.io/animal-controller/global-components/stats/stat-modifiers.md). # Stat Modifier Last updated AC v1.5.3 ## Overview **Stat Modifier** is a serializable struct that describes **one change to one Stat**. Almost everything in the framework that touches a Stat uses it: Damagers, Projectiles, Explosions, Stat Reactions, AI Tasks, Super Item Processors, and the Modify Stat component. A Stat Modifier answers two questions: * **What changes** — the **Target** Stat and the **Stat Option** applied to it. * **Which number is used** — either a plain **Value**, or a **Source** expression built from other Stats. ``` Stat Modifier ├── Target ─────────── the Stat that changes, on the Stats being modified ├── Stat Option ────── how it changes (Subtract, Add, Set, Regenerate…) └── Value From ├── Use Value ──── a random roll between Min and Max └── Use Sources ── an expression built from Stats and numbers ├── Source Stats ── the Stats component the terms are read from └── Terms ───────── Attack + [20-30] x Charge - Durability ``` {% hint style="info" %} **Coming from an older version?** The modifier used to expose a single **Source** Stat plus a **Source Part**. That pair is now the **first term** of the Sources list. Existing assets are migrated automatically the first time the modifier is drawn in the Inspector — there is nothing to re-author. {% endhint %} ## Parameters

#### Target The **Stat ID** that will be modified on the Stats component receiving the modifier. E.g. **Health** on the character being damaged. #### Stat Option What to do to the Target Stat. See **Stat Options** below. #### Value From Where the number applied by the Stat Option comes from.

Option	Description
Use Value	A random value between Min and Max. Set both to the same number for a fixed amount.
Use Sources	The value is calculated from the Source expression — one or more Stats and static numbers combined with operators.

#### Min / Max Shown when **Value From** is set to **Use Value**. The modifier rolls a random number in that range every time it is applied. #### Enable Replaces Min/Max when the Stat Option is **Enable** or **Immune**, since those options take a true/false instead of a number. ## Source Expression

When **Value From** is set to **Use Sources**, the value is built from a list of **terms**. This is how a weapon deals damage based on its own **Attack** Stat instead of a hard-coded number. \[Insert Image - the Source list: header with the Stats slot and the formula, and three term rows] {% hint style="warning" %} The list is evaluated **top to bottom, with no operator precedence**. The row order *is* the math order — `x` does **not** bind tighter than `+`. The header prints the resulting formula with parentheses so the real grouping is always visible. {% endhint %} Three rows reading `Attack`, `+ 30`, `x Charge` are evaluated as: ``` (Attack + 30) x Charge ``` Not as `Attack + (30 x Charge)`. To get that grouping, reorder the rows. ### Term Each row of the list is one term.

Field	Description
Operator	How the term combines with the result of the rows above it.
Use Value / Use Stat	Whether the term is a static number or a value read from a Stat.
Stat	The Stat the term reads, when set to Use Stat. E.g. the weapon's Attack.
Source Part	Which number of that Stat is used.
Min / Max	The static range rolled by the term, when set to Use Value.

The **first** term has nothing above it to combine with: it seeds the expression. Its operator only offers `+` and `-`, where `-` starts the expression at a negative value. ### Operators

Symbol	Operator	Result
`+`	Add	`result + value`
`-`	Substract	`result - value`
`x`	Multiply	`result x value`
`/`	Divide	`result / value` — skipped when the value is 0, so it can never divide by zero.
`+%`	Add Percent	`result + (result x value%)`. A value of `15` means +15%.
`-%`	Substract Percent	`result - (result x value%)`. A value of `15` means -15%.
`^`	Clamp Min	Floor: the result can never go below the value.
`v`	Clamp Max	Ceiling: the result can never go above the value.

### Source Part Which number of a Stat the term reads.

Part	Description
Value	The current runtime value of the Stat.
Min Value	The Stat's minimum value.
Max Value	The Stat's maximum value.
Random [Min-Max]	A random value inside the Stat's own range.
Normalized	The Stat's value divided by its Max Value, so a 0-1 number. Ideal as a multiplier — e.g. a Charge Stat scaling the damage.

### Source Stats The **Stats** component slot in the **Source** header. It is the component every **Use Stat** term reads from. Leave it **empty** to use the Stats the caller provides:

Used by	Stats provided
MDamager, MAttackTrigger, MExplosion	The Owner of the damager — the character swinging the weapon.
Super Item Processors (Damager, Projectile)	The Item's own Stats component, sitting next to the Super Item.
Modify Stat component	None. Assign Source Stats explicitly if the modifier uses Stat terms.

Assign it to read the terms from a specific character or item instead. An assigned component always wins over the one the caller provides. {% hint style="info" %} A component reference cannot cross a prefab/scene boundary. On a prefab, **Source Stats** must point at a Stats component on that same prefab — otherwise leave it empty and let the caller supply it. {% endhint %} ### Example A charged bow whose damage grows with the draw, plus a flat bonus, reduced by the bow's wear:

Row	Operator	Term	Running result
1	`+`	Attack (Value)	`20`
2	`+`	[20-30]	`20 + 25 = 45`
3	`x`	Charge (Normalized)	`45 x 0.8 = 36`
4	`-`	Durability (Value)	`36 - 5 = 31`

The header prints it as `(Attack + [20-30]) x Charge.Normalized - Durability`, and 31 is subtracted from the target's **Health**. ## Stat Options Actions to do to the Stat. The menu is grouped by the part of the Stat it touches.

### Value

Option	Description
Value/Add [+]	Adds the modifier value to the Stat's Value.
Value/Set	Sets the Stat's Value to the modifier value.
Value/Substract [-]	Substracts the modifier value from the Stat's Value. This is what damage uses.
Value/Reset	Resets the Stat to its Reset To value.
Value/Reduce by percent	Reduces the Stat's Value by the modifier value, read as a percent.
Value/Increase by percent	Increases the Stat's Value by the modifier value, read as a percent.
Value/Reset to Max	Resets the Stat to its maximum value.
Value/Reset to Min	Resets the Stat to its minimum value.
Value/Default	Restores the Value to the default it was authored with.

### Max Value / Min Value

Option	Description
Max Value/Modify	Adds or removes the modifier value from the Stat's Max Value.
Max Value/Set	Sets the Stat's Max Value to the modifier value.
Max Value/Default	Restores the Max Value to the default it was authored with.
Min Value/Default	Restores the Min Value to the default it was authored with.

### Degenerate / Regenerate

Option	Description
Degenerate/Value	Enables the Degeneration and sets the Degenerate Rate to the modifier value. A value of 0 leaves the rate untouched.
Degenerate/Start	Starts the Degeneration without changing the rate.
Degenerate/Stop	Stops the Degeneration.
Degenerate/Default	Restores the Degeneration to its default.
Regenerate/Value	Enables the Regeneration and sets the Regenerate Rate to the modifier value. A value of 0 leaves the rate untouched.
Regenerate/Start	Starts the Regeneration without changing the rate.
Regenerate/Stop	Stops the Regeneration.
Regenerate/Default	Restores the Regeneration to its default.

### Multiplier

Option	Description
Multiplier/Set	Sets the Stat's multiplier to the modifier value.
Multiplier/Modify	Adds or removes the modifier value from the Stat's multiplier.
Multiplier/Default	Restores the multiplier to the default it was authored with.

### Enable / Immune

Option	Description
Enable	Enables or disables the Stat, using the Enable toggle instead of a number.
Immune	Makes the Stat immune, so Add, Set and Substract can no longer alter it.

{% hint style="info" %} An **Immune** Stat still accepts every other option — only **Value/Add**, **Value/Set** and **Value/Substract** are blocked. {% endhint %}