Ability execution plans

Ability Execution Plans are optional Blueprint/C++ Data Assets that choose a bounded effect payload for one ability activation or one channel pulse. They extend authored abilities without bypassing Mass Forge validation, rollback, cooldown, charge, cost, event-order, or source-plus-one-target transaction rules.

Use a plan when an ability must choose effects or parameter values from current source/target state. Keep fixed outcomes directly on the Ability asset.

Quick setup

1. Create a Mass Forge Static Ability Execution Plan for data-only branching, or derive a Blueprint from Mass Forge Ability Execution Plan for project logic.
2. Give it a unique PlanId.
3. Choose Append After Authored Effects or Replace Authored Effects.
4. For a Static plan, fill ActivationPayload and/or ChannelPulsePayload. For a Blueprint plan, override Build Execution Plan and return a response.
5. Assign the plan to the Ability's Execution Plan field.
6. Run Unreal Data Validation and Tools > Mass Forge Project Health.

Any plan that can return target effects must be used by an Ability with Requires Target enabled. This makes targeting requirements visible to designers, AI, UI, and preflight checks before plan evaluation.

Query available to Blueprint and C++

Every evaluation receives read-only context:

• world context;
• source and target entity handles;
• optional represented source and target Actors;
• stable Ability ID;
• Activation or ChannelPulse phase;
• lifecycle ID for casts/channels;
• one-based channel-pulse number, or zero for activation;
• the Ability's authored effect-parameter map.

Actor pointers may be null for actorless Mass entities. Logic must use the entity handles when Actor representation is optional.

Returned transaction payload

A successful response may return:

• self and target Instant Effects;
• self and target Persistent Effects for the activation phase;
• named effect-parameter overrides.

Output is limited to 64 combined effects and 64 parameter overrides per evaluation. Channel-pulse output supports Instant Effects only; Persistent Effects belong to the activation transaction. Empty output is valid.

With Append After Authored Effects, fixed Ability effects execute first in authored order, followed by plan effects in returned order. With Replace Authored Effects, plan lists replace all fixed effect lists for that phase. In both modes, plan parameters override authored parameters with the same name and leave other authored parameters intact.

Evaluation timing

• Can Activate Mass Forge Ability evaluates the activation plan as a side-effect-free preflight.
• An Instant ability evaluates again immediately before its atomic commit.
• A Cast or Channel evaluates at admission, then evaluates again when the delayed activation transaction commits.
• A Channel evaluates its channel-pulse payload once for every earned pulse. ChannelPulse is one-based and remains stable during bounded catch-up.

Plans must therefore be deterministic for the same query and safe to evaluate more than once. Do not spend resources, apply effects, grant abilities, start another ability, broadcast gameplay events, or otherwise mutate gameplay from Build Execution Plan. Return a description and let Mass Forge commit it.

Validation and atomic failure behavior

Mass Forge validates the plan and every returned reference before changing gameplay state. It rejects:

• missing, unloadable, or unidentified plans/effects;
• invalid worlds, sources, targets, merge modes, names, or non-finite parameter values;
• recursive plan evaluation;
• output beyond either fixed limit;
• target output without a valid required target;
• Persistent Effect output during a channel pulse.

Activation failures return ExecutionPlanRejected with an ExecutionPlanResponse containing PlanId, the detailed result, and optional stable Reason. Recursive admission returns ExecutionPlanEvaluationInProgress. A rejected activation commits no costs, effects, cooldowns, charges, persistent instances, lifecycle state, or gameplay events. If a later effect in a valid payload fails while staging, the existing ability transaction rollback rules apply to both authored and planned output.

A failed channel pulse follows the Ability's ChannelFailurePolicy; earlier completed pulses are separate transactions and are not rolled back.

Blueprint implementation pattern

In a Blueprint-derived plan:

1. Override Build Execution Plan.
2. Branch on Phase first.
3. Read only the supplied handles/Actors and stable project state.
4. Build one payload in deterministic array order.
5. Return Success, the plan's stable ID, and the payload.
6. For expected gameplay denial, return Rejected with a stable reason. For bad setup, return InvalidConfiguration.

The base class intentionally returns InvalidConfiguration with NoExecutionPlanImplementation, so an unimplemented asset fails closed. The Static subclass is the recommended no-code example and provides separate activation and channel payloads.

Scope and high-volume boundary

One plan describes one source plus at most one target. Radius, segment, provider, or collision selection remains a separate targeting step, and each selected activation remains an independent transaction. A plan is shared definition logic, not a per-entity UObject.

Execution plans run at ability admission/commit or channel-pulse frequency. They are not a Mass processor hot loop and should not be used to iterate an entire population. For uniform work across large archetypes, use compiled slots and Mass processors described in CPP_HIGH_VOLUME_GUIDE.md and HIGH_VOLUME_EFFECTS_GUIDE.md.

Support checklist

• Give every plan and returned effect a unique stable ID.
• Keep output under both limits and use finite parameter values.
• Enable Requires Target when target output is possible.
• Treat Blueprint callbacks as pure decision functions.
• Test both preflight and delayed commit when state may change during a cast.
• Test every channel failure policy used by the project.
• Inspect nested execution-plan diagnostics before reporting a transaction bug.
• Include the Ability, plan, effects, Project Health report, and reproduction query in support requests.

See ABILITIES_GUIDE.md, ABILITY_LIFECYCLE_GUIDE.md, GAMEPLAY_ASSET_AUTHORING_GUIDE.md, and TRANSACTION_AND_EVENT_CONTRACT.md.