How-To: Create and Equip an Augment

Goal: make a data asset that changes one ability - more damage, an extra target, a chance to refund cooldown - and equip it onto a single ability spec at runtime.

Prerequisites

Quick Start, and How-To: Get the Building Blocks step 3.

What an augment is

An augment attaches to one ability spec, not to the character. It holds exactly two kinds of content, plus optional persistent listeners:

Part	Type	Does
Mutations	`FCrimsonAugmentMutation`	Standing changes applied on equip and reverted on unequip. One list; its `Kind` field selects whether it targets an ability property, a gameplay attribute, a class slot, an object slot or a spec tag.
Event groups	`FCrimsonAugmentEventGroup`	The event tag authored once, plus an ordered list of actions that run when it fires. Actions carry no event tag of their own - the group they sit in is the binding.
Stateful listeners	`UCrimsonStatefulAugmentBase`	Persistent objects that accumulate across events - hit counters, stack consumers. The only thing that receives the defensive `OnOwner*` events your project declares.

1. Create the augment asset

Content Browser -> right-click -> Crimson -> Ability System -> Ability Augment. Set its Slot Category (one of the Augment.Category.* tags) - this decides which slots it can occupy.

Verify

The asset exists and reports a valid Slot Category.

2. Add an action

Open the augment (double-click it) to get the Augment Editor: a palette on the left, the augment as an ordered stack in the middle, details on the right, and a generated summary plus live validation along the bottom.

Click + Add Event... to add a WHEN: group - the menu lists only events the target contract publishes, plus the always-available lifecycle events. Then select the group and click an action in the palette to add it. The plugin ships nine actions.

Action	Does
`_ApplyGameplayEffect`	Applies an effect to the target or the caster. Supplies its own SetByCaller magnitudes - see the callout below.
`_ConsumeEffectStacks`	Spends stacks of an effect.
`_FindTargets`	Re-targets the chain. Excludes the actors it was handed, filters by team, sorts nearest-first, THEN applies Max Targets - so a limit of 1 gives the nearest valid other actor. Replaces the target set for every action after it, discarding the original hit result.
`_GrantAndActivateAbility`	Grants an ability and activates it immediately.
`_ModifyContext`	Edits the effect context (crit flags, source data).
`_ModifySetByCaller`	Changes a SetByCaller magnitude already on the outgoing spec.
`_ModifySpecAttribute`	Changes an attribute-backed value on the spec.
`_ReduceCooldown`	Shortens a cooldown by tag.
`_SpawnActor`	Spawns an actor tied to the ability lifetime.

Feeding a SetByCaller magnitude

Apply Gameplay Effect can supply the numbers its effect asks for. Tick Is Set By Caller, then add an entry to Set By Caller Magnitudes:

- The key is the Data Tag of a Set by Caller modifier on the GameplayEffect. Open the effect, find the modifier whose Magnitude Calculation Type is Set by Caller, and copy its Data Tag exactly.
- The value says where the number comes from: a blackboard value left by an earlier step (Source Property Tag), otherwise that same tag read off the ability's contract properties, otherwise the literal Value curve. Tick Scale By Event Magnitude to multiply (or add, subtract, divide, override) by whatever the event carried - for On Hit that is the damage dealt.

If the key and the effect's Data Tag do not match, GAS resolves that modifier to zero. The effect still applies and simply does nothing, which looks exactly like the augment never fired.

Keeping a chain off your allies

Find Nearby Targets defaults Team Filter to Hostile only, asked of the caster through Epic's IGenericTeamAgentInterface - so any team system implementing it is honored. Set it to Friendly only for chained heals, or Any to disable the check.

If the caster has no team identity at all - neither it nor its controller implements the interface - the filter is skipped and everything is kept, with a warning in the log. That is deliberate: silently returning no targets is indistinguishable from a broken chain.

Conditions and chance

There is no wrapper action for conditions or probability. Every event group and every action carries a Gate (FCrimsonAugmentActionGate): a tag query, a chance, and a minimum level. A gate on the group is rolled once for the whole group; a gate on an action is rolled for that action alone.

Ordering and the shared context

Every action in a group runs top to bottom against one shared context, so an earlier action can change what a later one operates on - _FindTargets is the common case. The editor prints each action's reads and writes underneath it, and warns when a target-replacing action is followed by others.

A group also fires once per target the event carries: on a three-target hit, its actions run three times.

Defensive events named OnOwnerDodge, OnOwnerBlock or OnOwnerDamageTaken reach stateful listeners only - they are never delivered to event groups, and validation rejects a group bound to one. The plugin does not declare those tags; it recognizes the names if your project does.

An effect applied by an augment does not count as a new hit by default, so it will not re-run on-hit augments - without that, an Apply Gameplay Effect inside an On Hit group would re-enter its own group forever. Turn on Retrigger Hit Events on the action when you genuinely want a proc that itself procs; nesting is capped and a runaway chain is dropped with a warning.

Verify

Equip the augment and trigger its event. The action runs.

3. Equip it

Equipping is server-authoritative. Slots are per-ability and come in two pools: Fixed slots declared by the ability, and Temp slots used for transient grants like combo rewards.

On the ASC: Equip Augment To First Free Slot (simplest), Try Equip Augment To Slot (a specific index), or Equip Augment To Temp Slot. Query first with Get Available Slots For Ability.

Remove with Unequip Augment From Slot or Unequip Augment By Slot Address.

Or grant it, and let the ability arrive later

The equip calls above need a live ability handle. When the augment should be owned before the ability exists - a skill tree sells it first, a save restores in either order, an ability set is swapped out and back - grant it instead. The ASC equips a granted augment onto every compatible ability it holds now, onto every compatible ability granted later, and again after an ability is removed and re-granted. Which abilities count as compatible is the augment's own Target Contract / Target Family Query.

On the ASC (server only): Grant Augment with a level, Set Granted Augment Level to rank it up in place, Revoke Augment to take it back everywhere. Query with Is Augment Granted, Get Granted Augment Level, Get Granted Augments, and Find Abilities Compatible With Augment.

Say what it fits

An augment in Contract Family mode must set Target Display Text ("Fire abilities"). A tooltip cannot diff stats against several abilities at once, so it shows that line instead; data validation fails a family augment that leaves it empty.

Verify

Play As Client. The augment's effect is visible on the client, proving it replicated rather than only applying on the server.

How-To: Create and Equip an Augment

What an augment is

1. Create the augment asset

2. Add an action

3. Equip it

Or grant it, and let the ability arrive later

See also