Abilities

Mass Forge abilities are shared Data Assets executed by actorless or represented Mass entities. Per-entity state contains only stable ability IDs, cooldown timestamps, and optional charge state.

For project-specific read-only admission rules beyond built-in attributes, tags, targeting, cooldowns, charges, and costs, see the ability condition extensions guide.

For project-specific dynamic effect selection that still uses the normal bounded atomic transaction, see the ability execution plans guide.

Opening the asset shows a live execution summary, validation results, and searchable policy/effect dependencies plus saved referencers. See GAMEPLAY_ASSET_AUTHORING_GUIDE.md.

Setup

1. Create Mass Forge Instant Effect and/or Mass Forge Persistent Effect assets for the ability's outcomes.
2. Create a Mass Forge Ability Data Asset and assign a stable AbilityId.
3. Configure costs, individual/shared cooldowns, execution type, self/target instant effects, self/target persistent effects, optional channel effects, default effect parameters, and an optional execution plan.
4. Add Mass Forge Ability Trait to the Entity Config and assign starting abilities, or grant them at runtime. Entities receiving persistent outcomes also need Mass Forge Persistent Effects Trait and, when tags are used, Mass Forge Gameplay Tag Trait.

This generated example is a complete small ability: it costs 20 Mana, applies the authored Heal effect to the source, and starts a six-second cooldown. Change the assets and numbers; the execution contract stays the same.

Can Activate Mass Forge Ability reports grant, target, requirement, tag-gate, cooldown, charge, affordability, and active-lifecycle failures without changing state. Activate Mass Forge Ability commits Instant abilities immediately or begins a configured Cast/Channel lifecycle. The eventual activation transaction commits attribute, counted Gameplay Tag, and persistent-effect changes atomically. A failed transaction restores individual cooldown, shared cooldown, charges, attributes, tags, active persistent instances, cancellations, and deterministic handle allocation. See ABILITY_LIFECYCLE_GUIDE.md for timing and stop semantics.

A granted ability is compact per-entity ownership state; the shared Data Asset remains the authored definition. Add the side-effect-free Can Activate query when UI or AI needs the exact rejection reason before activation.

Casts and channels

Set ExecutionType to Cast with a positive cast time, or Channel with positive duration and period values. Cast/channel requests are checked when they start and fully revalidated before costs, charges, cooldowns, and activation effects commit. One lifecycle can be active per entity.

Channel self/target effects are separate from activation effects. They execute as an atomic transaction on every scheduled pulse without repeating the ability cost. The lifecycle API exposes state, remaining time, pulse count, cancel and interrupt operations, Actor convenience nodes, and presentation-neutral events. The unified entity inspection snapshot and editor inspector show the active lifecycle.

Attribute requirements

Add entries to Requirements when activation depends on current gameplay state rather than spending a resource. Each entry selects the source or target entity, an attribute, one of six comparisons, and the required value. Equal and Not Equal comparisons also expose a non-negative tolerance.

Examples include source Health > 0, source Mana >= 20, target Health <= 30, or target Shield == 0 within a chosen tolerance. A target-side requirement automatically makes the target pin mandatory even when the ability has no target effects.

A failed comparison returns Requirement Not Met without reserving cooldowns or charges and without applying costs or effects. The activation result identifies the zero-based requirement index, source/target subject, attribute, observed value, and required value, allowing Blueprint UI or AI logic to explain the failure without parsing text. An unresolvable requirement attribute returns the corresponding attribute failure with the same requirement identity fields.

Gameplay Tag requirements

Add Mass Forge Gameplay Tag Trait to entities that own tags. Ability assets expose required and blocked tag containers for both source and target. Every required tag must match; any blocked tag rejects activation. Target tag rules automatically require a valid target. Failures return Missing Gameplay Tag Fragment, Missing Required Tag, or Blocked By Tag plus the exact tag and source/target subject.

Matching is hierarchical, so requiring a parent tag accepts an owned child. Tag gates run before any cooldown, charge, cost, or effect state is changed. See GAMEPLAY_TAGS_GUIDE.md.

