Inspecting and testing

Skill ferret-debugging · download all skills · SKILL.md

When to use#

Finding out what a running game holds, driving it from a tool or an agent, writing tests that need no renderer.

The model#

CommandChannel (world.commands) is a list of named commands with a description: list() says what is there, execute(name, args) runs one; each package registers its own when its service starts, so the list is what the running game has loaded. The inspector, the model viewer, the editor and agents all use it, and the tests call the same names.

Steps#

1. world.commands.list() first; the description of each command is the authority.
2. World: world.info, world.pause, world.step, world.timeScale. Scene: scene.entities, scene.node, scene.bounds, scene.stats, scene.validate, camera.get|set.
3. installInspector adds the entity tree and component values.
4. Physics: physics.info, physics.bodies, body.state (see ferret-physics-host).
5. Tests: build a world with the test helpers, drive it with world.step() / world.run(s); visual behaviour gets a Playwright screenshot (pnpm test:e2e).

Check afterwards#

The command you rely on appears in list() for this game; a headless test reproduces the problem in fixed steps.

What usually goes wrong#

• Command not found: its package or capability was not registered or enabled in this game.
• Testing against a number seen once instead of a law the code implements.
• Tests sharing state: make a world per test and dispose it.

Files#

• reference/world.md — World, the fixed step, entities and components, services, the event bus and registries.
• reference/commands.md — The debug command channel: how a tool, the inspector or an AI agent drives a running game, and the commands each package registers.
• reference/api-inspector.md — every export of @ferret/inspector with signature and doc comment
• reference/api-core.md — every export of @ferret/core with signature and doc comment
• reference/commands.md — 33 commands of these packages with their arguments