Run any Skill in Manus with one click

sparkengine-debugging-playbook

Stars23

Forks1

UpdatedJuly 18, 2026 at 15:21

SparkEngine subsystem-specific symptom lookup table: you observed a concrete wrong behavior in a SparkEngine subsystem (AI behavior trees, weapons, the ImGui editor, undo/redo, MMO modules, localization, cinematic sequencer, ECS system ticking, or client-side network prediction) and need to know where to look, what the correct code should look like, and a discriminating experiment to confirm the cause before changing anything. TRIGGER when the user says things like "cloned behavior tree does nothing", "weapon damage is attributed to entity 0", "editor crashes when I open a scene", "editor won't prompt to save", "MMO module uses the wrong NetworkManager", "localized string is garbage", "cutscene has no audio", "my ECS system never ticks / never runs", or "multiplayer is rubber-banding / desyncing". DO NOT TRIGGER for generic C++ crashes, undefined-behavior hunts, or compiler/linker error messages (use the global cpp-crash-triage and msvc-error-decoder skills), nor for a chronological "what changed and why" nar

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

Krilliac

Krilliac/SparkEngine

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

More from this repository

same repository

sparkengine-architecture-contract

Krilliac/SparkEngine

The load-bearing design decisions of the SparkEngine C++23 game engine: the invariants that MUST hold, WHY each exists, what breaks if you violate it, and the OPEN known-weak-points. TRIGGER when you are about to add or wire a subsystem, touch the service locator / EngineContext, change ECS system ordering or the system-manager plumbing, add a global, change RHI backend selection, cross the DLL/game-module boundary, or you catch yourself asking "how is this engine supposed to fit together / where does X live / can I add a g_ global / why is my subsystem null in a module". DO NOT TRIGGER for pure build/CMake/CI failures (use the global cmake-msvc / ci-troubleshoot skills), pure formatting, or a self-contained bug fix that touches no cross-subsystem boundary and adds no new system.

2026-07-1823

sparkengine-job-system-threading

Krilliac/SparkEngine

SparkEngine concurrency and threading-discipline runbook: the real JobSystem / ThreadSafeQueue / StageBasedExecutor / ParallelPerception APIs, the ECS phase barriers, per-subsystem thread-safety rules, and a checklist for parallelizing a new system without data races. TRIGGER when: "parallelize this system", "is it safe to call from a worker thread", "add a job", "JobSystem", "Submit / ParallelFor", "which stage does my system run in", "data race / crash under TSan", "can I touch the ECS from a background thread", "thread-safe queue", "Jolt physics threads". DO NOT TRIGGER for: performance profiling / measuring / optimizing hot paths (use the global perf-hotpath skill), rendering-backend RHI work, or networking protocol logic.

2026-07-1823

sparkengine-asset-pipeline

Krilliac/SparkEngine

Reference for SparkEngine's asset import/load pipeline in SparkEngine/Source/Graphics — how a source file (.obj/.fbx/.gltf/.glb, .png/.tga/.dds, .wav) becomes a runtime MeshAsset/TextureAsset/AudioAsset, what AssetMetadata tracks (guid, checksum, timestamps, fbx.* custom properties), and the non-obvious Windows/Linux platform-split (AssetPipelineWindows.cpp vs AssetPipelineLinux.cpp, D3D11 vs RHI/tinyobj/cgltf/stb_image). TRIGGER when: adding a new asset type or source format, editing AssetPipeline / AssetTypes / AssetMetadata / FBXImporter / ModelLoading, wondering "why is FBX loading Linux-only?", "why are there two .cpp files per asset class?", or "where does mesh loading actually happen?". DO NOT TRIGGER when: writing render-graph / RHI backend code (that is the RHI layer, not the asset layer — read SparkEngine/Source/Graphics/RHI directly), authoring shaders, or doing runtime ECS/gameplay work — use sparkengine-ecs-query-patterns for ECS instead. Phrases: "import an fbx", "add a texture format", "asset m

2026-07-0723

sparkengine-config-and-flags

Krilliac/SparkEngine

