unreal-gas-abilities

Unreal 5.8 GAS Abilities

Build reliable network-ready GAS abilities

---
name: unreal-gas-abilities
description: Design, implement, network, and debug Gameplay Abilities with Unreal Engine 5.8 Gameplay Ability System. Use for Ability System Component ownership, granting, activation, input or Gameplay Event triggers, costs, cooldowns, instancing, net execution, prediction, targeting, Ability Tasks, cancellation, animation, passive abilities, or ability lifecycle failures.
---

# Unreal 5.8 GAS Abilities

## Establish the GAS boundary

Read [`references/architecture.md`](references/architecture.md) before implementation.

- Put the Ability System Component on the Pawn/Character when abilities should reset with
  that avatar.
- Put it on PlayerState when abilities, attributes, or cooldowns must survive pawn death or
  replacement; initialize Owner Actor and Avatar Actor correctly on server and owning client.
- Grant and remove abilities on authority. Store returned ability spec handles when later
  removal or mutation is required.
- Route attribute/effect work to `$unreal-gas-attributes-effects` and taxonomy/query work
  to `$unreal-gameplay-tags`.

## Execute the lifecycle

1. Define activation trigger, ownership, instancing policy, net execution policy, tags,
   cost, cooldown, targeting, and cancellation behavior.
2. Request activation through `TryActivateAbility`, a Gameplay Event, or the project's
   input-to-ability mapping. Do not call `CallActivateAbility` as a normal public entry.
3. Let GAS run activation checks. Add custom checks only for conditions not represented by
   tags, costs, cooldowns, or target requirements.
4. In `ActivateAbility`, commit at the intended point. If `CommitAbility` fails, end the
   ability without applying authoritative gameplay.
5. Use Ability Tasks for multi-frame waits, animation, input, targeting, and events.
6. Apply authoritative effects on the server or through a supported predicted path.
7. Handle success, cancel, interruption, failed targeting, and montage interruption.
8. Call `EndAbility` on every terminal path and undo non-effect side effects.

Read [`references/ability-lifecycle.md`](references/ability-lifecycle.md) for the ordered
flow, [`references/patterns.md`](references/patterns.md) for concrete ability shapes, and
[`references/networking.md`](references/networking.md) before choosing prediction.

## Required answer format

Return:

1. **ASC owner/avatar layout** and initialization points.
2. **Ability configuration**: grant path, trigger, instancing, net policy, tags, cost,
   cooldown, and targeting.
3. **Ordered activation graph or C++ flow**.
4. **Authority/prediction split** and rollback limitations.
5. **All terminal paths**, including cancellation cleanup.
6. **Failure tags/logging** and multiplayer verification.

Do not invent property names, Blueprint nodes, prediction guarantees, or security behavior.

## Hard rules

- Grant abilities only on the authoritative server.
- Do not put mutable execution state on a non-instanced ability.
- Do not assume local prediction makes arbitrary spawned actors or instant damage reversible.
- Do not use Gameplay Cues for authoritative gameplay; they are cosmetic and not reliably
  replicated.
- Do not omit `EndAbility`.
- Do not commit a cost/cooldown before the design's true commitment point by accident.
- Keep ability input identifiers separate from semantic ability and state tags.

Use [`references/troubleshooting.md`](references/troubleshooting.md) when activation fails,
fires twice, desynchronizes, ignores cancellation, or leaves an ability active. See
[`references/sources.md`](references/sources.md) for the UE 5.8 source trail.

## Establish the GAS boundary

Read [`references/architecture.md`](/unreal/unreal-gas-abilities/architecture/) before implementation.

- Put the Ability System Component on the Pawn/Character when abilities should reset with
  that avatar.
- Put it on PlayerState when abilities, attributes, or cooldowns must survive pawn death or
  replacement; initialize Owner Actor and Avatar Actor correctly on server and owning client.
- Grant and remove abilities on authority. Store returned ability spec handles when later
  removal or mutation is required.
- Route attribute/effect work to `$unreal-gas-attributes-effects` and taxonomy/query work
  to `$unreal-gameplay-tags`.

## Execute the lifecycle

1. Define activation trigger, ownership, instancing policy, net execution policy, tags,
   cost, cooldown, targeting, and cancellation behavior.
2. Request activation through `TryActivateAbility`, a Gameplay Event, or the project's
   input-to-ability mapping. Do not call `CallActivateAbility` as a normal public entry.
3. Let GAS run activation checks. Add custom checks only for conditions not represented by
   tags, costs, cooldowns, or target requirements.
4. In `ActivateAbility`, commit at the intended point. If `CommitAbility` fails, end the
   ability without applying authoritative gameplay.
5. Use Ability Tasks for multi-frame waits, animation, input, targeting, and events.
6. Apply authoritative effects on the server or through a supported predicted path.
7. Handle success, cancel, interruption, failed targeting, and montage interruption.
8. Call `EndAbility` on every terminal path and undo non-effect side effects.

Read [`references/ability-lifecycle.md`](/unreal/unreal-gas-abilities/ability-lifecycle/) for the ordered
flow, [`references/patterns.md`](/unreal/unreal-gas-abilities/patterns/) for concrete ability shapes, and
[`references/networking.md`](/unreal/unreal-gas-abilities/networking/) before choosing prediction.

## Required answer format

Return:

1. **ASC owner/avatar layout** and initialization points.
2. **Ability configuration**: grant path, trigger, instancing, net policy, tags, cost,
   cooldown, and targeting.
3. **Ordered activation graph or C++ flow**.
4. **Authority/prediction split** and rollback limitations.
5. **All terminal paths**, including cancellation cleanup.
6. **Failure tags/logging** and multiplayer verification.

Do not invent property names, Blueprint nodes, prediction guarantees, or security behavior.

## Hard rules

- Grant abilities only on the authoritative server.
- Do not put mutable execution state on a non-instanced ability.
- Do not assume local prediction makes arbitrary spawned actors or instant damage reversible.
- Do not use Gameplay Cues for authoritative gameplay; they are cosmetic and not reliably
  replicated.
- Do not omit `EndAbility`.
- Do not commit a cost/cooldown before the design's true commitment point by accident.
- Keep ability input identifiers separate from semantic ability and state tags.

Use [`references/troubleshooting.md`](/unreal/unreal-gas-abilities/troubleshooting/) when activation fails,
fires twice, desynchronizes, ignores cancellation, or leaves an ability active. See
[`references/sources.md`](/unreal/unreal-gas-abilities/sources/) for the UE 5.8 source trail.