Individual and shared cooldowns

CooldownSeconds controls only the activated ability. To lock several abilities together, give them the same non-empty CooldownGroup and a positive finite CooldownGroupSeconds value. Activating any member starts that named group; another member returns On Cooldown Group, the group ID, and its remaining time until the lock expires.

• Leave the group name empty and its duration at zero to disable shared cooldowns.
• Use one common group ID on every ability to author a global cooldown.
• Different abilities in a group may author different durations; the ability that successfully activates supplies the new group duration.
• Get Mass Forge Cooldown Group Remaining lets Blueprint UI query a group without referencing a particular ability.
• An entity tracks at most eight named groups at once. Expired records are reused deterministically, so historic groups do not grow per-entity memory.
• A ninth group returns No Free Cooldown Group Slot only while all eight tracked groups are still active.

Individual cooldowns, shared cooldowns, and charges are independent gates. All enabled gates must be ready before an activation can succeed.

Charges

Charges are optional. Leave MaxCharges at zero to disable them. To enable charges, set MaxCharges from 1 to 255 and set ChargeRecoverySeconds to a finite value greater than zero.

• A grant begins at full capacity.
• Each successful activation consumes one charge.
• Recovery proceeds one charge at a time using absolute world time.
• Several elapsed recovery intervals are processed deterministically during the next query or activation.
• The recovery clock stops when capacity is full.
• An exhausted ability returns No Charges and reports the next recovery time.
• Get Mass Forge Ability Charge State exposes current charges, maximum charges, and recovery remaining to Blueprint.

Charges can be combined with both cooldown types. This permits burst charges with a short per-use cooldown, a shared global lockout, or slower strategic recovery.

Get Granted Mass Forge Abilities enumerates compact runtime state in lexical ability-ID order without loading definition assets. Get Active Mass Forge Cooldown Groups lists only groups with positive remaining time. Both are also included in the unified entity inspection snapshot.

Targets and effects

Enable Requires Target when the ability must receive a valid target distinct from its source. Target instant, persistent, or channel effects also imply that a target is needed. Self effects apply to the source entity; target effects apply to the selected target.

Targeting Policies provide reusable validation after basic handle checks and before tags, cooldowns, charges, requirements, costs, or effects. Every policy must allow the pair. The built-in range policy works with actorless Mass transforms and optional represented-Actor fallback; Blueprint policy subclasses can return a stable project-specific rejection reason. Policy failures identify the authored index, policy ID, detailed result, and evaluated distance where applicable. See TARGETING_POLICIES_GUIDE.md.

Selection is a separate concern. Mass Forge supplies bounded actorless radius and transform-segment searches, collision-hit conversion for represented Actors, Actor-based ability nodes, and a sanitized custom provider interface. See TARGET_SELECTION_GUIDE.md.

Requirements are read-only gates. Costs and all referenced attribute/tag modifiers form one transaction after every requirement passes. If a requirement fails, a cost is unaffordable, an attribute is unknown, a tag operation cannot complete, an effect is invalid, or a required magnitude parameter is absent, no cost or effect state is committed. Tag-operation failures identify the tag, source/target subject, and exact reason. See INSTANT_EFFECTS_GUIDE.md.

Instant and persistent modifiers may also derive magnitude from one source or recipient attribute. Every modifier in the atomic cost/Instant Effect stage samples the stage's pre-commit state. Persistent captures occur when that persistent instance reaches its documented self-then-target application position; earlier provisional ability outcomes are therefore visible consistently, while the incoming instance's own lifecycle changes are not. Persistent periodic snapshots retain that value and live periodic captures reevaluate at each pulse. Failures expose the sampled attribute, Source/Target subject, and underlying access result.

Dynamic execution plans

An optional Mass Forge Ability Execution Plan can append to or replace the fixed effect lists for activation and channel pulses. It receives source/target entity handles, optional represented Actors, stable Ability/lifecycle identity, phase, one-based pulse number, and authored parameters. It returns only a bounded transaction description; Mass Forge validates every effect and parameter and commits it through the existing atomic path.

