How-To: Create & Equip an Augment

Goal: author a UCrimsonAbilityAugment (a rune/gem) that mutates an ability through a declared slot, then equip it at runtime via the slot-based API.

Prerequisites
The target ability has a UCrimsonAbilityContract assigned, and that contract declares at least one augment slot (a SlotCategory). Augments can only occupy slots the contract publishes.

1. Declare an augment slot on the contract

Open the ability's contract and add an entry to AugmentSlots - a SlotCategory tag and how many augments it accepts. Augments whose SlotCategory matches can be equipped there.

Screenshot pendingImages/CrimsonAbilitySystem/howto-contract-slot.png
Contract -> Schema -> Augment Slots -> add a slot category + capacity.

2. Create the augment asset

Pick a compatibility mode and a slot, then add mutations.

FieldPurpose
TargetModeSpecificContract (binds to one TargetContract) or ContractFamily (matches TargetFamilyQuery against contract IdentityTags)
SlotCategoryWhich contract slot this augment occupies (must be declared by the contract)
SlotCostSlot capacity consumed (>= 1)
StatMutationsAdjust contract properties by tag (Additive / Multiplicative / Override, with a MinimumLevel)
AttributeMutationsAdjust attributes baked into damage execution (crit, power...)
ClassMutations / ObjectMutationsSwap a class/object slot the contract publishes (e.g. fire -> ice projectile)
TagMutationsAdd / Remove / Replace tags on the ability spec
RequiresAugmentTags / ConflictsAugmentTagsPer-augment relationship rules enforced at equip time
Editor catches wiring bugs
When TargetMode = SpecificContract, every mutation's tag dropdown is populated from that contract's published schema - you can't target a tag the ability doesn't expose. IsDataValid fails the asset at save time if a binding is broken, so footguns surface in the editor, not at runtime.

3. Equip it at runtime (server only)

Use the slot-based API on the ASC. All equip functions are BlueprintAuthorityOnly and report why an equip failed via ECrimsonEquipFailure (and a logged warning - never a silent no-op).

Screenshot pendingImages/CrimsonAbilitySystem/howto-equip-augment.png
Has Authority -> Equip Augment To First Free Slot (Ability Handle, Augment, Level). Branch on the return value; read Out Reason on failure.

To remove an augment, use UnequipAugmentFromSlot(Handle, SlotCategory, SlotIndex), or UnequipAugmentBySlotAddress for an instance you got from GetAvailableSlotsForAbility / GetActiveTempAugments. For temporary, uncapped grants (e.g. a buff), use EquipAugmentToTempSlot.

Authority
All equip/unequip calls are server-authoritative. The equipped instances replicate to clients via the ActiveAugments fast-array; stateful listeners run server-side only.
Verify
Equip in PIE, then check the affected GetConfigurableValue (e.g. cooldown) reflects the mutation, and any TagMutations show on the ability spec. A bad slot/relationship returns false with a descriptive ECrimsonEquipFailure.

See also

  • Concept: Augment System - the full model, actions, and stateful listeners
  • Concept: Ability Contract - what contracts publish