Skip to content

Debug C++ ECS State: Trace Writers and Execution Order

An invisible body stops moving. Reproduce the input, calculate its expected state, and identify the missing writer instead of blaming a whole architecture.

Smallest Reproduction

Use A with visible=false: x=0, vx=1, ax=2, dt=0.5. Correct state is vx=2, x=1, and empty render output.

broken_visibility_update in deferred.hpp deliberately places motion inside a visibility condition. It is a faulty specimen, not the worlds' real update path.

Run the Investigation

1
2
/tmp/pi-design-main/design_demo debug
/tmp/pi-design-main/design_tests debug

1
2
3
4
intentional broken specimen: x=0 expected=1 FAIL
id=1 acceleration x=0 vx=2
id=1 movement x=1 vx=2
correct x=1 rendered=0

FAIL labels the deliberate specimen. The demo exits successfully after explaining it; the regression test must pass.

Interpret Each Observation

Observation Interpretation Next check
Broken x stays 0 Motion did not execute Capability condition
Acceleration trace writes vx=2 Velocity writer ran Movement's input
Movement trace writes x=1 Position writer followed acceleration Final snapshot
Render count is 0 Visibility filter worked Do not make the body visible to “fix” motion

Trace entries copy number, stage, position, and velocity; they are not storage pointers. A combined multi-world log would also need a world label.

Compare Investigation Paths

For records, read advance and its conditions. For composition, follow optional Motion. For inheritance, check the selected subclass, override, and base sequencing.

For ECS, inspect matching criteria and ordered passes. A capability-wide fault can be convenient to isolate; one entity's story requires assembling multiple events.

Architecture changes the path, not the need for a reproducible input and independent expected result.

Keep the Regression Focused

The debug group reproduces the faulty x=0, requires the actual record world to reach x=1, verifies trace writers, and requires empty rendering.

Changing visibility to make motion pass would hide the faulty coupling and violate chapter 1.

Exercise

If x=0.5 but vx=2, which writer probably ran in the wrong order? Why does that signature suggest a different fault from x=0?

Next: turn investigation results into maintenance rules.

Previous: Chapter 7 · Course overview · Next: Chapter 9

Donate