Plans are preflighted by Can Activate and re-evaluated at actual commit, so Blueprint/C++ implementations must be deterministic, side-effect-free, and safe to call more than once. Target output requires Requires Target. Channel-pulse output is Instant-only. See ABILITY_EXECUTION_PLANS_GUIDE.md for merge order, limits, failure diagnostics, and the data-only Static plan.

Persistent outcomes and transaction order

Use SelfPersistentEffects and TargetPersistentEffects for damage-over-time, healing-over-time, timed buffs/debuffs, temporary state tags, immunity-aware applications, and cleanse or dispel abilities. The ability's effect parameters and source identity are copied into every persistent context for later pulses.

Successful activation uses a deterministic order: costs plus self/target Instant Effects are calculated first, followed by self Persistent Effects in authored order, then target Persistent Effects in authored order. Persistent-effect handles are returned in that same self-then-target order. The result also reports the total number of existing instances cancelled by the activation.

This is one observable transaction. If any later persistent application fails—including a missing trait, immunity blocker, stack/capacity rejection, invalid asset, tag-capacity failure, or failed execute-on-application pulse—Mass Forge restores every earlier part of the activation. No provisional attribute, tag, persistent apply/removal/stack, or pulse event is published. The failure returns Persistent Effect Failed, the underlying persistent result, the source/target subject, the zero-based list index, and relevant tag or magnitude-parameter details.

On success, all state is committed before buffered events are released. Blueprint delegates remain available, and the attribute, tag, and persistent subsystems expose native C++ mirrors for direct engine-side binding.

Safe execution

Direct mutations are rejected while Mass is processing. Use the queued Activate, Grant, Revoke, Cancel, or Interrupt node when a Blueprint or external system can overlap a Mass phase. All five operations share one bounded FIFO and configurable back-pressure limit. Accepted receipts return a positive request ID; On Ability Operation Request Completed reports the operation and terminal result. Queued Cancel/Interrupt captures an exact lifecycle ID and cannot stop a later replacement lifecycle. The activation-only On Ability Request Completed event remains available for compatibility.

StateTree and tick-driven AI can instead use Request Mass Forge Ability Activation for AI. It adds a bounded pollable ticket over the same queue, with Pending, Active, Succeeded, Failed, Cancelled, and Interrupted states plus detailed activation/lifecycle data. Pending admission and active lifecycles can be cancelled through the ticket; terminal records can be explicitly forgotten and are otherwise evicted oldest-first when capacity is needed. See AI_STATETREE_GUIDE.md.

Abilities are the final phase of the shared external-command coordinator, after queued raw changes, Instant Effects, Persistent Effects, damage, and death handling. Existing ability lifecycles advance before queued Activate/Grant/Revoke/Cancel/Interrupt operations begin, preventing a newly admitted cast from consuming an earlier frame's delta and resolving natural lifecycle completion before queued control. See the deferred command contract for same-frame and callback-enqueue behavior.

Requests admitted to one ability phase execute FIFO. Each request validates against the state committed by every earlier request: two same-source abilities sharing a cooldown therefore produce one success followed by On Cooldown Group, while independent sources may both affect the same target in deterministic request order. A completion listener may queue more ability work, but that follow-up waits for the next safe coordinator tick even if the listener calls the coordinator recursively.

Successful ability state is complete before attribute, Gameplay Tag, persistent-effect, or ability commit listeners are notified. Cast/channel state carries a positive world-local Lifecycle Id; internal lifecycle processing checks that identity after every callback-capable operation. If a listener cancels a lifecycle and starts a replacement on the same entity, the outer cast completion or channel loop cannot consume, complete, or otherwise mutate the replacement.

Current limits

Each entity can hold 16 granted abilities, track eight named cooldown groups, run one active cast/channel lifecycle, and—when opted in—hold 16 active persistent instances. Multiplayer transport and prediction are outside the initial supported release.