sparkengine-ecs-lifecycle-threading-and-memory

Documents SparkEngine ECS phase wiring, threading rules, physics stepping, and memory ownership contracts.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? SparkEngine's runtime core has strict, easy-to-violate rules: one live ECS tick path, one physics stepper per process, main-thread-only registry access, and deferred mutation during entity iteration. This Skill gives an AI assistant the verified ground truth so it can add ECS systems, parallelize work, or debug lifecycle bugs without causing double-ticks, data races, or silent fault-isolated failures. ## Core Features & Use Cases - ECS phase wiring guidance: Explains the PhaseSystemManager phase order, the single production registration site in EngineSetup.h, and the CI-enforced harden tests that prove a system actually ticks. - Threading and synchronization rules: Provides the thread-affinity table for the EnTT registry, PhysicsSystem, JobSystem, and allocators, plus the gather-on-main/process-on-workers pattern. - Lifecycle and memory contracts: Covers DeferredQueue iteration safety, physics stepping ownership, world-origin rebasing hazards, and EngineRuntime ownership doctrine. - Use Case: When asked to add a new ECS system or diagnose why a system stopped ticking, the assistant follows the decision rules and failure-mode checklist instead of guessing from stale docs. ## Quick Start Ask the assistant to add a new ECS system to SparkEngine and have it follow this runbook to register it in the correct phase and prove it ticks with a harden test.

Frequently Asked Questions about sparkengine-ecs-lifecycle-threading-and-memory

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

FAQPage Schema
How do I add a new ECS system in SparkEngine?

Implement Spark::ECS::ISystem with Update and GetName, then register it in EngineSetup.h::CreatePhaseSystemManager in the correct phase. That is the only production registration site. Add a harden test driving InitializeEcsPhaseSystemsImpl to prove the system actually ticks.

Why is my SparkEngine ECS system not ticking?

Common causes are registering outside CreatePhaseSystemManager, using the unwired CreateGameSystems factory, or the fault isolator auto-disabling a repeatedly throwing system. Check SPARK_GUARDED_UPDATE fault logs and grep EngineSetup.h for your system's registration.

Is the EnTT registry thread-safe in SparkEngine?

No, the EnTT registry and World wrapper are main-thread only. Gather snapshots on the main thread, process them on JobSystem workers, then write results back on the main thread, following the ParallelPerception pattern.

Who steps the physics simulation in SparkEngine?

Physics stepping is module-driven; exactly one owner per process calls Update(deltaTime) or StepFixed, never both. The PhysicsUpdateSystem ECS phase only syncs bodies and transforms and never advances the simulation.

How do I safely destroy entities during EnTT view iteration?

Never destroy entities or mutate components you are iterating inside the view loop. Use Spark::DeferredQueue to mark entities during iteration and Flush after the loop; DeferredQueue itself is not thread-safe.

When should I not use this ECS runbook skill?

Route module DLL injection, ABI, and hot-reload questions to the modules skill, CMake and CI questions to the build skill, incident history to failure-archaeology, and live crash diagnosis to the debugging playbook.