unreal 5.8 gas abilities design, implement, network, and debug gameplay abilities with unreal engine 5.8 gameplay ability system. use for ability system component ownership, granting, activation, input or gameplay event triggers, costs, cooldowns, instancing, net execution, prediction, targeting, ability tasks, cancellation, animation, passive abilities, or ability lifecycle failures. ability lifecycle ability lifecycle configuration checklist - instancing: non-instanced, instanced per actor, or instanced per execution. - net execution: local only, local predicted, server initiated, or server only. - activation trigger: explicit/spec handle, gameplay event, effect/tag trigger, or input. - ability/state tags: activation required/blocked, cancel, block, owned while active. - cost and cooldown gameplay effects. - target acquisition/validation. - cancellation and terminal cleanup. use an instanced policy when blueprint graphs, member variables, latent work, or per-run state are needed. non-instanced abilities operate on the class default object and cannot safely hold mutable execution state. ordered activation flow 1. input/gameplay event requests tryactivateability or a project wrapper. 2. gas evaluates availability, tags, cost/cooldown checks, and custom activation checks. 3. activateability starts only after activation succeeds. 4. validate target data at the authority boundary. 5. call commitability at the designed commitment point. if it returns false, terminate. 6. start ability tasks for montage, waits, input, events, or targeting. 7. apply authoritative gameplay effects and other gameplay results. 8. route cosmetic feedback through gameplay cues or presentation systems. 9. on completion, interruption, cancel, invalid target, or task failure, clean up and call endability with the correct canceled flag. callactivateability does not perform the normal availability check itself; do not use it as the usual input entry point. commit point commit determines when cost and cooldown become real. examples: - immediate dodge: commit after direction and movement feasibility checks. - aimed spell: commit on confirm, not when targeting ui opens, unless design says aiming itself spends the resource. - melee attack: commit at accepted activation or at a montage-defined point, consistently. - channel: initial cost on start; periodic cost through a deliberate repeating effect/task. avoid applying gameplay before a failed commit. avoid accidentally charging on canceled target selection. cleanup checklist - stop or let gas terminate active ability tasks; - remove non-effect temporary state and input locks; - clear spawned targeting helpers owned by the run; - stop animation only when this ability owns it; - end exactly once on every branch. gas ability architecture gas ability architecture enable and expose gas 1. enable the gameplay ability system plugin. 2. add gameplayabilities, gameplaytags, and gameplaytasks to the relevant module dependencies. 3. give the ability-owning actor access to a uabilitysystemcomponent and implement iabilitysysteminterface where appropriate. 4. create the project's ugameplayability base class for shared failure, input, tag, targeting, and cleanup behavior. choose asc owner and avatar owneractor owns the component; avataractor is the physical actor acting in the world. | need | common layout | |---|---| | ai or pawn-local abilities reset with pawn | asc on pawn/character; owner and avatar are that actor | | player abilities/cooldowns persist through pawn replacement | asc on playerstate; owner is playerstate, avatar is current pawn | for a playerstate-owned asc, initialize actor info after server possession and on the owning client when playerstate/possession data is available. reinitialize when the avatar changes. do not cache an obsolete avatar inside abilities. granting - grant with giveability/fgameplayabilityspec on authority; the blueprint give ability node is ignored when the actor is not authoritative. - persist the returned fgameplayabilityspechandle if equipment, loadout, or progression later removes/changes the grant. - separate the ability class from the grant's level, input binding, and source object. - decide whether a passive activates on grant, via effect/event trigger, or through an explicit startup pass; define its removal behavior too. cross-skill boundaries - costs, cooldown effects, damage, attributes, stacking → $unreal-gas-attributes-effects. - ability/state/event/input tag taxonomy and query semantics → $unreal-gameplay-tags. - blueprint component/subsystem communication outside gas → $unreal-blueprint-architecture. networking and prediction networking and prediction policy selector | policy | use | |---|---| | local only | purely local behavior that must not execute on server | | local predicted | responsive locally controlled ability with server validation and gas-supported reconciliation | | server initiated | server starts it and clients receive replicated execution | | server only | authoritative server behavior with no predicted local activation | choose explicitly. the correct choice depends on ownership, responsiveness, cheating risk, and whether every side effect participates in gas prediction. prediction-safe design - keep the server authoritative for target legality and gameplay results. - use gas effects and ability mechanisms with prediction support where appropriate. - treat instant attribute/tag changes, arbitrary rpcs, external object mutation, and spawned actors as separate rollback problems; do not assume gas reverses them. - separate predicted presentation from authoritative hit/damage confirmation. - do not grant abilities from clients. target data 1. client may collect responsive aim/target data for a locally controlled ability. 2. send through the supported gas targeting/event path. 3. server validates range, line of sight if required, source transform, team/target rules, cooldown/cost, and timing. 4. server applies authoritative results. multiplayer verification matrix test in editor and packaged development builds with dedicated server where relevant: - owning client with artificial latency and packet loss; - listen server player; - simulated proxy observing the ability; - activation rejected by server; - cancel before and after commit; - avatar death/respawn during execution; - target disappears during targeting; - duplicate input press/release; - montage interruption and late event; - ability grant/removal during possession change. log role, owner/avatar, prediction key where available, spec handle, activation result, failure tags, commit result, and termination reason. ability patterns ability patterns instant self ability example: heal, stance toggle request, short utility action. 1. try activation. 2. commit. 3. make outgoing effect spec with ability level/context. 4. apply to self or resolved target on authority/predicted supported path. 5. trigger cosmetic cue. 6. end. montage-driven melee 1. activate and commit at the chosen commitment point. 2. start a montage ability task. 3. open damage window from a gameplay event/notify path owned by the ability. 4. server validates hits and applies effects once per valid target/window. 5. close the window. 6. end on montage completed, blended out, interrupted, or canceled; distinguish paths where recovery/cooldown rules differ. target-confirmed projectile 1. activate into targeting state without spending if design permits cancellation. 2. ability task waits for confirm/cancel and produces target data. 3. server validates origin, direction/range, target legality, and fire rate. 4. commit. 5. spawn the authoritative projectile or apply the validated result. 6. end; clean up reticle/target actor on every path. do not assume a client-predicted spawned actor automatically rolls back. charged ability 1. activate and record charge start in an instanced ability/task. 2. wait for release, cancel, maximum charge, or interruption. 3. compute charge from server-valid timing or bounded client data. 4. commit on release. 5. put charge magnitude into a setbycaller value or level/context as designed. 6. apply effect, feedback, and end. channeled ability 1. commit initial activation. 2. apply an active state tag/effect. 3. use tasks/effects for periodic work; do not create uncontrolled tick logic. 4. stop on input release, insufficient resource, blocking tag, death, invalid target, or external cancel. 5. remove non-effect state and end. passive ability 1. define grant and activation trigger. 2. apply persistent effects or register bounded event listeners. 3. on removal/end, remove active effects by retained handle and unregister listeners. 4. test loadout swaps, respawn, duplicate grants, and reconnect. ue 5.8 primary sources ue 5.8 primary sources verified 2026-07-19. - gameplay ability system - gameplay ability system overview - using gameplay abilities - ability tasks - ability system component and attributes - give ability blueprint api - ugameplayability api - abilities in lyra version note: these epic pages currently resolve to unreal engine 5.8. prediction is not a blanket rollback system. epic specifically distinguishes supported predicted gameplay effect behavior from instantaneous changes and other external side effects. troubleshooting troubleshooting ability will not activate - confirm the ability is granted on server and present in the asc spec list. - confirm initabilityactorinfo has valid owner/avatar on this machine. - inspect activation required/blocked tags, cooldown tags, cost attributes, and custom checks. - capture failure tags and log role, ownership, and local control. - confirm the request uses tryactivateability/supported trigger. activates on server but not owning client - check asc replication and its owner chain. - reinitialize actor info when playerstate and pawn become available client-side. - check net execution policy and local ownership. activates twice - ensure input is not routed both through numeric input binding and tag/event routing. - check duplicate grants and repeated bindings after respawn. - check whether both input press and gameplay event activate the same spec. cost or cooldown missing - confirm commitability executes and succeeds. - confirm cost/cooldown effects are configured and their attributes/tags exist. - confirm the commit point is reached on the correct authority/prediction path. - inspect active gameplay effects and cooldown tags on the asc. ability never ends - trace every task output and early-return branch to endability. - handle montage completed, blend out, interrupted, and canceled outputs. - confirm custom ability tasks broadcast terminal delegates or end. - add one guarded termination helper in the project base ability. cancel does not clean up - put persistent modifiers in effects that can be removed deterministically. - retain handles for spawned helpers/listeners/effects owned by the run. - remove manual movement/input locks during cancellation. - do not depend on a cosmetic gameplay cue to restore gameplay state. client predicts a hit the server rejects - separate predicted feedback from confirmed damage. - validate target data on server. - check that non-gas side effects are not assumed to roll back. - test under latency; log prediction and server result together.

Ability lifecycle

# Ability lifecycle

## Configuration checklist

- Instancing: non-instanced, instanced per actor, or instanced per execution.
- Net execution: local only, local predicted, server initiated, or server only.
- Activation trigger: explicit/spec handle, Gameplay Event, effect/tag trigger, or input.
- Ability/state tags: activation required/blocked, cancel, block, owned while active.
- Cost and cooldown Gameplay Effects.
- Target acquisition/validation.
- Cancellation and terminal cleanup.

Use an instanced policy when Blueprint graphs, member variables, latent work, or per-run state
are needed. Non-instanced abilities operate on the class default object and cannot safely
hold mutable execution state.

## Ordered activation flow

1. Input/gameplay event requests `TryActivateAbility` or a project wrapper.
2. GAS evaluates availability, tags, cost/cooldown checks, and custom activation checks.
3. `ActivateAbility` starts only after activation succeeds.
4. Validate target data at the authority boundary.
5. Call `CommitAbility` at the designed commitment point. If it returns false, terminate.
6. Start Ability Tasks for montage, waits, input, events, or targeting.
7. Apply authoritative Gameplay Effects and other gameplay results.
8. Route cosmetic feedback through Gameplay Cues or presentation systems.
9. On completion, interruption, cancel, invalid target, or task failure, clean up and call
   `EndAbility` with the correct canceled flag.

`CallActivateAbility` does not perform the normal availability check itself; do not use it
as the usual input entry point.

## Commit point

Commit determines when cost and cooldown become real. Examples:

- Immediate dodge: commit after direction and movement feasibility checks.
- Aimed spell: commit on confirm, not when targeting UI opens, unless design says aiming
  itself spends the resource.
- Melee attack: commit at accepted activation or at a montage-defined point, consistently.
- Channel: initial cost on start; periodic cost through a deliberate repeating effect/task.

Avoid applying gameplay before a failed commit. Avoid accidentally charging on canceled
target selection.

## Cleanup checklist

- stop or let GAS terminate active Ability Tasks;
- remove non-effect temporary state and input locks;
- clear spawned targeting helpers owned by the run;
- stop animation only when this ability owns it;
- end exactly once on every branch.

GAS ability architecture

# GAS ability architecture

## Enable and expose GAS

1. Enable the Gameplay Ability System plugin.
2. Add `GameplayAbilities`, `GameplayTags`, and `GameplayTasks` to the relevant module
   dependencies.
3. Give the ability-owning actor access to a `UAbilitySystemComponent` and implement
   `IAbilitySystemInterface` where appropriate.
4. Create the project's `UGameplayAbility` base class for shared failure, input, tag,
   targeting, and cleanup behavior.

## Choose ASC owner and avatar

`OwnerActor` owns the component; `AvatarActor` is the physical actor acting in the world.

| Need | Common layout |
|---|---|
| AI or pawn-local abilities reset with pawn | ASC on Pawn/Character; owner and avatar are that actor |
| Player abilities/cooldowns persist through pawn replacement | ASC on PlayerState; owner is PlayerState, avatar is current Pawn |

For a PlayerState-owned ASC, initialize actor info after server possession and on the owning
client when PlayerState/possession data is available. Reinitialize when the avatar changes.
Do not cache an obsolete avatar inside abilities.

## Granting

- Grant with `GiveAbility`/`FGameplayAbilitySpec` on authority; the Blueprint `Give Ability`
  node is ignored when the actor is not authoritative.
- Persist the returned `FGameplayAbilitySpecHandle` if equipment, loadout, or progression
  later removes/changes the grant.
- Separate the ability class from the grant's level, input binding, and source object.
- Decide whether a passive activates on grant, via effect/event trigger, or through an
  explicit startup pass; define its removal behavior too.

## Cross-skill boundaries

- Costs, cooldown effects, damage, attributes, stacking → `$unreal-gas-attributes-effects`.
- Ability/state/event/input tag taxonomy and query semantics → `$unreal-gameplay-tags`.
- Blueprint component/subsystem communication outside GAS → `$unreal-blueprint-architecture`.

Networking and prediction

# Networking and prediction

## Policy selector

| Policy | Use |
|---|---|
| Local Only | Purely local behavior that must not execute on server |
| Local Predicted | Responsive locally controlled ability with server validation and GAS-supported reconciliation |
| Server Initiated | Server starts it and clients receive replicated execution |
| Server Only | Authoritative server behavior with no predicted local activation |

Choose explicitly. The correct choice depends on ownership, responsiveness, cheating risk,
and whether every side effect participates in GAS prediction.

## Prediction-safe design

- Keep the server authoritative for target legality and gameplay results.
- Use GAS effects and ability mechanisms with prediction support where appropriate.
- Treat instant attribute/tag changes, arbitrary RPCs, external object mutation, and spawned
  Actors as separate rollback problems; do not assume GAS reverses them.
- Separate predicted presentation from authoritative hit/damage confirmation.
- Do not grant abilities from clients.

## Target data

1. Client may collect responsive aim/target data for a locally controlled ability.
2. Send through the supported GAS targeting/event path.
3. Server validates range, line of sight if required, source transform, team/target rules,
   cooldown/cost, and timing.
4. Server applies authoritative results.

## Multiplayer verification matrix

Test in editor and packaged Development builds with dedicated server where relevant:

- owning client with artificial latency and packet loss;
- listen server player;
- simulated proxy observing the ability;
- activation rejected by server;
- cancel before and after commit;
- avatar death/respawn during execution;
- target disappears during targeting;
- duplicate input press/release;
- montage interruption and late event;
- ability grant/removal during possession change.

Log role, owner/avatar, prediction key where available, spec handle, activation result,
failure tags, commit result, and termination reason.

Ability patterns

# Ability patterns

## Instant self ability

Example: heal, stance toggle request, short utility action.

1. Try activation.
2. Commit.
3. Make outgoing effect spec with ability level/context.
4. Apply to self or resolved target on authority/predicted supported path.
5. Trigger cosmetic cue.
6. End.

## Montage-driven melee

