How-To: Set Up a Toggle Ability

Goal: build a stance that applies a buff while it is on, drains a resource on its own schedule, and starts its cooldown at the moment you choose.

Prerequisites

Quick Start and How-To: Declare an Ability Contract. A toggle reads its buff and its recurring costs from a contract, so the contract comes first.

The ability itself authors almost nothing

UCrimsonGameplayAbility_Toggle has exactly two tag properties - Buff Effect Class Slot Tag and Toggle Config Tag - plus Cooldown Policy. There is no buff class, no cost array and no interval on the ability. Everything a designer tunes lives on the contract, which is what lets an augment reach it. A toggle with neither tag set still works: it turns on, turns off, and fires its events.

1. Declare the buff slot and the config entry on the contract

Open your UCrimsonAbilityContract and add two entries. The Class Slot holds the infinite buff Gameplay Effect applied while the toggle is on. The Configuration entry holds the recurring costs and the tick abilities.

Contract section	Entry	Holds
`Class Slots`	e.g. `Ability.Slot.Toggle.Buff`	The infinite GE applied while on. `Expected Base Class` = `GameplayEffect`.
`Configuration`	e.g. `Ability.Config.Toggle`	A `Toggle Ability Configuration` (`FCrimsonToggleConfig`) value.

Pick the struct, not the base

The Value picker on a Configuration entry lists every struct deriving from FCrimsonContractConfigBase. Choose Toggle Ability Configuration. Picking anything else makes the ability report an error in Data Validation rather than silently doing nothing.

Verify

Save the contract. The Configuration entry's Value header reads Toggle Ability Configuration, and the Class Slot shows your buff GE under Default Class.

2. Author the costs and ticks, each with its own interval

Inside the Toggle Ability Configuration there are two arrays. Every entry carries its own Interval, so one toggle can drain stamina every second while burning a charge every ten.

Array	Entry fields	Meaning
`Periodic Costs`	`Effect Class`, `Interval`, `Interval Attribute Tag`	Instant GE charged every `Interval` seconds. Unaffordable at its own moment ends the toggle.
`Tick Abilities`	`Ability Class`, `Interval`, `Interval Attribute Tag`	Ability activated every `Interval` seconds. Failing to activate ends the toggle.

Interval Attribute Tag is optional

Leave it None and the authored Interval is used. Set it to a property your contract publishes and that entry's cadence becomes augmentable - "your stamina drain ticks 20% slower" without touching the other entries. An Interval of 0 or less never fires.

In the contract asset, expand Configuration -> [your entry] -> Value -> Periodic Costs, add an element, and set Effect Class to your drain GE and Interval to 1.0. Repeat under Tick Abilities for anything the stance should fire while active.

Verify

Each element under Periodic Costs and Tick Abilities shows its OWN Interval field. If you see a single interval for the whole array, you are looking at the wrong struct.

3. Point the ability at both tags

Open your Toggle ability Blueprint and set the two tags under Crimson | Toggle to the entries you just authored.

Property	Set to
`Buff Effect Class Slot Tag`	The Class Slot tag from step 1. Leave `None` for a toggle with no buff.
`Toggle Config Tag`	The Configuration tag from step 1. Leave `None` for a toggle with no cost and no tick.

Class Defaults -> Crimson | Toggle. Both are plain gameplay tag pickers. Read the resolved values back at runtime with Get Buff Effect Class, Get Periodic Costs and Get Tick Abilities - each returns what the ability currently has, augments included.

Verify

Play, press the input. The buff GE appears on the avatar and your drain effect fires on its interval. Press again: the buff is removed and the drain stops.

4. Choose when the cooldown lands

A toggle has two moments an ordinary ability does not distinguish. Cooldown Policy picks which one starts the cooldown.

`Cooldown Policy`	Charged	Use for
`On Toggle On`	When it turns on, inside the activation prediction window.	An aura you should not be able to flicker. This is the default.
`On Toggle Off`	Once it turns off. Server only.	A stance that is free to enter but locks you out after you leave it.
`On Both`	At both ends.	Costly to enter and to leave.
`Manual (Blueprint Driven)`	Never automatically.	Any other moment - call Trigger Toggle Cooldown yourself.

Cancels are charged too

With On Toggle Off or On Both, a toggle that is canceled - stunned, interrupted, or unable to pay a periodic cost - still pays the cooldown. An interrupted stance still occupied the time the cooldown is meant to price.

Trigger Toggle Cooldown is callable under any policy, not just Manual. Use it for a cooldown that starts on some third moment - after a successful tick, once a resource empties, or when the stance has been held long enough.

Call Trigger Toggle Cooldown from any graph on the ability. It is a no-op on clients, so you do not need an authority check before it - but the node that decides to call it should still run in an (Authority) event.

Verify

Set Cooldown Policy to On Toggle Off and give the ability a cooldown effect. Toggle on: the slot shows no cooldown. Toggle off: the cooldown starts. Run Play As Client and confirm the client's cooldown UI fills in when the effect replicates.

5. Optional: let an augment change the lists

A Config mutation folds a delta into the Configuration entry, so an augment can add a drain or strip a tick without restating the whole thing. Unlike a Class or Object swap, every contributing augment applies - two augments can each add a tick to the same toggle.

Field on `Toggle Ability Modification`	Effect
`Add Periodic Costs`	Adds whole entries (class plus its schedule). An entry whose `Effect Class` is already present is ignored.
`Remove Periodic Cost Effect Classes`	Strips every cost entry using one of these classes, whoever supplied it.
`Add Tick Abilities`	Adds whole entries. Duplicate `Ability Class` is ignored.
`Remove Tick Abilities`	Strips every tick entry using one of these ability classes.

On the augment, add a Mutation, set Kind to Modify Configuration, pick your Configuration tag from the dropdown, and fill in a Toggle Ability Modification. Removals are applied after additions, so one augment can reliably strip an entry the contract authored.

Config changes land on the next toggle-on

The config is snapshotted when the toggle turns on, because each entry owns a timer keyed to its position in the list. An augment equipped while a toggle is running does not resize that list underneath the running timers - switch the toggle off and on for it to take effect.

Verify

Equip the augment, then toggle on. The added drain fires on its own interval alongside the contract's. Unequip and toggle again: it is gone.

Multiplayer

Piece	Runs on
The toggle-off press	Owning client signals through a replicated `UAbilityTask_WaitInputPress`; the server decides.
Buff GE, periodic costs, tick abilities	Server only.
Activation cost and an `On Toggle On` cooldown	Predicted by the owning client, confirmed by the server.
An `On Toggle Off` / `Manual` cooldown	Server only. The client sees it when the effect replicates.
`(Cosmetic)` events	Server and predicting client.
`(Authority)` events	Server only.

How-To: Set Up a Toggle Ability

1. Declare the buff slot and the config entry on the contract

2. Author the costs and ticks, each with its own interval

3. Point the ability at both tags

4. Choose when the cooldown lands

5. Optional: let an augment change the lists

Multiplayer

See also