Scenario Unreal Gameplay

Unreal Gameplay (framework, Blueprint vs C++, input, GAS, AI, UI)

Expert level means every piece of data lives in the class whose lifetime and network presence match it, logic is text (C++ or small functions) under data-only Blueprints and data assets that Python configures, and every mechanic is proven in isolation (injected input, debug commands, traces) before it is judged in play. The agent does not pretend to author graphs it cannot reach: it states which surface each piece lands on and escalates only the residue. If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add scenario-labs/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

REQUIRED BACKGROUND: scenario-unreal-expert (channels, review loop, 5.8 traps).

Status (2026-09-24): Unreal is not installed. The offline layer passed (python3 tests/code/unreal-gameplay/run_all.py --offline). Every in-editor snippet and generated C++ file is not yet run in Unreal (C++ not yet compiled); job_00_gameplay_probe.py answers the [verify] names.

Stance (the expert delta)

• Place data by lifetime and network presence. GameMode is server-only rules; GameState and PlayerState replicate to all; PlayerController is owner-only; the Pawn is a respawnable body; GameInstance subsystems outlive maps (Forsythe IaU2Hue-ApI [00:13:26]). State goes in replicated properties with RepNotify, never multicast; C++ RepNotify does not fire on the server (JOJP0CvpB8w [00:10:50], [00:14:48]). Under World Partition BeginPlay can run several times: keep it idempotent (Shao KBn62trwkLw [00:07:29]).
• C++ base, data-only Blueprint child; Blueprint may depend on C++, never the reverse (Forsythe VMZftEVDuCE [00:24:10]). Tuning is EditDefaultsOnly, asset choices TSubclassOf slots, cosmetics BlueprintImplementableEvent hooks: logic as diffable text, Blueprints as defaults Python sets. Broadcasters fire one-way delegates (OnDied) that controllers, spawners and HUD bind ([00:19:25]).
• Blueprint cost is per node; the real cost is hard references. Tick overhead is noise next to a CharacterMovement update; casting to a Blueprint class keeps it loaded with the caster (Arnbjörnsson S2olUc9zcB8 [00:06:07], [00:28:01]). Move to C++ only what an Insights trace puts in the hot set (Forsythe [00:16:33]).
• Effects are what, abilities are when. New features are new reactive assets listening through tags; reactions query a GE's asset tags; one damage GE with SetByCaller; Wait Delay, not Delay; always End Ability; PlayMontageAndWait; Gameplay Cues cosmetic only (Shao 8bi0rnXnRj4 [00:19:25], [00:47:35], [00:21:43], [00:49:12], [00:13:02]; tranek 9.3). A SetByCaller value exists only when code sets it, so console isolation tests use a fixed-magnitude twin [added].
• Wire the ASC on both sides. On the pawn unless attributes survive respawn (then PlayerState); InitAbilityActorInfo on the server in PossessedBy and on the owning client in the PlayerController's AcknowledgePossession (or OnRep_PlayerState); Mixed for players, Minimal for AI, set early; never predict damage (tranek 4.1, 4.1.2, 7.3, 4.10).
• Input is data with indirection. Input Action to input tag to ability, so the pawn holds no ability logic (Noland, Lyra Fj1zCsYydD8 [00:34:33]); mapping contexts mutually exclusive per gameplay state (framework doc).
• StateTree selects a leaf before any transition and re-checks enter conditions only when a transition asks (Mononen YEmq4kcblj4 [00:11:22]). Every condition that should end a state needs an event or a transition; every state gets explicit success and failure ways out, or it falls back to the root ([00:14:13]); data by binding, tuning as tree parameters ([00:16:40]); actions delegate to a Gameplay Ability with a timeout (Bruno XKQfMZOXFv0 [00:17:37], [00:19:15]).
• UI updates by events, never property bindings; turn Global Invalidation on, then hunt frozen widgets (Albert VxX1aah6TZM [00:24:09]). Widget Tick runs from Paint, a text change is a layout invalidation, Hidden only repaints where Collapsed relayouts ([00:10:09], [00:13:56], [00:12:53]).

Establish first

Authoring surfaces

Scriptable: C++ classes, Blueprint children and their CDO defaults, data assets and tables, Enhanced Input assets, Gameplay Effect shells, StateTree assets and parameters, widget trees (EditorUtilityLibrary.add_source_widget). Graph content (event graphs, GE modifiers Python cannot instance, StateTree states and transitions, Behavior Tree nodes) goes through a template duplicated per variant, Epic's MCP toolsets, 5.8 BlueprintGraphEditor after help(), or one precise GUI pass. Full table: procedures P15.

Workflow

1. Probe once per engine. job_00_gameplay_probe.py (headless) lists the classes, properties and cvars the skill marks [verify], including the AbilitySystem.Fix... asset-tag cvar, plus a dumpticks sample. GATE: probe.json written.
2. Decide. ue_gameplay.decide(spec): data placement, Blueprint vs C++, GAS or not, AI system, ASC placement, init and replication, communication, UI, each with its deciding condition. GATE: every datum has owner, replication and survival (respawn, map change, streaming).
3. Scaffold project and config. ue_env.enable_plugins; ini_set for bUseDebugTargetFromHud, the asset-tag cvar at 0, tags; a GameMode HUD class for showdebug. GATE: config_verdict clean.
4. C++ layer. cpp_scaffold() (character base, player controller, dash and melee abilities, AI controller, StateTree tasks, health widget, native tags), patch_build_cs(), build_command(), editor closed for new reflected members. GATE: build exit 0; cpp_lint without errors (it includes ASC_CLIENT_INIT_MISSING).
5. Data layer from Python. Blueprint children and CDO defaults: movement, JumpMaxCount = 2, player_controller_class on the GameMode, and on every AI pawn ai_controller_class = the controller Blueprint that holds the tree plus auto_possess_ai placed or spawned. Input assets from input_plan(), GE assets from plans checked by ge_plan_verdict, StateTree asset, widget tree. GATE: ge_plan_verdict and audit_gameplay() clean.
6. Graph residue. Write each tree as a spec, check it with statetree_spec_verdict, wire it from statetree_outline through an MCP toolset or one GUI pass (references/gui-paths.md), set tree parameters per enemy. GATE: spec verdict clean; the tree compiles with no unbound Inputs; ai_setup_verdict clean.
7. Test in isolation, then the chain. Fixed-magnitude debug GE from the console, showdebug abilitysystem (3 pages), the gameplay debugger on each AI, log LogAbilitySystem VeryVerbose read by gas_log_triage; then pie_scenario or a PythonAutomationTest with Input.+key injection, judged by analyzers whose thresholds derive from the parameters (analyze_jump, dash_expected_cm, analyze_cooldown, state_sequence_verdict, health_bar_verdict). GATE: every scenario passes, no stuck ability, no unplanned root entry.
8. Evidence and review. Screenshots of the debug pages, showdebug enhancedinput, health bar before and after damage, enemy per state, navmesh coverage; ue_review.image_checks before looking. GATE: no blank frame; UI in sync.
9. Measure. Development build or new-window PIE: stat game, stat unit, dumpticks (tick_verdict), stat slate with Global Invalidation off and on, and an Insights trace of the scenario before any rewrite (rewrite_gate). GATE: tick census justified; rewrites only for hot-set functions; trace handed to scenario-unreal-performance.