Catalog of every SparkEngine CMake build option (ENABLE_*/SPARK_*/BUILD_*), its real verified default, the C/C++ #define it produces, what code it gates, and the CMakePresets it is set by. TRIGGER when the user asks "what does ENABLE_VULKAN / ENABLE_EDITOR / ENABLE_DXR do", "how do I turn off networking / the editor / tests", "which preset builds shipping", "why is my #ifdef SPARK_* not firing", "what flag maps to which define", or "how do I add a new build toggle correctly". DO NOT TRIGGER for MSVC toolchain setup, vcvars, sccache, or build-error triage (use the global cmake-msvc skill instead) — this skill is only the project's feature-flag surface, not how to run the compiler.

2026-07-0723

sparkengine-custom-allocator

Krilliac/SparkEngine

Reference for SparkEngine's four hand-rolled memory allocators — FrameAllocator (per-frame bump), LockFreeRingAllocator (producer/consumer ring), HandleAllocator/VersionedHandle (generational handles), and RHI TransientBufferAllocator (GPU vertex/index suballocation). TRIGGER when you are about to write per-frame or transient allocations, ask "which allocator should I use", need the exact method signatures / thread-safety of one of these, wonder why the code uses naked buffers instead of new/delete, or need to prevent use-after-free on recycled slots/indices. DO NOT TRIGGER for hunting an actual leak or use-after-free bug (use the memory-hunt skill), for general std::unique_ptr ownership questions, or for GPU resource lifetime / ComPtr / RHI backend selection.

2026-07-0723

sparkengine-ecs-query-patterns

Krilliac/SparkEngine

How to query and iterate the EnTT-based ECS in SparkEngine — building views over component combinations, iterating entities inside a system, the CoreComponents vs domain-header layout, the data-driven archetype/prefab spawn format, and the fixed Physics->Animation->AI->Audio->Lifecycle->Render execution order. TRIGGER when the user says "iterate entities with component X", "write a new ECS system", "loop over all entities that have", "GetEntitiesWith", "registry.view", "EnTT view or group", "how do I spawn a prefab/archetype", "what order do systems run in", "why does my system read a stale Transform", or "where do I add a new component struct". DO NOT TRIGGER for how to REGISTER a component with reflection/editor/save (see sparkengine-reflection-conventions), for AngelScript scripting (see sparkengine-hot-reload-seam), or for generic EnTT questions unrelated to this codebase's conventions.

2026-07-0723

name	sparkengine-debugging-playbook
description	SparkEngine subsystem-specific symptom lookup table: you observed a concrete wrong behavior in a SparkEngine subsystem (AI behavior trees, weapons, the ImGui editor, undo/redo, MMO modules, localization, cinematic sequencer, ECS system ticking, or client-side network prediction) and need to know where to look, what the correct code should look like, and a discriminating experiment to confirm the cause before changing anything. TRIGGER when the user says things like "cloned behavior tree does nothing", "weapon damage is attributed to entity 0", "editor crashes when I open a scene", "editor won't prompt to save", "MMO module uses the wrong NetworkManager", "localized string is garbage", "cutscene has no audio", "my ECS system never ticks / never runs", or "multiplayer is rubber-banding / desyncing". DO NOT TRIGGER for generic C++ crashes, undefined-behavior hunts, or compiler/linker error messages (use the global cpp-crash-triage and msvc-error-decoder skills), nor for a chronological "what changed and why" narrative (use the sibling sparkengine-failure-archaeology skill).
trilobite_compatible	true
trilobite_role	debugging

SparkEngine Debugging Playbook

A symptomatic lookup table for SparkEngine subsystems: "You are seeing X. Look at Y. Here is how to confirm it's the cause Z before you touch code." Each entry gives a discriminating experiment — a cheap check that distinguishes the suspected cause from a look-alike, so you don't start editing the wrong file.

Glossary (defined once):

RHI — Render Hardware Interface, SparkEngine's rendering abstraction (D3D11/D3D12/Vulkan/…).
ECS — Entity Component System (EnTT-backed). A system is a per-frame update over entities.
UAF — use-after-free.
DI / injected context — EngineContext handed to a game-module DLL via Initialize(context), as opposed to a process-global singleton.

