> For the complete documentation index, see [llms.txt](https://morningheartgames.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/subsystems/modifiers-magnitudes.md).

# Modifiers and Magnitudes

> Online doc: <https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/subsystems/modifiers-magnitudes?fallback=true>

Modifiers are the numeric instructions inside costs and effects. Magnitudes decide how large each modifier is at runtime.

![Practical modifier magnitude diagram showing several value sources feeding one calculation.](/files/UJzZPnuBEwu7RJJ2giFv)

## What It Does

| Type                                 | Responsibility                                                             |
| ------------------------------------ | -------------------------------------------------------------------------- |
| `Modifier`                           | Authoring-time target attribute, operation, and magnitude source.          |
| `ModifierSpec`                       | Runtime resolved modifier attached to an effect spec or instant execution. |
| `ModifierOperation`                  | The operation applied to the attribute.                                    |
| `ModifierMagnitude`                  | Serialized magnitude strategy wrapper.                                     |
| `IModifierMagnitudeCalculator`       | Runtime strategy interface for custom magnitude calculation.               |
| `ModifierMagnitudeCalculatorFactory` | Registry for calculator creators.                                          |
| `ModifierMagnitudeCalContext`        | Source/target/effect context used during calculation.                      |

## When To Use It

Use modifiers when an effect or ability cost needs to change an attribute:

* Subtract 20 Health.
* Add 10 Armor while a shield buff is active.
* Multiply movement speed during a slow.
* Scale damage by level.
* Read an attacker attribute and apply it to a defender attribute.
* Use set-by-caller values passed through an effect application.

## Editor Setup

1. Open or create an `EffectDefinition` or `AbilityDefinition`.
2. In the Inspector, find `Modifiers` for effects or `Costs` for abilities.
3. Add a modifier row.
4. Choose the target `AttributeId`.
5. Choose the operation.
6. Choose the magnitude source.
7. Enter level values, attribute capture fields, or set-by-caller names depending on the selected magnitude type.
8. Enter Play Mode and inspect the ASC `Attributes` and `Effects` tabs.

## Magnitude Sources

| Source               | Types                                                      | Use case                                                        |
| -------------------- | ---------------------------------------------------------- | --------------------------------------------------------------- |
| Constant/level-based | `LevelBasedFloat`, `LevelBasedMagnitudeCalculator`         | Values that scale by ability/effect level.                      |
| Attribute-based      | `AttributeBasedFloat`, `AttributeBasedMagnitudeCalculator` | Damage from Attack, healing from SpellPower, armor mitigation.  |
| Set-by-caller        | `SetByCallerFloat`, `SetByCallerMagnitudeCalculator`       | Runtime values supplied by code, hit data, or external systems. |
| Custom calculator    | `IModifierMagnitudeCalculator`                             | Complex formulas not covered by built-in strategies.            |

## Modifier Operations

Use the operation that matches your design intent:

| Operation style          | Typical use                                                             |
| ------------------------ | ----------------------------------------------------------------------- |
| Additive                 | Damage, healing, armor bonus, resource gain.                            |
| Multiplicative           | Speed multipliers, damage multipliers, global buffs.                    |
| Override-like operations | Temporary hard-set values, if supported by the selected operation enum. |

Always test combined effects. Modifier order matters when additive and multiplicative operations stack.

## Runtime Flow

```mermaid
flowchart TD
    Effect["EffectDefinition modifiers"] --> Spec["EffectSpec"]
    Spec --> Context["ModifierMagnitudeCalContext"]
    Context --> Magnitude["Resolve magnitude"]
    Magnitude --> ModifierSpec["ModifierSpec"]
    ModifierSpec --> RuntimeAttrs["RuntimeAttributes"]
    RuntimeAttrs --> Order["Apply operation order"]
    Order --> Clamp["Clamp"]
    Clamp --> Events["Attribute events"]
```

## Attribute-Based Magnitudes

Use attribute-based magnitudes when the value depends on source or target state. Examples:

| Formula need                     | Source attribute      | Target attribute |
| -------------------------------- | --------------------- | ---------------- |
| Weapon damage affects Health     | Source `Attack`       | Target `Health`  |
| Armor reduces damage             | Target `Armor`        | Target `Health`  |
| Healing scales with caster power | Source `HealingPower` | Target `Health`  |

Confirm the source and target ASCs are resolved in the `EffectApplicationRequest`. Missing source or target attributes make the calculation fail or fall back depending on the calculator.

## Set-By-Caller Magnitudes

Set-by-caller is useful when an ability computes a value at runtime:

* Charged ability amount.
* Hit location damage multiplier.
* Combo index.
* Game Creator event payload value.
* Projectile travel-time scaling.

Use stable data names. If multiple systems write set-by-caller values, document the names in the ability or effect description.

## Custom Magnitude Calculator

1. Implement `IModifierMagnitudeCalculator`.
2. Read source/target/effect context from `ModifierMagnitudeCalContext`.
3. Register the calculator with `ModifierMagnitudeCalculatorFactory.RegisterCalculatorCreator()`.
4. Add tests for normal values, missing attributes, and invalid context.
5. Expose only the fields designers need.

## Debugging Checklist

* If a modifier has no effect, confirm the target attribute exists on the target ASC.
* If a cost never passes, inspect `RuntimeAttributes.CanApplyAttributeModifiers`.
* If a value is wrong by level, inspect the level used when applying the effect or granting the ability.
* If source-based damage is zero, confirm `instigatorASC` is present in the application request.
* If a set-by-caller value is zero, confirm the data name exactly matches.
* If stacked modifiers look wrong, isolate additive and multiplicative effects in a small test scene.

## Common Mistakes

| Mistake                                                      | Result                       | Fix                                    |
| ------------------------------------------------------------ | ---------------------------- | -------------------------------------- |
| Using target attributes when source attributes were intended | Damage reads defender stats  | Check capture side.                    |
| Hard-coding values in runtime code instead of effect assets  | Designers cannot tune values | Put tunable numbers in modifiers.      |
| Reusing one data name for unrelated set-by-caller values     | Values collide conceptually  | Prefix names by feature.               |
| Not testing combined modifiers                               | Final value surprises users  | Add focused tests or a cookbook scene. |

## Examples and Tests

* Cookbook: [Damage With Armor Mitigation](/docs/gameplay-ability-toolkit/build-with-it/07-cookbook.md#damage-with-armor-mitigation).
* Tests: `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/ModifierMagnitudeTests.cs`, `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Attributes/ModifierMagnitudeDeepContractTests.cs`, `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Attributes/AttributeModifierTagDeepTests.cs`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/subsystems/modifiers-magnitudes.md?ask=<question>
```

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.