1. Activate and commit at the chosen commitment point.
2. Start a montage Ability Task.
3. Open damage window from a gameplay event/notify path owned by the ability.
4. Server validates hits and applies effects once per valid target/window.
5. Close the window.
6. End on montage completed, blended out, interrupted, or canceled; distinguish paths where
   recovery/cooldown rules differ.

## Target-confirmed projectile

1. Activate into targeting state without spending if design permits cancellation.
2. Ability Task waits for confirm/cancel and produces target data.
3. Server validates origin, direction/range, target legality, and fire rate.
4. Commit.
5. Spawn the authoritative projectile or apply the validated result.
6. End; clean up reticle/target actor on every path.

Do not assume a client-predicted spawned Actor automatically rolls back.

## Charged ability

1. Activate and record charge start in an instanced ability/task.
2. Wait for release, cancel, maximum charge, or interruption.
3. Compute charge from server-valid timing or bounded client data.
4. Commit on release.
5. Put charge magnitude into a SetByCaller value or level/context as designed.
6. Apply effect, feedback, and end.

## Channeled ability

1. Commit initial activation.
2. Apply an active state tag/effect.
3. Use tasks/effects for periodic work; do not create uncontrolled Tick logic.
4. Stop on input release, insufficient resource, blocking tag, death, invalid target, or
   external cancel.
5. Remove non-effect state and end.

## Passive ability

1. Define grant and activation trigger.
2. Apply persistent effects or register bounded event listeners.
3. On removal/end, remove active effects by retained handle and unregister listeners.
4. Test loadout swaps, respawn, duplicate grants, and reconnect.

UE 5.8 primary sources

# UE 5.8 primary sources

Verified 2026-07-19.