When to use this skill / when NOT to

Situation	Use
A named SparkEngine subsystem misbehaves in a specific way (table below)	this skill
Generic segfault / heap corruption / UB with no subsystem lead	global `cpp-crash-triage`
A raw MSVC/clang compile or link error message	global `msvc-error-decoder`
"How did we get here / what was the history of this bug"	sibling `sparkengine-failure-archaeology`
The architecture rules a fix must respect (service locator, wiring, thresholds)	`sparkengine-architecture-contract`

Do NOT paste generic C++ advice here. This file only carries SparkEngine-specific symptom→cause maps.

Important: most historical bugs below are already FIXED

This table was built from HARDEN_FLEET_HANDOFF.md's deferred-issue list and then re-verified against the live code on 2026-07-07. Eight of the nine listed issues have since been fixed. The value of the table today is twofold:

If you observe the symptom, the row tells you the fix that should be present so you can spot a regression (someone reverted or broke the fix).
The one partially-fixed issue (Sequencer audio) and the ECS ticking model are live gotchas.

Every file/line reference was checked on 2026-07-07 (branch Working). Line numbers drift — grep the named symbol, do not trust the number blindly.

Triage table

1. Cloned behavior tree does nothing / has no root (AI)

Symptom: An AI agent whose behavior tree was produced by cloning a template just idles; the cloned tree appears empty or its root child is missing.
Where to look: SparkEngine/Source/Engine/AI/BehaviorTreeTypes.h (BTNode::Clone) and SparkEngine/Source/Engine/AI/BehaviorTreeNodes.h (per-node Clone() overrides).
Expected (fixed) state: Clone() is pure virtual (virtual std::unique_ptr<BTNode> Clone() const = 0;). Every node type deep-copies: composites (SequenceNode, SelectorNode, ParallelNode) loop their children calling child->Clone(); decorators (InverterNode, RepeaterNode) clone m_child; leaves (ActionNode, ConditionNode, WaitNode) copy their payload.
Discriminating experiment: Grep the node header for the Clone() bodies:
```
rg -n "std::unique_ptr<BTNode> Clone" SparkEngine/Source/Engine/AI/BehaviorTreeNodes.h
```
If a composite's Clone() returns std::make_unique<SequenceNode>(m_name) without the for (child) cloned->AddChild(child->Clone()) loop, the deep-copy regressed → cloned trees lose their children. If the loop is present, the bug is elsewhere (check the template was populated before cloning, and that AISystem actually calls Clone() for unseen agent types).

2. Weapon damage/kills attributed to entity 0 (Gameplay/FPS)

Symptom: WeaponFireEvent.ownerEntity is always 0; damage/kill attribution, hit markers, or kill feed all credit entity 0.
Where to look: SparkEngine/Source/Engine/Gameplay/WeaponManager.cpp — the call chain Update → ProcessWeapon → HandleFiring → emit WeaponFireEvent.
Expected (fixed) state: the shooter entity id is threaded through the whole chain: ProcessWeapon(uint32_t ownerEntity, …) receives the entity from the ECS view (view.each() → ProcessWeapon(static_cast<uint32_t>(entity), …)), passes it to HandleFiring(uint32_t ownerEntity, …), which sets event.ownerEntity = ownerEntity;.
Discriminating experiment:
```
rg -n "ownerEntity" SparkEngine/Source/Engine/Gameplay/WeaponManager.cpp
```
Confirm event.ownerEntity = ownerEntity; and that ProcessWeapon/HandleFiring take ownerEntity as a parameter (not a hardcoded 0 or a default-constructed local). If the signature still carries the id but the event reads 0, the loss is at the emit site, not the plumbing.

3. Editor crashes / UAF when opening a scene while one is loaded (Editor)

