FERRETGame engine over Babylon.js
Ferret

Editing a level by commands

Skill ferret-level-editor · download all skills · SKILL.md

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