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.

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

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.

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

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.

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.

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.

Chronological case-file of SparkEngine's hardest, already-solved bugs — each with symptom, root cause, the exact fix commit, and current landed/open status. TRIGGER when you are about to re-investigate something that "feels like it was fixed before", when you say "has this ICF / type-id / C++23 gate / blue-screen / macOS build / camera race / AngelScript hot-reload thing happened before", when a Windows Release-only CI failure reappears, when you want the STORY and commit hash of a past incident, or when auditing which harden-fleet items are still deferred. DO NOT TRIGGER for a brand-new live symptom you just hit and want a fix recipe for — use the sibling sparkengine-debugging-playbook (symptom->fix triage) instead; this skill is a history book, not a first-responder.

Reference for how SparkEngine's AngelScript hot-reload and client/server script context separation actually work, and a checklist for exposing a new scripted type/function so it survives a reload. TRIGGER when the user says "script hot-reload", "reload the .as script", "why didn't my AngelScript change take effect", "[server]/[client] script tag", "SetScriptContext", "AttachScript returns false", "script state got wiped on reload", or "I added a new function/type callable from AngelScript". DO NOT TRIGGER for C++ game module hot-reload (that is the `ModuleHotReload` C++ class, a different code path, not this skill), shader hot-reload (the `ShaderHotReload` C++ class), or AngelScript sandbox/security questions (see the sandbox code directly) — those are separate seams.

Decision-gated campaign to finish and verify the SparkEngine "module EngineContext injection" P0 — the cross-DLL fix that makes EngineContext::Get() inside a game-module DLL resolve to the host engine's live context instead of a dead per-image copy. TRIGGER when: someone says the module DI / EngineContext injection P0 is "landed but inert", when module-side service-locator lookups (NetworkManager, GetNetwork) return null or a wrong singleton inside a GameModules DLL, when a HARDEN_FLEET / trilobite handoff lists "SparkModuleInjectEngineContext export still needed", or when a rebuilt module DLL must be proven to export the injection hook. DO NOT TRIGGER for general "how do I add a new module DLL" questions (use sparkengine-plugin-abi), for the ImGui or console injection hooks specifically (those already shipped), or for non-Windows builds (this whole seam is #if defined(_WIN32) only).

SparkEngine game-module DLL plugin ABI reference — how ModuleManager discovers and loads GameModules/*.dll, the extern "C" injection hooks a module must export (SparkModuleInjectEngineContext / Console / ImGui), and the exact checklist for adding a new game module DLL. TRIGGER when the user says "add a new game module", "my module's EngineContext::Get() returns null", "module console commands don't work", "module ImGui draws nothing / crashes", "CreateModule not found", "how does ModuleManager load DLLs", "why is my module's NetworkManager a dead singleton", or asks how the plugin/module ABI works. DO NOT TRIGGER for finishing the specific EngineContext-injection P0 step-by-step (use sparkengine-module-injection-p0-campaign), for engine-internal subsystem wiring unrelated to DLLs, or for AngelScript hot-reload (that is scripting, not the native module ABI).

How to register a new reflected ECS component type in SparkEngine's hand-rolled, no-RTTI reflection system (Core/Reflection.h + Core/ComponentReflection.cpp). TRIGGER when the user says "add a reflected field", "expose this component to the editor inspector", "why isn't my component showing up in the Inspector", "add SPARK_REFLECT", "make this field replicated/serialized", "register a new component type", "TypeRegistry", "ComponentFactory", or "reflection macro". DO NOT TRIGGER for AngelScript scripting reflection (see sparkengine-hot-reload-seam), for scene-file save/load mechanics beyond the reflected-field bridge (see sparkengine-serialization-format), or for generic C++ RTTI/dynamic_cast questions unrelated to this system.

Runbook for launching and operating the built SparkEngine binaries — the engine (SparkEngine.exe), the ImGui editor (SparkEditor.exe), the standalone SparkConsole subprocess, and the 10 game-module DLLs — plus where logs, crash dumps, saves and screenshots land. TRIGGER when: "how do I run/launch/start the engine or editor", "which executable do I run", "what are the command-line flags", "run headless / dedicated server", "load a specific game module with -game", "the console subprocess isn't receiving my commands", "where do crash dumps / SparkCrash .dmp / logs / save files go", "how does the SparkConsole IPC pipe work". DO NOT TRIGGER when: you need to compile/configure/build (use global cmake-msvc / ci-troubleshoot), diagnose a compiler or CMake error, write engine C++ code, or debug rendering/physics internals — this skill is about operating already-built binaries, not producing them.

The SparkEngine save-game and world-persistence formats — the SaveSystem `.spark_save` binary layout (magic, versioning, per-component string properties) and the AsyncDatabase persistence layer (async future/callback/sync API, shared-connection threading, file-backed key-value fallback). TRIGGER when the user says "add a field to the save file", "why isn't my component saved", "save/load format", "spark_save", "SaveSystem", "quicksave/autosave", "AsyncDatabasePool", "async query", "ProcessCallbacks", "prepared statement", "MMO persistence", "save version / migration", or "database won't persist". DO NOT TRIGGER for scene/entity file serialization or the reflection macros (see sparkengine-reflection-conventions), for AngelScript hot-reload state (see sparkengine-hot-reload-seam), or for network replication wire format.

Architecture and internals of SparkShaderCompiler, SparkEngine's in-house offline shader-compilation CLI tool (SparkShaderCompiler/src/main.cpp). Covers what input languages it accepts (HLSL and GLSL, SPIR-V passthrough), its CLI flags, the RHI CompileShader pipeline stages, output artifacts (.cso / .spv / .glsl) and where they land, filename-based stage inference, and how to add a new backend/stage or extend the tool. TRIGGER when the user asks "how does the shader compiler tool work", "how do I run SparkShaderCompiler", "what flags does the shader compiler take", "how do I batch-compile shaders", "where do compiled shaders go", "how do I add a new shader stage/backend to the compiler", or "why is my .cso just HLSL text". DO NOT TRIGGER for runtime shader debugging (why a shader renders wrong, pixel/HLSL debugging) — use the global shader-debug skill instead.