Symptom: The ImGui editor crashes (often a UAF) shortly after File → Open while a scene is already loaded; panels reference freed entities/components of the old world.
Where to look: SparkEditor/Source/Core/EditorUI.cpp — SwapWorld, OpenScene, and the panel-rewire block; CommandHistory (undo stack that may close over old entities).
Expected (fixed) state: EditorUI::SwapWorld(std::unique_ptr<World>) is the single funnel: it (a) clears undo history first — Spark::Editor::CommandHistory::GetInstance().Clear(); — then (b) m_world = std::move(newWorld); then (c) rewires every panel's SetWorld(m_world.get()). OpenScene() and the initial world creation both route through SwapWorld().
Discriminating experiment:
```
rg -n "SwapWorld|OpenScene|CommandHistory::GetInstance\(\)\.Clear" SparkEditor/Source/Core/EditorUI.cpp
```
Confirm OpenScene() calls SwapWorld(...) and does not assign m_world directly. If any code path sets m_world = ... outside SwapWorld (bypassing the history-clear + panel-rewire), that path is the UAF source — a stale CommandHistory command or panel still points at the freed world.

4. Editor won't prompt to save despite real changes (Editor / undo-redo)

Symptom: You make edits, undo back to the saved point, then branch to new edits — and the editor reports "no unsaved changes" (false negative), so you lose work on close.
Where to look: SparkEditor/Source/UndoRedo/UndoRedoManager.h — HasUnsavedChanges, m_editSequence, m_savedSequence.
Expected (fixed) state: dirty tracking is a monotonic counter, not a stack-size compare. m_editSequence increments on every mutating op (execute/merge/undo/redo); MarkSaved snapshots it into m_savedSequence; HasUnsavedChanges() returns m_editSequence != m_savedSequence.
Discriminating experiment:
```
rg -n "m_editSequence|m_savedSequence|HasUnsavedChanges" SparkEditor/Source/UndoRedo/UndoRedoManager.h
```
If HasUnsavedChanges compares stack sizes or indices (e.g. m_currentIndex != m_savedIndex) instead of the monotonic sequences, the false-negative bug regressed: undo-to-saved-then-branch produces an equal size/index while the content differs.

5. MMO game module uses the wrong / stale subsystem instance (MMO / DI)

Symptom: An MMO module (SparkGameMMO) talks to a different NetworkManager (or other subsystem) than the one the host injected — messages vanish, or a second stale singleton appears.
Where to look: GameModules/SparkGameMMO/Source/Player/MMOPlayerSystem.cpp and GameModules/SparkGameMMO/Source/World/MMOWorldSetup.cpp.
Expected (fixed) state: the module stores the injected context (m_context = context; in Initialize) and resolves subsystems through it — e.g. auto* netMgr = m_context ? m_context->GetNetwork() : nullptr; — not through a process-global SomeManager::GetInstance().
Discriminating experiment:
```
rg -n "m_context->Get|::GetInstance\(\)" GameModules/SparkGameMMO/Source
```
SimpleConsole::GetInstance() and SeamlessAreaManager::GetInstance() are legitimate shared singletons — ignore those. The red flag is resolving network / physics / graphics / the engine context itself via GetInstance() instead of m_context->GetX(). If you find that, the DI fix regressed and the module is on a stale instance.

6. Localized string is intermittent garbage or crashes (Localization)

Symptom: Reading a localized string occasionally returns corrupted text or crashes, especially under concurrent access.
Where to look: SparkEngine/Source/Engine/Localization/LocalizationSystem.h / .cpp — GetString, and Format (which calls GetString).
Expected (fixed) state: std::string GetString(const std::string& key) const; returns by value. (Returning const std::string& into an internal map after releasing the lock is the classic dangling-reference bug.)
Discriminating experiment:
```
rg -n "GetString" SparkEngine/Source/Engine/Localization/LocalizationSystem.h
```
If the signature is const std::string& GetString(...) (reference return), the dangling bug is back. Value return is safe. Note Format binds const std::string& tmpl = GetString(key); — that is a const-ref to a temporary (lifetime-extended) and is fine only while GetString returns by value.

7. Cinematic plays visuals but no audio (Sequencer) — PARTIALLY WIRED

