Debug Continuous Behavior

Real-time behavior (physics, animations, collisions, game loops) happens too fast for an agent to observe directly. By the time you take a screenshot, the action is over. This skill uses ECS time-control tools to freeze, step, and diff state frame by frame.

User request is in $ARGUMENTS.

Core Workflow

Every debugging session follows this pattern:

1. Set up the scenario (position objects, aim controllers, etc.)
2. ecs_pause — freeze ECS updates right before the interesting moment
3. ecs_snapshot({ "label": "before" }) — capture state before the action
4. Trigger the action (release grip, apply force, start animation, etc.)
5. ecs_step(count, delta) — advance a few frames at fixed timestep
6. browser_screenshot — visually verify what happened
7. ecs_snapshot({ "label": "after" }) — capture state after stepping
8. ecs_diff({ "from": "before", "to": "after" }) — see exactly what changed
9. Repeat steps 5-8, stepping further until the behavior completes
10. ecs_resume — return to normal execution when done

The key insight: pause BEFORE triggering the action, not after. If you pause after, you've already missed the first frames.

Tool Reference

Stepping Guidelines

• delta is in seconds. Common values: 0.016 (60fps), 0.0139 (72fps/Quest refresh rate).
• Start small — step 1-3 frames first to catch the initial moment, then step more.
• Don't overshoot — stepping 100 frames at once defeats the purpose. Step in batches of 5-20.

Patterns

Short domain-specific tips. Apply the core workflow above, plus these hints.

Physics (falling, bouncing, collisions)

• Pause BEFORE releasing the object or applying force.
• Step 1-3 frames at delta: 0.016 to catch initial acceleration.
• In diffs, check PhysicsBody._linearVelocity and PhysicsBody._angularVelocity to see motion direction and speed.
• Check Transform.position to track movement.
• If an object falls through a surface: verify the surface entity has both PhysicsBody (Static) and PhysicsShape (TriMesh for complex geometry).
• Use ecs_query_entity to inspect PhysicsShape and PhysicsBody on both the falling object and the surface.

Grab and Throw

• Pause while the object is still held (trigger/grip engaged).
• Release the input (set button value to 0) while paused.
• Step frame by frame to observe the release velocity.
• In diffs, PhysicsBody._linearVelocity shows the throw direction and speed.
• If the object doesn't move after release: check that it has PhysicsBody with state: Dynamic.

Animations and Transitions

• Step 1 frame at a time with delta matching your target framerate.

…