sparkengine-debugging-playbook

Diagnoses SparkEngine subsystem failures using symptom-to-cause lookup tables and discriminating experiments.

31|3|Updated Jul 26, 2025
One-click install
npx skills add https://github.com/Krilliac/SparkEngine --skill sparkengine-debugging-playbook-krilliac
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: sparkengine-debugging-playbook
Source: https://github.com/Krilliac/SparkEngine/tree/main/.claude/skills/sparkengine-debugging-playbook
Command: npx skills add https://github.com/Krilliac/SparkEngine --skill sparkengine-debugging-playbook-krilliac

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When a SparkEngine subsystem misbehaves (AI behavior trees, weapons, the ImGui editor, undo/redo, MMO modules, localization, cinematic audio, ECS ticking, or network prediction), developers waste time editing the wrong file. This Skill maps each concrete symptom to the exact source location, the expected correct code, and a cheap discriminating experiment to confirm the cause before changing anything. ## Core Features & Use Cases - Symptom-to-cause triage table: Nine verified entries covering cloned behavior trees, weapon damage attribution, editor world-swap UAF crashes, undo/redo dirty tracking, MMO dependency injection, localization dangling references, sequencer audio wiring, ECS phase ticking, and client-side prediction rubber-banding. - First-response toolkit: Log macros (SPARK_LOG_*), debug hooks, fault isolation (SPARK_GUARDED_UPDATE), crash dumps via crash_mode, and test selectors (SPARK_TEST_FILE/SPARK_TEST_NAME) for gathering signal before guessing. - Regression detection: Each row documents the fix that should be present, so you can spot when a historical bug has regressed versus a look-alike failure. - Use Case: Your ECS system compiles but never ticks. The Skill directs you to check CreatePhaseSystemManager registration, the flat-vs-phased AddSystem overload, null subsystem dependencies, and fault isolation status via fault.status in SparkConsole. ## Quick Start Describe the wrong behavior you observed in a running SparkEngine subsystem, such as "my ECS system never ticks" or "weapon damage is attributed to entity 0", and ask where to look and how to confirm the cause.

Frequently Asked Questions about sparkengine-debugging-playbook

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug an ECS system that never ticks in SparkEngine?

Check whether the system is registered in CreatePhaseSystemManager with a Phase argument, since the flat AddSystem overload runs last and ad hoc registration never ticks. Also verify subsystem dependencies were non-null at registration and run fault.status in SparkConsole to rule out fault isolation disabling the ECS_Phases tick.

Why does my cloned behavior tree do nothing in SparkEngine AI?

A cloned behavior tree idles when a composite node's Clone() override omits the loop that deep-copies children. Grep for std::unique_ptr<BTNode> Clone in BehaviorTreeNodes.h and confirm each composite calls child->Clone() for every child.

How do I confirm the cause before editing SparkEngine code?

Each symptom row provides a discriminating experiment, usually a single ripgrep command against a named symbol, that distinguishes the suspected cause from look-alikes. Run the experiment first; only edit if it shows the expected fix has regressed.

When should I not use this debugging playbook?

Do not use it for CI job or build configuration failures, chronological bug-history investigation, raw compiler or linker error decoding, or generic C++ crash forensics with no subsystem lead. Those route to sibling skills or crash tooling instead.

How do I get more debug output from the SparkEngine runtime?

Use SPARK_LOG_* macros with log categories, register callbacks via DebugHookManager at frame or system update points, enable crash_mode on in SparkConsole for dumps, and filter tests with SPARK_TEST_FILE and SPARK_TEST_NAME environment variables.

Why is multiplayer rubber-banding happening on the client?

Rubber-banding comes from ClientPrediction reconciliation applying server corrections. Log GetLastCorrectionMagnitude: consistently large values mean simulation mismatch, spikes under packet loss mean insufficient buffered inputs, and near-zero values point to render interpolation instead.