---
name: ferret-debugging
description: Use to look inside a running Ferret game and to test it: world.commands (list, execute), the inspector (entity tree, component values, stats), scene and camera commands, asset and package commands, headless worlds in unit tests and the Playwright runs.
---

# Inspecting and testing

## 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