Symptom: A Sequence plays animation/property/event tracks correctly, but AudioCue tracks produce no sound.
Where to look: SparkEngine/Source/Engine/Cinematic/Sequencer.h (AudioCallback typedef, SetAudioCallback) and Sequencer.cpp (the per-frame dispatch loop and SetAudioCallback).
Verified current state (2026-07-07): the mechanism exists — using AudioCallback = std::function<void(const AudioCue&)>;, void SetAudioCallback(AudioCallback), and a dispatch loop that fires m_audioCallback(*cue) for each triggered cue only when m_audioCallback is set. BUT: grep finds no caller of SetAudioCallback anywhere in the engine or game modules. So by default the callback is null and cues silently no-op. This is the one issue that is only partially resolved.
Discriminating experiment:
```
rg -n "SetAudioCallback" SparkEngine GameModules SparkEditor
```
If the only hits are the declaration (Sequencer.h) and definition (Sequencer.cpp), then nothing wires audio — the fix is to have the cinematic owner call sequence.SetAudioCallback([audio](const AudioCue& c){ /* play c */ }); at setup. If a caller does exist and audio still fails, check AudioCueTrack::GetTriggeredCues(prevTime, currentTime) and that m_previousTime/m_currentTime actually advance (a zero-length step triggers nothing).

8. A registered ECS system silently never ticks (ECS)

Symptom: You added an ECS system, it compiles, but its Update never runs — entities aren't processed and no error is raised.

Where to look: three names historically collided; here is the verified current model (2026-07-18) — PhaseSystemManager is now the wired canonical manager:

Class	File	Role
`PhaseSystemManager`	`SparkEngine/Source/Engine/ECS/Systems/PhaseSystemManager.h`	Canonical and WIRED (2026-07-18). `GameplayLifecycleShared.cpp` calls `CreatePhaseSystemManager(ctx)` during gameplay init and pumps `UpdateAll(*world, dt)` every frame in `Phase` enum order. Regression test: `Tests/harden/Test_lifecycle_ecs_phase_wiring.cpp`.
`SystemManager`	`SparkEngine/Source/Engine/ECS/Systems/ECSystems.h`	Legacy flat, insertion-order manager. Do not add new systems here.
`StageBasedExecutor`	(deleted 2026-07-18)	Was a live tick over zero registered systems; removed when `PhaseSystemManager` was wired.
`ParallelSystemExecutor`	`ParallelSystemExecutor.h`	A separate access-set batcher, not wired into the live tick; `PhaseSystemManager::UpdateAll` is serial (see its `@note`). See `sparkengine-job-system-threading §1c/§1d`.

