---
name: ferret-level-editor
description: Use when an agent builds or changes a Ferret level by commands: edit.open, edit.entity.*, edit.spawn.*, edit.zone.*, edit.anim.*, edit.physics.*, edit.patch (JSON pointer), undo/redo, edit.validate, edit.diff and edit.save, with the model viewer for screenshots.
---

# Editing a level by commands

## When to use
Putting entities in a level, adding zones, spawns, animation graphs, physics settings, or fixing a manifest without hand-editing JSON.

## The model
`@ferret/editor` edits a **draft** of a level's manifest through commands on `world.commands`. Every edit is a JSON-pointer patch (`add`, `replace`, `remove`) with its undo; a person in the editor and an agent share one undo history. Nothing is written until `edit.save`, which is refused while the draft is invalid.

## Steps
1. `edit.open {level}` (draft; `live` reloads the level after each edit).
2. Read with `edit.get {path?}` (a JSON pointer such as `/entities/0/params`).
3. Change with the typed commands: `edit.entity.add|set|remove|duplicate`, `edit.spawn.*`, `edit.zone.*`, `edit.collider.set`, `edit.navmesh.rebuild`, `edit.anim.*`, `edit.physics.*` (material, constraint, fracture, set). Use `edit.patch {ops}` only when no typed command fits.
4. `edit.validate`, then `edit.diff` to see exactly what changed.
5. Look: the model viewer (`pnpm viewer`, `pnpm viewer:headless`) relays commands and serves screenshots of the active camera.
6. `edit.save`. `edit.undo` / `edit.redo` / `edit.history` while working.

## Check afterwards
`edit.validate` is empty; `edit.colliders.missing` lists no large non-solid mesh you meant to be solid; a screenshot shows the level; the level plays.

## What usually goes wrong
- Node names that do not exist in the glTF (the loader cannot wire them: `edit.validate` reports it).
- Removing a state or graph still used.
- Forgetting `edit.navmesh.rebuild` after moving solid meshes.
- Editing with `live` off and not calling `edit.reload`.

## Files

- `reference/levels.md` — The level manifest, the level registry and travel, environment, and the .ferret package format.
- `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-editor.md` — every export of `@ferret/editor` with signature and doc comment
- `reference/commands.md` — 76 commands of these packages with their arguments