- [Gameplay Ability System](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-ability-system-for-unreal-engine)
- [Gameplay Ability System Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/understanding-the-unreal-engine-gameplay-ability-system)
- [Using Gameplay Abilities](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-gameplay-abilities-in-unreal-engine)
- [Ability Tasks](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-ability-tasks-in-unreal-engine)
- [Ability System Component and Attributes](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-ability-system-component-and-gameplay-attributes-in-unreal-engine)
- [Give Ability Blueprint API](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/GameplayAbilities/GiveAbility)
- [`UGameplayAbility` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/GameplayAbilities/UGameplayAbility)
- [Abilities in Lyra](https://dev.epicgames.com/documentation/en-us/unreal-engine/abilities-in-lyra-in-unreal-engine)

Version note: these Epic pages currently resolve to Unreal Engine 5.8. Prediction is not a
blanket rollback system. Epic specifically distinguishes supported predicted Gameplay Effect
behavior from instantaneous changes and other external side effects.

Troubleshooting

# Troubleshooting

## Ability will not activate

- Confirm the ability is granted on server and present in the ASC spec list.
- Confirm `InitAbilityActorInfo` has valid owner/avatar on this machine.
- Inspect activation required/blocked tags, cooldown tags, cost attributes, and custom checks.
- Capture failure tags and log role, ownership, and local control.
- Confirm the request uses `TryActivateAbility`/supported trigger.

## Activates on server but not owning client

- Check ASC replication and its owner chain.
- Reinitialize actor info when PlayerState and Pawn become available client-side.
- Check net execution policy and local ownership.

## Activates twice

- Ensure input is not routed both through numeric input binding and tag/event routing.
- Check duplicate grants and repeated bindings after respawn.
- Check whether both input press and gameplay event activate the same spec.

## Cost or cooldown missing

- Confirm `CommitAbility` executes and succeeds.
- Confirm cost/cooldown effects are configured and their attributes/tags exist.
- Confirm the commit point is reached on the correct authority/prediction path.
- Inspect active Gameplay Effects and cooldown tags on the ASC.

## Ability never ends

- Trace every task output and early-return branch to `EndAbility`.
- Handle montage completed, blend out, interrupted, and canceled outputs.
- Confirm custom Ability Tasks broadcast terminal delegates or end.
- Add one guarded termination helper in the project base ability.

## Cancel does not clean up

- Put persistent modifiers in effects that can be removed deterministically.
- Retain handles for spawned helpers/listeners/effects owned by the run.
- Remove manual movement/input locks during cancellation.
- Do not depend on a cosmetic Gameplay Cue to restore gameplay state.

## Client predicts a hit the server rejects

- Separate predicted feedback from confirmed damage.
- Validate target data on server.
- Check that non-GAS side effects are not assumed to roll back.
- Test under latency; log prediction and server result together.


unreal-gas-attributes-effects

Unreal 5.8 GAS Attributes and Effects

Model attributes and Gameplay Effects safely

---
name: unreal-gas-attributes-effects
description: Model, implement, tune, replicate, and debug Gameplay Attributes and Gameplay Effects in Unreal Engine 5.8 GAS. Use for AttributeSets, base versus current values, initialization, instant/duration/infinite effects, modifiers, SetByCaller values, magnitude or execution calculations, damage, healing, buffs, debuffs, periodic effects, stacking, clamping, replication, delegates, and UI updates.
---

# Unreal 5.8 GAS Attributes and Effects

## Select the representation

Read [`references/attribute-model.md`](references/attribute-model.md) and
[`references/effect-selector.md`](references/effect-selector.md).

- Use an **Attribute** for replicated numeric gameplay state that participates in GAS
  calculations and temporary modifiers.
- Use an **Instant Gameplay Effect** for a permanent base-value change such as damage,
  healing, or initial values.
- Use a **Duration Gameplay Effect** for a timed modifier or periodic effect.
- Use an **Infinite Gameplay Effect** for a removable modifier with no automatic expiry.
- Use **SetByCaller** when runtime code supplies one named magnitude to an effect spec.
- Use a **Modifier Magnitude Calculation** for one reusable magnitude computation.
- Use a **Gameplay Effect Execution Calculation** for authoritative multi-attribute or
  multi-output calculations such as damage resolution.

## Execute

1. Define AttributeSets in native code and group attributes by coherent lifetime/ownership.
2. Initialize through an applied Gameplay Effect, not ad hoc direct writes spread across
   constructors and possession code.
3. Build a Gameplay Effect asset as immutable configuration; create a Gameplay Effect Spec
   for runtime level, context, captured values, and SetByCaller magnitudes.
4. Apply effects through an Ability System Component using correct source and target context.
5. Clamp invariants explicitly. The AttributeSet system has no automatic min/max clamp.
6. Replicate player-visible attributes and notify GAS correctly so prediction corrections
   and listeners remain valid.
7. Drive UI from ASC attribute-change delegates; do not poll every frame.
8. Test removal, expiry, stacking, respawn/reinitialization, prediction correction, and
   server/client values.

Read [`references/calculations-and-patterns.md`](references/calculations-and-patterns.md)
for damage, healing, regeneration, buff, debuff, and initialization patterns. Read
[`references/replication-ui.md`](references/replication-ui.md) for replication and UI.

## Required answer format

Return:

1. **Attribute and AttributeSet layout**.
2. **Effect type and calculation method** with rationale.
3. **Ordered creation/application steps**, including source, target, context, level, and
   runtime magnitudes.
4. **Clamping and invariant locations**.
5. **Stacking, duration, periodic, and removal policy**.
6. **Authority, replication, UI notification, and verification**.

Do not invent Gameplay Effect settings, defaults, or prediction guarantees.

## Hard rules

- Gameplay Effect assets are definitions; do not mutate their shared defaults at runtime.
- Do not write temporary buffs directly into Attribute values.
- Do not rely on Data Table MinValue/MaxValue columns for clamping.
- Treat Instant effects as base-value changes; timed/infinite modifiers affect current
  values while active.
- Re-check critical invariants where final executed values are known; `PreAttributeChange`
  alone is not a universal final clamp.
- Keep gameplay authority on the server even when UI predicts or displays local changes.
- Do not poll attributes on Tick for UI.

Use [`references/troubleshooting.md`](references/troubleshooting.md) when values double,
fail to revert, exceed bounds, fail to replicate, or disagree across machines. See
[`references/sources.md`](references/sources.md) for the UE 5.8 source trail.

## Select the representation

Read [`references/attribute-model.md`](/unreal/unreal-gas-attributes-effects/attribute-model/) and
[`references/effect-selector.md`](/unreal/unreal-gas-attributes-effects/effect-selector/).

- Use an **Attribute** for replicated numeric gameplay state that participates in GAS
  calculations and temporary modifiers.
- Use an **Instant Gameplay Effect** for a permanent base-value change such as damage,
  healing, or initial values.
- Use a **Duration Gameplay Effect** for a timed modifier or periodic effect.
- Use an **Infinite Gameplay Effect** for a removable modifier with no automatic expiry.
- Use **SetByCaller** when runtime code supplies one named magnitude to an effect spec.
- Use a **Modifier Magnitude Calculation** for one reusable magnitude computation.
- Use a **Gameplay Effect Execution Calculation** for authoritative multi-attribute or
  multi-output calculations such as damage resolution.

## Execute

1. Define AttributeSets in native code and group attributes by coherent lifetime/ownership.
2. Initialize through an applied Gameplay Effect, not ad hoc direct writes spread across
   constructors and possession code.
3. Build a Gameplay Effect asset as immutable configuration; create a Gameplay Effect Spec
   for runtime level, context, captured values, and SetByCaller magnitudes.
4. Apply effects through an Ability System Component using correct source and target context.
5. Clamp invariants explicitly. The AttributeSet system has no automatic min/max clamp.
6. Replicate player-visible attributes and notify GAS correctly so prediction corrections
   and listeners remain valid.
7. Drive UI from ASC attribute-change delegates; do not poll every frame.
8. Test removal, expiry, stacking, respawn/reinitialization, prediction correction, and
   server/client values.

Read [`references/calculations-and-patterns.md`](/unreal/unreal-gas-attributes-effects/calculations-and-patterns/)
for damage, healing, regeneration, buff, debuff, and initialization patterns. Read
[`references/replication-ui.md`](/unreal/unreal-gas-attributes-effects/replication-ui/) for replication and UI.

## Required answer format

Return:

1. **Attribute and AttributeSet layout**.
2. **Effect type and calculation method** with rationale.
3. **Ordered creation/application steps**, including source, target, context, level, and
   runtime magnitudes.
4. **Clamping and invariant locations**.
5. **Stacking, duration, periodic, and removal policy**.
6. **Authority, replication, UI notification, and verification**.

Do not invent Gameplay Effect settings, defaults, or prediction guarantees.

## Hard rules

- Gameplay Effect assets are definitions; do not mutate their shared defaults at runtime.
- Do not write temporary buffs directly into Attribute values.
- Do not rely on Data Table MinValue/MaxValue columns for clamping.
- Treat Instant effects as base-value changes; timed/infinite modifiers affect current
  values while active.
- Re-check critical invariants where final executed values are known; `PreAttributeChange`
  alone is not a universal final clamp.
- Keep gameplay authority on the server even when UI predicts or displays local changes.
- Do not poll attributes on Tick for UI.

Use [`references/troubleshooting.md`](/unreal/unreal-gas-attributes-effects/troubleshooting/) when values double,
fail to revert, exceed bounds, fail to replicate, or disagree across machines. See
[`references/sources.md`](/unreal/unreal-gas-attributes-effects/sources/) for the UE 5.8 source trail.

unreal 5.8 gas attributes and effects model, implement, tune, replicate, and debug gameplay attributes and gameplay effects in unreal engine 5.8 gas. use for attributesets, base versus current values, initialization, instant/duration/infinite effects, modifiers, setbycaller values, magnitude or execution calculations, damage, healing, buffs, debuffs, periodic effects, stacking, clamping, replication, delegates, and ui updates. attribute model attribute model define attributesets gameplay attributes live in native uattributeset classes as fgameplayattributedata properties. group them by coherent ownership/lifetime, for example: - vitals: health, maxhealth, stamina, maxstamina; - combat: attackpower, armor, critical parameters; - movement: movespeed or movement multipliers; - transient meta inputs: incomingdamage or incominghealing. an asc can access registered attributesets. avoid one giant set merely because it is easy to create; avoid splitting so finely that related invariants become hard to enforce. base and current values - base value: durable value before temporary modifiers. - current value: evaluated result including active modifiers. - instant gameplay effects change base values. - duration and infinite effects modify current values while active and are undone when they expire or are removed. use an effect for changes. do not directly write a temporary bonus into the attribute, or its source/removal/stacking semantics become opaque. initialization 1. create an instant initialization gameplay effect with default attribute modifiers. 2. create a spec at the correct level or with setbycaller values. 3. apply it from authority after asc actor info and attributesets are ready. 4. guard against duplicate application on respawn/repossession. 5. if asc persists on playerstate, explicitly decide which attributes persist and which reset for the new avatar. invariants and clamping attributesets do not provide automatic min/max clamping. data table minvalue and maxvalue columns do not enforce bounds. enforce invariants deliberately: - clamp proposed current-value changes in preattributechange where appropriate; - clamp permanent executed results in postgameplayeffectexecute or the authoritative calculation/application path; - when maxhealth changes, decide whether health preserves absolute value, percentage, or only clamps down; - keep resource invariants explicit: 0 <= health <= maxhealth. do not assume a clamp in one hook covers every aggregator recalculation or execution path. calculations and action patterns calculations and action patterns direct damage with a meta-attribute 1. source ability creates an instant damage effect spec. 2. supply raw damage through a configured modifier or setbycaller tag. 3. execution calculation captures required source/target values and computes mitigated damage on authority. 4. write the result to transient incomingdamage. 5. in postgameplayeffectexecute, consume incomingdamage, set it back to zero, subtract from health, clamp, and signal death only on the valid transition. the meta-attribute keeps transient inputs separate from persistent health and centralizes post-damage rules. healing 1. create an instant effect with a positive health change or incominghealing meta value. 2. apply on authority with source context. 3. clamp final health to maxhealth. 4. emit ui/gameplay reactions after final value is known. timed buff 1. create a has duration effect. 2. add a modifier to the target attribute. 3. configure duration and stacking explicitly. 4. add owned/status tags through the current gameplay effect component model where needed. 5. apply and retain the active effect handle only if a later targeted removal needs it. 6. verify attribute returns exactly when the effect expires/removes. equipment or passive modifier 1. create an infinite effect per coherent source or bundle. 2. apply when equipped/granted. 3. store factivegameplayeffecthandle with the runtime equipment/passive instance. 4. remove by that handle on unequip/revoke. 5. test duplicate equip, load restore, owner change, and removal order. regeneration choose one model: - periodic gameplay effect for discrete authoritative ticks; - continuous modifier if the attribute semantics support it; - server-owned timer/system applying instant effects. define delay after damage, period, first tick timing, max clamp, stacking, and pause/block tags. do not add per-character tick without a measured need. max-value change pick and document one policy: - preserve absolute current value, then clamp; - preserve percentage: newcurrent = oldcurrent / oldmax newmax; - apply the same delta to current and max; - refill on increase. implement deliberately; no policy is universally correct. gameplay effect selector gameplay effect selector duration policy | need | duration policy | notes | |---|---|---| | damage, healing, purchase, permanent progression, initialization | instant | changes base value | | timed buff/debuff | has duration | modifier exists while active | | equipped/aura/passive modifier removed by handle/condition | infinite | explicit removal required | | damage/heal over time | has duration or infinite with period | period and duration/removal are separate decisions | magnitude method | need | method | |---|---| | constant or level-scaled data | scalable float / configured magnitude | | runtime caller supplies one named amount | setbycaller on the gameplay effect spec | | reusable magnitude from captured source/target attributes | modifier magnitude calculation | | multi-stage authoritative result, multiple captures/outputs, custom damage resolution | gameplay effect execution calculation | prefer the simplest method that expresses the rule. calculations add implementation and prediction constraints; fixed/scalable modifiers remain easier to inspect. modifier operation choose the operation from the desired math—additive, multiplicative, division, or override— and test multiple simultaneous sources. document whether percentages are intended to combine additively or multiplicatively; do not infer it from ui wording. runtime data gameplay effect assets are immutable definitions. at runtime: 1. make a gameplay effect context with instigator/source information. 2. make an outgoing gameplay effect spec at the desired level. 3. set setbycaller magnitudes and other spec data before application. 4. apply the spec to self or target asc. 5. retain the active effect handle when explicit removal or inspection is required. stacking design questions - aggregate by source or by target? - maximum stack count? - refresh, extend, or preserve duration on reapplication? - reset period on reapplication? - overflow behavior? - is each source independent, or should all instances combine? - which tags identify and inhibit the effect? test the exact configured behavior; stacking policy changes gameplay semantics, not just implementation. replication and ui replication and ui authority the server owns final gameplay state. clients may predict supported gas changes, but every effect and calculation must still be designed for rejection/correction. attribute replication for replicated attributes in native attributesets: 1. mark the attribute property for replication with a repnotify function. 2. add it to getlifetimereplicatedprops with the chosen replication condition/notification. 3. in the repnotify function, invoke gameplayattributerepnotify for that attributeset, attribute, and old value. 4. verify simulated proxies and the owning client receive expected changes and prediction corrections. follow the exact current engine macro/api signature in the 5.8 headers or epic sample code. ui update pattern 1. widget/view model obtains the correct asc for the represented actor. 2. read initial value once. 3. subscribe to getgameplayattributevaluechangedelegate(attribute) or the project wrapper. 4. on callback, format current/max values and update presentation. 5. unsubscribe/rebind when the represented actor or asc changes. do not poll attributes each frame. do not make the widget authoritative or apply gameplay effects from display logic. useful diagnostics log or inspect: - source and target asc owner/avatar; - effect class, spec level, context/instigator; - setbycaller keys and values; - active effect handle, duration, period, and stack count; - old/new base and current values where available; - server and client roles; - attribute delegate and repnotify execution. test initial join, late join, respawn, possession swap, effect expiry, effect removal, prediction rejection, and ui rebind. ue 5.8 primary sources ue 5.8 primary sources verified 2026-07-19. - gameplay attributes and attribute sets - gameplay effects - gameplay ability system overview - ability system component and attributes - ugameplayeffect api - egameplayeffectdurationtype api version note: these epic pages currently resolve to unreal engine 5.8. epic's 5.8 attributeset documentation explicitly states that the system has no built-in clamp and that the example metadata table's minvalue/maxvalue columns do not enforce bounds. troubleshooting troubleshooting value exceeds min/max - attributesets do not automatically clamp. - confirm both proposed current changes and final executed base changes are covered. - reapply invariant after max-value changes and aggregator recalculation where required. - do not rely on attributemetadata table minvalue/maxvalue columns. buff never reverts - confirm it is duration/infinite, not instant. - confirm removal targets the retained active effect handle or matching query. - check stacking: another source/stack may remain. - check manual direct writes that bypassed the effect aggregator. modifier applies twice - log every application site and active effect handle. - check duplicate initialization after possession/respawn. - check both server and client applying an unsupported non-predicted effect. - inspect stacking configuration and source aggregation. setbycaller is zero/missing - confirm the magnitude tag/name on the spec exactly matches the effect modifier. - set the value before application. - log missing keys as errors during development; do not silently accept zero for critical gameplay. client ui is stale - confirm attribute replicates and repnotify calls gameplayattributerepnotify. - confirm widget binds to the current asc after respawn/possession. - read initial value before waiting for changes. - ensure the ui listens to the attribute delegate rather than a local effect event only. server and client damage disagree - keep final damage execution authoritative. - verify captured attributes and snapshot/non-snapshot intent. - log source/target context, spec level, runtime magnitudes, and prediction path. - separate predicted hit feedback from confirmed health change. death fires repeatedly - detect the transition from above zero to zero after final clamping. - centralize death signaling in one authoritative path. - guard against repeated instant effects on an already-dead target with a state tag/rule.

Attribute model

# Attribute model

## Define AttributeSets

Gameplay Attributes live in native `UAttributeSet` classes as `FGameplayAttributeData`
properties. Group them by coherent ownership/lifetime, for example:

- vitals: Health, MaxHealth, Stamina, MaxStamina;
- combat: AttackPower, Armor, critical parameters;
- movement: MoveSpeed or movement multipliers;
- transient meta inputs: IncomingDamage or IncomingHealing.

An ASC can access registered AttributeSets. Avoid one giant set merely because it is easy to
create; avoid splitting so finely that related invariants become hard to enforce.

## Base and current values

- **Base value**: durable value before temporary modifiers.
- **Current value**: evaluated result including active modifiers.
- Instant Gameplay Effects change base values.
- Duration and Infinite effects modify current values while active and are undone when they
  expire or are removed.

Use an effect for changes. Do not directly write a temporary bonus into the attribute, or its
source/removal/stacking semantics become opaque.

## Initialization

1. Create an Instant initialization Gameplay Effect with default attribute modifiers.
2. Create a spec at the correct level or with SetByCaller values.
3. Apply it from authority after ASC actor info and AttributeSets are ready.
4. Guard against duplicate application on respawn/repossession.
5. If ASC persists on PlayerState, explicitly decide which attributes persist and which reset
   for the new avatar.

## Invariants and clamping

AttributeSets do not provide automatic min/max clamping. Data Table `MinValue` and `MaxValue`
columns do not enforce bounds.

Enforce invariants deliberately:

- clamp proposed current-value changes in `PreAttributeChange` where appropriate;
- clamp permanent executed results in `PostGameplayEffectExecute` or the authoritative
  calculation/application path;
- when MaxHealth changes, decide whether Health preserves absolute value, percentage, or only
  clamps down;
- keep resource invariants explicit: `0 <= Health <= MaxHealth`.

Do not assume a clamp in one hook covers every aggregator recalculation or execution path.

Calculations and action patterns

# Calculations and action patterns

## Direct damage with a meta-attribute

1. Source ability creates an Instant damage effect spec.
2. Supply raw damage through a configured modifier or SetByCaller tag.
3. Execution calculation captures required source/target values and computes mitigated damage
   on authority.
4. Write the result to transient `IncomingDamage`.
5. In `PostGameplayEffectExecute`, consume IncomingDamage, set it back to zero, subtract from
   Health, clamp, and signal death only on the valid transition.

The meta-attribute keeps transient inputs separate from persistent Health and centralizes
post-damage rules.

## Healing

1. Create an Instant effect with a positive health change or IncomingHealing meta value.
2. Apply on authority with source context.
3. Clamp final Health to MaxHealth.
4. Emit UI/gameplay reactions after final value is known.

## Timed buff

1. Create a Has Duration effect.
2. Add a modifier to the target Attribute.
3. Configure duration and stacking explicitly.
4. Add owned/status tags through the current Gameplay Effect component model where needed.
5. Apply and retain the active effect handle only if a later targeted removal needs it.
6. Verify attribute returns exactly when the effect expires/removes.

## Equipment or passive modifier

1. Create an Infinite effect per coherent source or bundle.
2. Apply when equipped/granted.
3. Store `FActiveGameplayEffectHandle` with the runtime equipment/passive instance.
4. Remove by that handle on unequip/revoke.
5. Test duplicate equip, load restore, owner change, and removal order.

## Regeneration

Choose one model:

- periodic Gameplay Effect for discrete authoritative ticks;
- continuous modifier if the Attribute semantics support it;
- server-owned timer/system applying instant effects.

Define delay after damage, period, first tick timing, max clamp, stacking, and pause/block tags.
Do not add per-character Tick without a measured need.

## Max-value change

Pick and document one policy:

- preserve absolute current value, then clamp;
- preserve percentage: `NewCurrent = OldCurrent / OldMax * NewMax`;
- apply the same delta to current and max;
- refill on increase.

Implement deliberately; no policy is universally correct.

Gameplay Effect selector

# Gameplay Effect selector

## Duration policy

| Need | Duration policy | Notes |
|---|---|---|
| Damage, healing, purchase, permanent progression, initialization | Instant | Changes base value |
| Timed buff/debuff | Has Duration | Modifier exists while active |
| Equipped/aura/passive modifier removed by handle/condition | Infinite | Explicit removal required |
| Damage/heal over time | Has Duration or Infinite with Period | Period and duration/removal are separate decisions |

## Magnitude method

| Need | Method |
|---|---|
| Constant or level-scaled data | Scalable Float / configured magnitude |
| Runtime caller supplies one named amount | SetByCaller on the Gameplay Effect Spec |
| Reusable magnitude from captured source/target attributes | Modifier Magnitude Calculation |
| Multi-stage authoritative result, multiple captures/outputs, custom damage resolution | Gameplay Effect Execution Calculation |

Prefer the simplest method that expresses the rule. Calculations add implementation and
prediction constraints; fixed/scalable modifiers remain easier to inspect.

## Modifier operation

Choose the operation from the desired math—additive, multiplicative, division, or override—
and test multiple simultaneous sources. Document whether percentages are intended to combine
additively or multiplicatively; do not infer it from UI wording.

## Runtime data

Gameplay Effect assets are immutable definitions. At runtime:

1. Make a Gameplay Effect Context with instigator/source information.
2. Make an outgoing Gameplay Effect Spec at the desired level.
3. Set SetByCaller magnitudes and other spec data before application.
4. Apply the spec to self or target ASC.
5. Retain the active effect handle when explicit removal or inspection is required.

## Stacking design questions

- Aggregate by source or by target?
- Maximum stack count?
- Refresh, extend, or preserve duration on reapplication?
- Reset period on reapplication?
- Overflow behavior?
- Is each source independent, or should all instances combine?
- Which tags identify and inhibit the effect?

Test the exact configured behavior; stacking policy changes gameplay semantics, not just
implementation.

Replication and UI

# Replication and UI

## Authority

The server owns final gameplay state. Clients may predict supported GAS changes, but every
effect and calculation must still be designed for rejection/correction.

## Attribute replication

For replicated attributes in native AttributeSets:

1. Mark the attribute property for replication with a RepNotify function.
2. Add it to `GetLifetimeReplicatedProps` with the chosen replication condition/notification.
3. In the RepNotify function, invoke `GAMEPLAYATTRIBUTE_REPNOTIFY` for that AttributeSet,
   attribute, and old value.
4. Verify simulated proxies and the owning client receive expected changes and prediction
   corrections.

Follow the exact current engine macro/API signature in the 5.8 headers or Epic sample code.

## UI update pattern

1. Widget/view model obtains the correct ASC for the represented actor.
2. Read initial value once.
3. Subscribe to `GetGameplayAttributeValueChangeDelegate(Attribute)` or the project wrapper.
4. On callback, format current/max values and update presentation.
5. Unsubscribe/rebind when the represented actor or ASC changes.

Do not poll attributes each frame. Do not make the widget authoritative or apply gameplay
effects from display logic.

## Useful diagnostics

Log or inspect:

- source and target ASC owner/avatar;
- effect class, spec level, context/instigator;
- SetByCaller keys and values;
- active effect handle, duration, period, and stack count;
- old/new base and current values where available;
- server and client roles;
- attribute delegate and RepNotify execution.

Test initial join, late join, respawn, possession swap, effect expiry, effect removal,
prediction rejection, and UI rebind.

UE 5.8 primary sources

# UE 5.8 primary sources

Verified 2026-07-19.

- [Gameplay Attributes and Attribute Sets](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-attributes-and-attribute-sets-for-the-gameplay-ability-system-in-unreal-engine)
- [Gameplay Effects](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-effects-for-the-gameplay-ability-system-in-unreal-engine)
- [Gameplay Ability System Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/understanding-the-unreal-engine-gameplay-ability-system)
- [Ability System Component and Attributes](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-ability-system-component-and-gameplay-attributes-in-unreal-engine)
- [`UGameplayEffect` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/GameplayAbilities/UGameplayEffect)
- [`EGameplayEffectDurationType` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/GameplayAbilities/EGameplayEffectDurationType)

Version note: these Epic pages currently resolve to Unreal Engine 5.8. Epic's 5.8
AttributeSet documentation explicitly states that the system has no built-in clamp and that
the example metadata table's MinValue/MaxValue columns do not enforce bounds.

Troubleshooting

# Troubleshooting

## Value exceeds min/max

- AttributeSets do not automatically clamp.
- Confirm both proposed current changes and final executed base changes are covered.
- Reapply invariant after Max-value changes and aggregator recalculation where required.
- Do not rely on AttributeMetaData table MinValue/MaxValue columns.

## Buff never reverts

- Confirm it is Duration/Infinite, not Instant.
- Confirm removal targets the retained active effect handle or matching query.
- Check stacking: another source/stack may remain.
- Check manual direct writes that bypassed the effect aggregator.

## Modifier applies twice

- Log every application site and active effect handle.
- Check duplicate initialization after possession/respawn.
- Check both server and client applying an unsupported non-predicted effect.
- Inspect stacking configuration and source aggregation.

## SetByCaller is zero/missing

- Confirm the magnitude tag/name on the spec exactly matches the effect modifier.
- Set the value before application.
- Log missing keys as errors during development; do not silently accept zero for critical
  gameplay.

## Client UI is stale

- Confirm attribute replicates and RepNotify calls `GAMEPLAYATTRIBUTE_REPNOTIFY`.
- Confirm widget binds to the current ASC after respawn/possession.
- Read initial value before waiting for changes.
- Ensure the UI listens to the attribute delegate rather than a local effect event only.

## Server and client damage disagree

- Keep final damage execution authoritative.
- Verify captured attributes and snapshot/non-snapshot intent.
- Log source/target context, spec level, runtime magnitudes, and prediction path.
- Separate predicted hit feedback from confirmed Health change.

## Death fires repeatedly

- Detect the transition from above zero to zero after final clamping.
- Centralize death signaling in one authoritative path.
- Guard against repeated Instant effects on an already-dead target with a state tag/rule.


unreal-insights-profiling

Unreal 5.8 Insights Profiling

Capture and isolate Unreal performance bottlenecks

---
name: unreal-insights-profiling
description: Capture, analyze, compare, and automate performance evidence in Unreal Engine 5.8. Use for Unreal Insights, Timing Insights, Memory Insights, Networking Insights, Task Graph Insights, stat unit, stat commands, GPU Profiler, trace channels, CPU/GPU/thread bottlenecks, hitches, stalls, garbage collection, asset loading, memory growth, packet cost, custom trace instrumentation, performance budgets, or before/after regression captures.
---

# Unreal 5.8 Insights Profiling

## Establish the measurement contract

Read [`references/capture-contract.md`](references/capture-contract.md), then choose the narrowest
tool in [`references/tool-selector.md`](references/tool-selector.md).

1. State target platform, hardware class, build configuration, resolution, quality tier, map,
   camera path, player count, and workload.
2. State the frame, hitch, memory, load-time, or bandwidth budget in measurable units.
3. Reproduce without editor-only noise when possible; use a Development or Test packaged build.
4. Triage with `stat unit`/`stat unitgraph`; identify Game, Draw, RHI, GPU, memory, loading, or net.
5. Capture only the trace channels needed for the hypothesis and mark the measured interval.
6. Analyze inclusive/exclusive cost, thread dependencies, spikes, counts, and the critical path.
7. Change one causal variable, repeat the same workload, and compare milliseconds or bytes.
8. Preserve the baseline, candidate, capture metadata, and acceptance result.

Load only what applies:

- [`references/first-pass-triage.md`](references/first-pass-triage.md)
- [`references/timing-insights-cpu.md`](references/timing-insights-cpu.md)
- [`references/gpu-and-render-thread.md`](references/gpu-and-render-thread.md)
- [`references/hitches-loading-and-gc.md`](references/hitches-loading-and-gc.md)
- [`references/memory-insights.md`](references/memory-insights.md)
- [`references/network-task-and-ui.md`](references/network-task-and-ui.md)
- [`references/instrumentation-and-exports.md`](references/instrumentation-and-exports.md)
- [`references/regression-workflow.md`](references/regression-workflow.md)

## Required answer format

Return:

1. **Question and budget** being tested.
2. **Representative workload** and capture environment.
3. **Exact tool, channels, commands, and capture interval**.
4. **Observed bound and evidence**, separating sustained cost from spikes.
5. **Ranked causal suspects**, with inclusive/exclusive time or byte evidence.
6. **Single next experiment or fix** and its predicted measurable effect.
7. **Before/after comparison** and pass/fail result.
8. **Uncertainty**, capture overhead, and missing evidence.

## Hard rules

- Report frame time in milliseconds; FPS alone hides magnitude and variability.
- Do not profile a Debug build or treat PIE/editor numbers as shipping evidence.
- Do not infer CPU- versus GPU-bound from FPS; use thread/GPU timing and synchronization context.
- Do not treat GPU time as causal when it includes idle/wait time; inspect the frame and GPU event tree.
- Keep trace channels narrow. Tracing consumes CPU, memory, disk, and bandwidth and can perturb results.
- Capture spikes and steady state separately; averages can hide harmful hitches.
- Memory allocation tracing must start with the process; late connect cannot reconstruct earlier allocations.
- Use bookmarks for infrequent state changes, timers/counters for high-frequency events.
- Preserve same hardware, build, resolution, quality, workload, and capture length for A/B comparisons.
- Optimize the current top cost, re-profile, and stop when the declared budget is met.

See [`references/sources.md`](references/sources.md) for the UE 5.8 primary-source trail.

## Establish the measurement contract

Read [`references/capture-contract.md`](/unreal/unreal-insights-profiling/capture-contract/), then choose the narrowest
tool in [`references/tool-selector.md`](/unreal/unreal-insights-profiling/tool-selector/).

1. State target platform, hardware class, build configuration, resolution, quality tier, map,
   camera path, player count, and workload.
2. State the frame, hitch, memory, load-time, or bandwidth budget in measurable units.
3. Reproduce without editor-only noise when possible; use a Development or Test packaged build.
4. Triage with `stat unit`/`stat unitgraph`; identify Game, Draw, RHI, GPU, memory, loading, or net.
5. Capture only the trace channels needed for the hypothesis and mark the measured interval.
6. Analyze inclusive/exclusive cost, thread dependencies, spikes, counts, and the critical path.
7. Change one causal variable, repeat the same workload, and compare milliseconds or bytes.
8. Preserve the baseline, candidate, capture metadata, and acceptance result.

Load only what applies:

- [`references/first-pass-triage.md`](/unreal/unreal-insights-profiling/first-pass-triage/)
- [`references/timing-insights-cpu.md`](/unreal/unreal-insights-profiling/timing-insights-cpu/)
- [`references/gpu-and-render-thread.md`](/unreal/unreal-insights-profiling/gpu-and-render-thread/)
- [`references/hitches-loading-and-gc.md`](/unreal/unreal-insights-profiling/hitches-loading-and-gc/)
- [`references/memory-insights.md`](/unreal/unreal-insights-profiling/memory-insights/)
- [`references/network-task-and-ui.md`](/unreal/unreal-insights-profiling/network-task-and-ui/)
- [`references/instrumentation-and-exports.md`](/unreal/unreal-insights-profiling/instrumentation-and-exports/)
- [`references/regression-workflow.md`](/unreal/unreal-insights-profiling/regression-workflow/)

## Required answer format

Return:

1. **Question and budget** being tested.
2. **Representative workload** and capture environment.
3. **Exact tool, channels, commands, and capture interval**.
4. **Observed bound and evidence**, separating sustained cost from spikes.
5. **Ranked causal suspects**, with inclusive/exclusive time or byte evidence.
6. **Single next experiment or fix** and its predicted measurable effect.
7. **Before/after comparison** and pass/fail result.
8. **Uncertainty**, capture overhead, and missing evidence.

## Hard rules

- Report frame time in milliseconds; FPS alone hides magnitude and variability.
- Do not profile a Debug build or treat PIE/editor numbers as shipping evidence.
- Do not infer CPU- versus GPU-bound from FPS; use thread/GPU timing and synchronization context.
- Do not treat GPU time as causal when it includes idle/wait time; inspect the frame and GPU event tree.
- Keep trace channels narrow. Tracing consumes CPU, memory, disk, and bandwidth and can perturb results.
- Capture spikes and steady state separately; averages can hide harmful hitches.
- Memory allocation tracing must start with the process; late connect cannot reconstruct earlier allocations.
- Use bookmarks for infrequent state changes, timers/counters for high-frequency events.
- Preserve same hardware, build, resolution, quality, workload, and capture length for A/B comparisons.
- Optimize the current top cost, re-profile, and stop when the declared budget is met.

See [`references/sources.md`](/unreal/unreal-insights-profiling/sources/) for the UE 5.8 primary-source trail.

unreal 5.8 insights profiling capture, analyze, compare, and automate performance evidence in unreal engine 5.8. use for unreal insights, timing insights, memory insights, networking insights, task graph insights, stat unit, stat commands, gpu profiler, trace channels, cpu/gpu/thread bottlenecks, hitches, stalls, garbage collection, asset loading, memory growth, packet cost, custom trace instrumentation, performance budgets, or before/after regression captures. capture contract capture contract record this metadata before interpreting a trace: | field | required value | |---|---| | target | platform, device model/cpu/gpu/ram, driver/os | | build | changelist/commit, development/test/shipping, packaged/editor | | display | output resolution, screen percentage/dynamic resolution, refresh/vsync | | quality | device profile, scalability groups, ray tracing/upscaler path | | workload | map, save/state, camera path, player/ai/effect counts, duration | | budget | frame ms and percentile/hitch threshold; memory/load/net budget if relevant | | capture | command line, channels, warm-up, marked start/end, trace filename | frame budgets before platform overhead or safety margin: | target | frame time | |---|---:| | 30 fps | 33.33 ms | | 60 fps | 16.67 ms | | 90 fps | 11.11 ms | | 120 fps | 8.33 ms | use a repeatable traversal or automated scenario. warm shader/asset caches only when measuring steady state; preserve a cold-start run when first-use hitch or loading is the question. record both if players experience both. reject comparisons that changed more than the intended variable, ran different content paths, used different thermal/power states, or silently changed resolution/scalability. first-pass triage first-pass triage establish the bound 1. run a non-debug build with the target device profile and resolution. 2. disable smoothing/vsync/frame caps only when they conceal the bound; record the change. 3. enter stat unit; add stat unitgraph and stat raw when spikes or filtering matter. 4. reproduce the workload for a fixed interval. 5. compare frame with game, draw, rhit, and gpu. interpretation: | pattern | working classification | next capture | |---|---|---| | frame follows game | game-thread bound | cpu/frame/bookmark; inspect game thread | | frame follows draw | render-thread bound | cpu/frame/gpu; inspect rendering submission | | frame follows rhit | rhi/submission/driver bound | cpu/gpu plus platform graphics profiler | | gpu stands alone near frame | gpu bound | profilegpu, gpu trace | | all appear below frame | cap, wait, sync, present, task dependency | timing + context switch; inspect waits | | rare raw spikes | hitch | bookmark and narrow hitch capture | stat unit is directional, not final proof. parallel cpu and gpu work, pipelining, idle time, vsync, and asynchronous compute can make similar numbers misleading. fast probes - lower primary resolution/screen percentage while holding content constant. a material gpu gain implicates pixel/resolution-scaled work; no gain does not prove a cpu bottleneck. - pause or freeze simulation to separate simulation-fed rendering changes from a stable frame. - disable one major feature with a supported cvar for diagnosis, then restore it. treat the delta as attribution evidence, not automatically as the shipping fix. - use stat scenerendering, stat rhi, stat gpu, stat game, stat anim, stat slate, or the subsystem stat only after the first bound is known. gpu and render thread gpu and render thread attribute gpu cost 1. confirm gpu is plausibly the bound with stat unit. 2. run stat gpu for a live overview. 3. capture one representative frame with profilegpu or ctrl+shift+;. 4. expand the event tree from the largest millisecond pass to its children. 5. repeat at the same camera, resolution, screen percentage, and quality. 6. toggle one supported renderer feature or quality control and compare the same pass. gpu time may contain idle time. asynchronous compute overlaps passes, so individual event totals can overlap or appear inflated. disable async compute only for isolated diagnosis when epic's subsystem guide explicitly recommends it; restore it for the real end-to-end measurement. separate submission from shading | evidence | likely direction | |---|---| | draw/render thread dominates, many primitives/sections | reduce submissions, components, sections, visibility work | | gpu base pass dominates | material/pixel coverage/geometry path | | shadows dominate | light/shadow method, invalidation, caster coverage | | translucency/post dominates | screen coverage, layer count, resolution, effect quality | | lowering resolution helps strongly | pixel-bound passes/upscaler tradeoff | | lowering resolution barely helps | geometry/submission/cpu or fixed-cost gpu work | use the rendering-performance skill only after the pass or submission cost is identified. hitches, loading, and garbage collection hitches, loading, and garbage collection capture a hitch 1. set an explicit hitch threshold for the target experience; use stat hitches or stat dumphitches for fast detection where useful. 2. display stat unitgraph, toggle stat raw, and reproduce the hitch. 3. add bookmarks immediately before/after the action that triggers it. 4. trace cpu,frame,bookmark plus only the suspected channel: loadtime, file, or stats. 5. inspect the exact slow frame and the preceding work; asynchronous requests often cause a later wait. symptom routing | hitch shape | inspect | |---|---| | first use of asset/effect | async load, shader/pso readiness, construction, audio decode | | periodic spike | gc, streaming update, autosave/telemetry, scheduled subsystem | | entering region | world partition/level/texture/nanite streaming and file io | | mass spawn/despawn | object construction, registration, physics/nav, gc pressure | | camera cut | visibility burst, vsm pages, streaming, post/upscaler history | for loading, correlate asset loading events with file reads and game-thread waits. a long async load is not necessarily a hitch unless the critical thread blocks for it or the workload saturates io/cpu. for gc, inspect allocation/object churn before the collection, collection duration, unreachable-object processing, and post-gc work. reduce avoidable churn or distribute work; do not merely raise the gc interval if that creates a larger eventual pause or excess memory. instrumentation and exports instrumentation and exports use built-in trace events before inventing a custom event stream. c++ instrumentation - wrap important cpu scopes with the tracecpuprofilereventscope macro family. - emit tracebookmark for infrequent state transitions such as entering a boss phase or opening a menu. - use trace counters for quantities that change frequently: active enemies, queued requests, bytes, or pool occupancy. - use llmscope tags for memory categories that should appear in llm and allocation traces. do not emit per-object bookmarks every frame. excess instrumentation changes the workload and can make traces too large to analyze. export for repeatable analysis unreal insights supports headless analysis and response commands. a representative invocation is: text unrealinsights.exe -opentracefile=path/file.utrace -autoquit -noui -execonanalysiscompletecmd="@=d:\tests\export.rsp" use timinginsights.exporttimerstatistics in the response workflow to export aggregate timer data for named regions. store the response file, capture contract, and threshold logic beside the test. keep raw .utrace files for regressions that require timeline inspection; csv summaries cannot explain dependencies or wait chains by themselves. memory insights memory insights allocation tracing must be enabled from process start. for a packaged project, use development mode. text mygame.exe -trace=default,memory mygame.exe -trace=default,memory,metadata,assetmetadata the metadata channels enable asset/class filtering but add trace cost and volume. select them only when the question requires attribution at that level. query patterns | question | comparison/query | |---|---| | what is live at time t? | live allocations at t, grouped by tag/callstack | | what grew during action a? | allocations between pre-a and post-a markers still live afterward | | is it a leak? | repeat a several times; inspect monotonic retained growth after cleanup | | what churns? | high allocation/free event rate with limited net growth | | which asset/class owns memory? | metadata/assetmetadata grouping and callstacks | correlate detailed allocation graphs, llm tag tracks, modules, and timing events. distinguish: - committed/resident/platform memory from traced allocations; - cpu memory from gpu memory; - cache growth that stabilizes from unbounded retained growth; - expected streaming residency from leaked ownership. capture startup when startup allocations matter. late connect cannot reconstruct allocations made before the memory channel was active. network, task graph, and ui traces network, task graph, and ui traces networking insights start each relevant client instance with: text -trace=net -nettrace=1 when tracing an editor instance to a separate local insights store, add -tracehost=localhost as required. choose verbosity greater than zero and raise it only when the missing packet detail justifies the overhead. inspect packet sizes/timeline, connection direction, object/property/rpc content, inclusive/exclusive net stats, frequency, bursts, and retransmission/transport context. optimize semantic frequency and payload ownership before compressing an already-wrong replication pattern. task graph use: text -trace=default,task inspect task prerequisites, worker occupancy, critical path, parent waits, queue delay, and task size. do not split work into smaller tasks when scheduling overhead already dominates; do not merge tasks when one serial task blocks the frame and parallelism is available. ui and slate triage with stat slate, stat ui, and widget-specific tools. enable the built-in slate insights plugin and capture with -trace=slate. in slate frame view, correlate invalidation reasons, update reasons, layout/prepass, paint, volatility, draw-element growth, and game/render thread cost. repeated full-tree invalidation or per-frame binding work is usually a structural issue; confirm it in the trace before adding caches or invalidation panels. regression workflow regression workflow baseline and candidate 1. freeze scenario, device profile, build settings, camera/input script, warm/cold state, and duration. 2. run multiple baseline samples; retain raw traces and summary metrics. 3. apply one change. 4. run the same number of candidate samples in comparable thermal/background conditions. 5. compare milliseconds, memory, bandwidth, hitch count, and percentile relevant to the budget. 6. inspect a representative trace when the aggregate moved unexpectedly. minimum report: | metric | baseline | candidate | delta | budget | result | |---|---:|---:|---:|---:|---| | median frame ms | | | | | | | p95/p99 or worst-frame ms | | | | | | | bound thread/pass ms | | | | | | | hitch count over threshold | | | | | | | memory/load/net metric | | | | | | do not call a change a win when it shifts cost outside the sampled interval, trades a rare severe hitch for a better average, changes image quality/gameplay, or exceeds another budget. keep a safety margin; meeting 16.67 ms only in an ideal trace is not a robust 60 fps target. ue 5.8 primary sources ue 5.8 primary sources - introduction to performance profiling and configuration - unreal insights - unreal insights trace quick start - unreal insights reference - timing insights timers and counters - trace developer guide - memory insights - networking insights - task graph insights - slate insights - stat commands - graphics programming overview - common performance considerations pages were checked against ue 5.8 documentation on 2026-07-19. reconfirm channel presets, platform support, trace overhead, command syntax, and export commands after an engine upgrade. timing insights and cpu timing insights and cpu capture launch with a narrow set such as: text -trace=default,cpu,frame,bookmark or start a file capture at runtime: text trace.file perfcase.utrace cpu,frame,bookmark trace.bookmark warmupcomplete trace.bookmark testbegin trace.bookmark testend trace.stop without an explicit path, trace files go under saved/profiling. check active channels with trace.status. use trace.enable, trace.disable, trace.pause, and trace.resume to reduce unwanted data, but do not expect late-enabled channels to reconstruct prior events. analyze 1. select only the marked test interval. 2. inspect game, render, rhi, worker, and named threads; do not rank timers across unrelated frames. 3. sort timer aggregation by inclusive time to find large subtrees, then exclusive time to find the scope itself. high inclusive/low exclusive cost means the children own the time. 4. inspect call count. a small scope called thousands of times may need structural batching. 5. open a slow frame and follow the critical dependency path, waits, task prerequisites, and long serial regions. 6. compare median/typical frames separately from worst hitches. common cpu shapes - long game-thread scope -> gameplay/blueprint/tick/ai/physics/gc work. - render-thread submissions -> primitive count, material sections, visibility, shadow/light setup. - worker tasks complete after parent waits -> imbalance, insufficient parallel work, dependency chain. - large gaps/waits -> synchronization, io, locks, frame cap, or starvation; not necessarily "free cpu." - thousands of tiny events -> per-object/tick architecture, dispatch overhead, or trace over-detail. tool selector tool selector | question | start with | escalate to | |---|---|---| | which side owns the frame? | stat unit, stat unitgraph | timing insights + gpu events | | which cpu scope/thread is slow? | timing insights cpu tracks | task/context-switch trace, custom scopes | | which gpu pass is slow? | stat gpu, profilegpu | gpu trace, renderdoc/platform profiler | | why did one frame hitch? | stat unitgraph, bookmark | timing insights, load/file/gc tracks | | why is memory growing? | platform/llm stats | memory insights from process start | | which asset loaded or blocked? | async-loading stats | asset loading insights + file/loadtime channels | | what consumes bandwidth? | stat net where applicable | networking insights packet/content/stats | | are tasks waiting or serialized? | cpu trace | task graph + context-switch channels | | is ui/slate expensive? | stat slate, stat ui | slate trace/insights tracks | | did a change regress? | repeatable stat/trace capture | exported timer statistics in ci | use renderdoc or a platform graphics debugger for pipeline/resource correctness inside one frame; use insights and profilegpu to decide which frame/pass deserves that inspection.

Capture contract

# Capture contract

Record this metadata before interpreting a trace:

| Field | Required value |
|---|---|
| Target | platform, device model/CPU/GPU/RAM, driver/OS |
| Build | changelist/commit, Development/Test/Shipping, packaged/editor |
| Display | output resolution, screen percentage/dynamic resolution, refresh/VSync |
| Quality | device profile, scalability groups, ray tracing/upscaler path |
| Workload | map, save/state, camera path, player/AI/effect counts, duration |
| Budget | frame ms and percentile/hitch threshold; memory/load/net budget if relevant |
| Capture | command line, channels, warm-up, marked start/end, trace filename |

Frame budgets before platform overhead or safety margin:

| Target | Frame time |
|---|---:|
| 30 fps | 33.33 ms |
| 60 fps | 16.67 ms |
| 90 fps | 11.11 ms |
| 120 fps | 8.33 ms |

Use a repeatable traversal or automated scenario. Warm shader/asset caches only when measuring
steady state; preserve a cold-start run when first-use hitch or loading is the question. Record both
if players experience both.

Reject comparisons that changed more than the intended variable, ran different content paths, used
different thermal/power states, or silently changed resolution/scalability.

First-pass triage

# First-pass triage

## Establish the bound

1. Run a non-Debug build with the target device profile and resolution.
2. Disable smoothing/VSync/frame caps only when they conceal the bound; record the change.
3. Enter `stat unit`; add `stat unitgraph` and `stat raw` when spikes or filtering matter.
4. Reproduce the workload for a fixed interval.
5. Compare Frame with Game, Draw, RHIT, and GPU.

Interpretation:

| Pattern | Working classification | Next capture |
|---|---|---|
| Frame follows Game | game-thread bound | CPU/frame/bookmark; inspect Game thread |
| Frame follows Draw | render-thread bound | CPU/frame/gpu; inspect rendering submission |
| Frame follows RHIT | RHI/submission/driver bound | CPU/GPU plus platform graphics profiler |
| GPU stands alone near Frame | GPU bound | `profilegpu`, GPU trace |
| all appear below Frame | cap, wait, sync, present, task dependency | timing + context switch; inspect waits |
| rare raw spikes | hitch | bookmark and narrow hitch capture |

`stat unit` is directional, not final proof. Parallel CPU and GPU work, pipelining, idle time, VSync,
and asynchronous compute can make similar numbers misleading.

## Fast probes

- Lower primary resolution/screen percentage while holding content constant. A material GPU gain
  implicates pixel/resolution-scaled work; no gain does not prove a CPU bottleneck.
- Pause or freeze simulation to separate simulation-fed rendering changes from a stable frame.
- Disable one major feature with a supported CVar for diagnosis, then restore it. Treat the delta as
  attribution evidence, not automatically as the shipping fix.
- Use `stat sceneRendering`, `stat rhi`, `stat gpu`, `stat game`, `stat anim`, `stat slate`, or the
  subsystem stat only after the first bound is known.

GPU and render thread

# GPU and render thread

## Attribute GPU cost

1. Confirm GPU is plausibly the bound with `stat unit`.
2. Run `stat gpu` for a live overview.
3. Capture one representative frame with `profilegpu` or `Ctrl+Shift+;`.
4. Expand the event tree from the largest millisecond pass to its children.
5. Repeat at the same camera, resolution, screen percentage, and quality.
6. Toggle one supported renderer feature or quality control and compare the same pass.

GPU time may contain idle time. Asynchronous compute overlaps passes, so individual event totals can
overlap or appear inflated. Disable async compute only for isolated diagnosis when Epic's subsystem
guide explicitly recommends it; restore it for the real end-to-end measurement.

## Separate submission from shading

| Evidence | Likely direction |
|---|---|
| Draw/Render thread dominates, many primitives/sections | reduce submissions, components, sections, visibility work |
| GPU base pass dominates | material/pixel coverage/geometry path |
| shadows dominate | light/shadow method, invalidation, caster coverage |
| translucency/post dominates | screen coverage, layer count, resolution, effect quality |
| lowering resolution helps strongly | pixel-bound passes/upscaler tradeoff |
| lowering resolution barely helps | geometry/submission/CPU or fixed-cost GPU work |

Use the rendering-performance skill only after the pass or submission cost is identified.

# Hitches, loading, and garbage collection

## Capture a hitch

1. Set an explicit hitch threshold for the target experience; use `stat hitches` or `stat dumphitches`
   for fast detection where useful.
2. Display `stat unitgraph`, toggle `stat raw`, and reproduce the hitch.
3. Add bookmarks immediately before/after the action that triggers it.
4. Trace `cpu,frame,bookmark` plus only the suspected channel: `loadtime`, `file`, or `stats`.
5. Inspect the exact slow frame and the preceding work; asynchronous requests often cause a later wait.

## Symptom routing

| Hitch shape | Inspect |
|---|---|
| first use of asset/effect | async load, shader/PSO readiness, construction, audio decode |
| periodic spike | GC, streaming update, autosave/telemetry, scheduled subsystem |
| entering region | World Partition/level/texture/Nanite streaming and file IO |
| mass spawn/despawn | object construction, registration, physics/nav, GC pressure |
| camera cut | visibility burst, VSM pages, streaming, post/upscaler history |

For loading, correlate Asset Loading events with file reads and Game-thread waits. A long async load is
not necessarily a hitch unless the critical thread blocks for it or the workload saturates IO/CPU.

For GC, inspect allocation/object churn before the collection, collection duration, unreachable-object
processing, and post-GC work. Reduce avoidable churn or distribute work; do not merely raise the GC
interval if that creates a larger eventual pause or excess memory.

Instrumentation and exports

# Instrumentation and exports

Use built-in trace events before inventing a custom event stream.

## C++ instrumentation

- Wrap important CPU scopes with the `TRACE_CPUPROFILER_EVENT_SCOPE_*` macro family.
- Emit `TRACE_BOOKMARK` for infrequent state transitions such as entering a boss phase or opening a
  menu.
- Use trace counters for quantities that change frequently: active enemies, queued requests, bytes,
  or pool occupancy.
- Use `LLM_SCOPE` tags for memory categories that should appear in LLM and allocation traces.

Do not emit per-object bookmarks every frame. Excess instrumentation changes the workload and can
make traces too large to analyze.

## Export for repeatable analysis

Unreal Insights supports headless analysis and response commands. A representative invocation is:

```text
UnrealInsights.exe -OpenTraceFile=path/file.utrace -AutoQuit -NoUI -ExecOnAnalysisCompleteCmd="@=D:\Tests\export.rsp"
```

Use `TimingInsights.ExportTimerStatistics` in the response workflow to export aggregate timer data for
named regions. Store the response file, capture contract, and threshold logic beside the test. Keep
raw `.utrace` files for regressions that require timeline inspection; CSV summaries cannot explain
dependencies or wait chains by themselves.

Memory Insights

# Memory Insights

Allocation tracing must be enabled from process start. For a packaged project, use Development mode.

```text
MyGame.exe -trace=default,memory
MyGame.exe -trace=default,memory,metadata,assetmetadata
```

The metadata channels enable asset/class filtering but add trace cost and volume. Select them only
when the question requires attribution at that level.

## Query patterns

| Question | Comparison/query |
|---|---|
| What is live at time T? | live allocations at T, grouped by tag/callstack |
| What grew during action A? | allocations between pre-A and post-A markers still live afterward |
| Is it a leak? | repeat A several times; inspect monotonic retained growth after cleanup |
| What churns? | high allocation/free event rate with limited net growth |
| Which asset/class owns memory? | metadata/assetmetadata grouping and callstacks |

Correlate detailed allocation graphs, LLM tag tracks, modules, and Timing events. Distinguish:

- committed/resident/platform memory from traced allocations;
- CPU memory from GPU memory;
- cache growth that stabilizes from unbounded retained growth;
- expected streaming residency from leaked ownership.

Capture startup when startup allocations matter. Late connect cannot reconstruct allocations made
before the memory channel was active.

Network, task graph, and UI traces

# Network, task graph, and UI traces

## Networking Insights

Start each relevant client instance with:

```text
-trace=net -NetTrace=1
```

When tracing an editor instance to a separate local Insights store, add `-tracehost=localhost` as
required. Choose verbosity greater than zero and raise it only when the missing packet detail justifies
the overhead.

Inspect packet sizes/timeline, connection direction, object/property/RPC content, inclusive/exclusive
Net Stats, frequency, bursts, and retransmission/transport context. Optimize semantic frequency and
payload ownership before compressing an already-wrong replication pattern.

## Task Graph

Use:

```text
-trace=default,task
```

Inspect task prerequisites, worker occupancy, critical path, parent waits, queue delay, and task size.
Do not split work into smaller tasks when scheduling overhead already dominates; do not merge tasks
when one serial task blocks the frame and parallelism is available.

## UI and Slate

Triage with `stat slate`, `stat ui`, and widget-specific tools. Enable the built-in Slate Insights
plugin and capture with `-trace=slate`. In Slate Frame View, correlate invalidation reasons, update
reasons, layout/prepass, paint, volatility, draw-element growth, and Game/Render thread cost. Repeated
full-tree invalidation or per-frame binding work is usually a structural issue; confirm it in the trace
before adding caches or invalidation panels.

Regression workflow

# Regression workflow

## Baseline and candidate

1. Freeze scenario, device profile, build settings, camera/input script, warm/cold state, and duration.
2. Run multiple baseline samples; retain raw traces and summary metrics.
3. Apply one change.
4. Run the same number of candidate samples in comparable thermal/background conditions.
5. Compare milliseconds, memory, bandwidth, hitch count, and percentile relevant to the budget.
6. Inspect a representative trace when the aggregate moved unexpectedly.

Minimum report:

| Metric | Baseline | Candidate | Delta | Budget | Result |
|---|---:|---:|---:|---:|---|
| median frame ms | | | | | |
| p95/p99 or worst-frame ms | | | | | |
| bound thread/pass ms | | | | | |
| hitch count over threshold | | | | | |
| memory/load/net metric | | | | | |

Do not call a change a win when it shifts cost outside the sampled interval, trades a rare severe hitch
for a better average, changes image quality/gameplay, or exceeds another budget. Keep a safety margin;
meeting 16.67 ms only in an ideal trace is not a robust 60 fps target.

UE 5.8 primary sources

# UE 5.8 primary sources

- [Introduction to Performance Profiling and Configuration](https://dev.epicgames.com/documentation/en-us/unreal-engine/introduction-to-performance-profiling-and-configuration-in-unreal-engine)
- [Unreal Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-insights-in-unreal-engine)
- [Unreal Insights Trace Quick Start](https://dev.epicgames.com/documentation/en-us/unreal-engine/trace-quick-start-guide-in-unreal-engine)
- [Unreal Insights Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-insights-reference-in-unreal-engine-5)
- [Timing Insights Timers and Counters](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-the-timers-and-counters-tabs-in-unreal-insights-for-unreal-engine)
- [Trace Developer Guide](https://dev.epicgames.com/documentation/en-us/unreal-engine/developer-guide-to-tracing-in-unreal-engine)
- [Memory Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/memory-insights-in-unreal-engine)
- [Networking Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/networking-insights-in-unreal-engine)
- [Task Graph Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/task-graph-insights-in-unreal-engine-5)
- [Slate Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/slate-insights-in-unreal-engine)
- [Stat Commands](https://dev.epicgames.com/documentation/en-us/unreal-engine/stat-commands-in-unreal-engine)
- [Graphics Programming Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/graphics-programming-overview-for-unreal-engine)
- [Common Performance Considerations](https://dev.epicgames.com/documentation/en-us/unreal-engine/common-memory-and-cpu-performance-considerations-in-unreal-engine)

Pages were checked against UE 5.8 documentation on 2026-07-19. Reconfirm channel presets,
platform support, trace overhead, command syntax, and export commands after an engine upgrade.

Timing Insights and CPU

# Timing Insights and CPU

## Capture

Launch with a narrow set such as:

```text
-trace=default,cpu,frame,bookmark
```

Or start a file capture at runtime:

```text
Trace.File PerfCase.utrace cpu,frame,bookmark
Trace.Bookmark WarmupComplete
Trace.Bookmark TestBegin
Trace.Bookmark TestEnd
Trace.Stop
```

Without an explicit path, trace files go under `Saved/Profiling`. Check active channels with
`Trace.Status`. Use `Trace.Enable`, `Trace.Disable`, `Trace.Pause`, and `Trace.Resume` to reduce
unwanted data, but do not expect late-enabled channels to reconstruct prior events.

## Analyze

1. Select only the marked test interval.
2. Inspect Game, Render, RHI, worker, and named threads; do not rank timers across unrelated frames.
3. Sort timer aggregation by inclusive time to find large subtrees, then exclusive time to find the
   scope itself. High inclusive/low exclusive cost means the children own the time.
4. Inspect call count. A small scope called thousands of times may need structural batching.
5. Open a slow frame and follow the critical dependency path, waits, task prerequisites, and long
   serial regions.
6. Compare median/typical frames separately from worst hitches.

## Common CPU shapes

- Long Game-thread scope -> gameplay/Blueprint/tick/AI/physics/GC work.
- Render-thread submissions -> primitive count, material sections, visibility, shadow/light setup.
- Worker tasks complete after parent waits -> imbalance, insufficient parallel work, dependency chain.
- Large gaps/waits -> synchronization, IO, locks, frame cap, or starvation; not necessarily "free CPU."
- Thousands of tiny events -> per-object/tick architecture, dispatch overhead, or trace over-detail.

Tool selector

# Tool selector

| Question | Start with | Escalate to |
|---|---|---|
| Which side owns the frame? | `stat unit`, `stat unitgraph` | Timing Insights + GPU events |
| Which CPU scope/thread is slow? | Timing Insights CPU tracks | task/context-switch trace, custom scopes |
| Which GPU pass is slow? | `stat gpu`, `profilegpu` | GPU trace, RenderDoc/platform profiler |
| Why did one frame hitch? | `stat unitgraph`, bookmark | Timing Insights, load/file/GC tracks |
| Why is memory growing? | platform/LLM stats | Memory Insights from process start |
| Which asset loaded or blocked? | async-loading stats | Asset Loading Insights + file/loadtime channels |
| What consumes bandwidth? | `stat net` where applicable | Networking Insights packet/content/stats |
| Are tasks waiting or serialized? | CPU trace | Task Graph + context-switch channels |
| Is UI/Slate expensive? | `stat slate`, `stat ui` | Slate trace/Insights tracks |
| Did a change regress? | repeatable stat/trace capture | exported timer statistics in CI |

Use RenderDoc or a platform graphics debugger for pipeline/resource correctness inside one frame;
use Insights and `profilegpu` to decide which frame/pass deserves that inspection.