The three ways a system silently doesn't tick:
1. Not added to CreatePhaseSystemManager. New systems must be registered in Spark::CreatePhaseSystemManager(ctx) (SparkEngine/Source/Core/EngineSetup.h) with the correct Phase:: bucket — that is the set the gameplay lifecycle creates and ticks. A system registered into the legacy SystemManager or constructed ad hoc will not tick.
2. Registered via the flat overload. AddSystem<T>(Phase::AI, …) is phased; AddSystem<T>(…) (no Phase) drops into the flat list that runs LAST, after all phases. If ordering matters (you read another system's output), the flat overload is the cause.
3. Its subsystem dependency was null at registration. In CreatePhaseSystemManager, physics, audio, and render systems are added only if ctx.GetPhysics()/GetAudio()/GetGraphics() are non-null. In headless / NullRHIDevice runs GetGraphics() may be null → RenderSystem is never registered and never ticks (by design).
Discriminating experiment:
```
rg -n "AddSystem<|UpdateAll" SparkEngine/Source/Core/EngineSetup.h
```
Then confirm your system appears with a Phase:: argument and that the owner of that manager calls UpdateAll every frame. To prove it ticks, put a one-shot log at the top of your Update; if it never prints, it's cause 1 or 3, not a logic bug inside Update.

9. Multiplayer rubber-banding / desync on the client (Networking / prediction)

Symptom: The local player snaps/teleports back after moving (rubber-banding), or client and server positions drift apart.
Where to look: SparkEngine/Source/Engine/Networking/ClientPrediction.h / .cpp — Reconcile(serverState, dt) re-applies un-ACKed inputs after a server correction; GetLastCorrectionMagnitude() reports the size of the last correction. It is wired into GameModules/SparkGameFPS/Source/Game/MultiplayerSystem.cpp and the MMO/TF nets.
Discriminating experiment: Log GetLastCorrectionMagnitude() each time a server state arrives.
- Consistently large corrections → the client's local simulation disagrees with the server's (different movement constants, or inputs not being recorded into the buffer before Reconcile).
- Corrections spike only under packet loss/latency → the input buffer isn't retaining enough un-ACKed inputs to replay, or sequence numbers are mismatched. Check that every predicted input is stamped with a monotonic sequence number and stored before it's sent.
- Magnitude ~0 but still visually snapping → the problem is render interpolation/smoothing, not prediction; look outside ClientPrediction.

How to use an entry (workflow)

Match your symptom to a row.
Run the row's discriminating experiment first — do not edit yet.
If the experiment shows the fix is present and correct, the bug is a look-alike; follow the "if the loop/signature is present…" branch in that row, or fall back to cpp-crash-triage.
If the experiment shows the fix regressed, restore the expected state described in the row. Respect sparkengine-architecture-contract (service locator, wiring rules) when doing so.
Re-verify with the same grep.

Provenance and maintenance

Built from D:\SparkEngine\HARDEN_FLEET_HANDOFF.md (handoff deferred-issue list) and re-verified against the live Working branch on 2026-07-07. Result: rows 1–6 verified FIXED, row 7 (Sequencer audio) verified partially wired (mechanism present, no caller), rows 8–9 describe the current ECS/prediction model. Note the ECS-manager reality (row 8): StageBasedExecutor exists (ParallelSystemExecutor.h:378) and its ExecuteAll(dt) is ticked every frame from GameplayLifecycleShared.cpp:1062, but has no RegisterSystem caller (dead tick); PhaseSystemManager is defined-not-wired (zero callers). None of the three managers is a cleanly-wired home — an OPEN architectural weak point (see sparkengine-architecture-contract Invariant 3 and sparkengine-job-system-threading §1c).

Line numbers are advisory; grep the named symbols. One-line re-verification commands:

# Row 1  BT deep-copy present
rg -n "std::unique_ptr<BTNode> Clone" SparkEngine/Source/Engine/AI/BehaviorTreeNodes.h
# Row 2  weapon owner threaded
rg -n "ownerEntity" SparkEngine/Source/Engine/Gameplay/WeaponManager.cpp
# Row 3  editor world-swap funnel
rg -n "SwapWorld|OpenScene" SparkEditor/Source/Core/EditorUI.cpp
# Row 4  monotonic dirty tracking
rg -n "m_editSequence|m_savedSequence" SparkEditor/Source/UndoRedo/UndoRedoManager.h
# Row 5  MMO resolves via injected context
rg -n "m_context->Get|::GetInstance\(\)" GameModules/SparkGameMMO/Source/Player/MMOPlayerSystem.cpp
# Row 6  localization returns by value
rg -n "GetString" SparkEngine/Source/Engine/Localization/LocalizationSystem.h
# Row 7  is SetAudioCallback ever called? (only decl+def == not wired)
rg -n "SetAudioCallback" SparkEngine GameModules SparkEditor
# Row 8  ECS managers: intended-but-unwired vs the live-but-empty tick
rg -n "AddSystem<|UpdateAll|CreatePhaseSystemManager" SparkEngine/Source/Core/EngineSetup.h
rg -n "StageBasedExecutor::GetInstance\(\).ExecuteAll" SparkEngine/Source/Core/Lifecycle/GameplayLifecycleShared.cpp
rg -rn "RegisterSystem\(" SparkEngine/Source | rg -i stage   # expect only the definition (dead tick)
# Row 9  prediction reconcile + correction magnitude
rg -n "Reconcile|GetLastCorrectionMagnitude" SparkEngine/Source/Engine/Networking/ClientPrediction.h

When you fix a genuinely new subsystem symptom, add a row here (symptom → where → expected state → discriminating experiment) and record durable lessons in the project wiki per CLAUDE.md.
Validate edits to this file by running the global skill-linter (~/.claude/skills/skill-linter/) against this folder: pass -Path .claude/skills/sparkengine-debugging-playbook.