Agents and automation

Feather 2 is built so that an AI agent or a script can do anything a person can do in the editor. Every authoring feature is a command in one shared catalog, with a strict JSON schema. The editor’s own panels run the same commands, so an edit made by an agent is validated, undoable and visible in the editor exactly like an edit made by hand.

The engine does not bundle a language model or provider credentials. You connect your own AI client through the Model Context Protocol, or call commands directly with feather-cli.

How a command flows

Step	What happens
1. Request	A person (editor panel or Cmd/Ctrl+K), the CLI or an MCP client sends a command name and JSON arguments
2. Validation	Arguments are checked against the command’s schema; unknown fields and out-of-range values are rejected
3. Transaction	The change is applied to a copy of the project, and the whole project is validated, including references between assets, objects and scripts
4. Commit	On success the change becomes one undo step and the revision number advances. On failure nothing changes
5. Feedback	The response reports the result. Agents can then read state, run a simulation, read runtime logs or capture the viewport

The catalog currently holds 270 commands; see the command reference.

Live and headless sessions

Session	Started with	Works on	Use it for
Headless	feather-cli --workspace DIR [--project FILE]	A document in memory, with no window or renderer	Batch authoring, CI checks, building projects from scripts
Live	feather-cli --connect SESSIONFILE	The running editor’s open project	Working alongside a person, Play, viewport capture

Headless sessions support all authoring commands, renderer-free play-testing with game.simulate and game builds with game.export. Commands that need a real window — runtime.*, viewport.*, editor.* and job.inspect — work only in a live session. A live session connects over an authenticated local connection described by a session file; see MCP setup.

Response envelope

Every command returns the same JSON envelope:

{
  "ok": true,
  "revision": 12,
  "data": { "object": { "id": 4, "name": "My cube" } },
  "error": null
}

On failure, ok is false, data is null and error holds a stable code and a message that says what to change.

Error code	Meaning
invalid_arguments	Arguments do not match the command’s schema
not_found	A referenced object, asset or item does not exist
validation	The change would leave the project invalid
revision_conflict	The document changed since the revision you passed
playing	Authoring is locked while the live editor is in Play
unknown_command	No command with that name exists
requires_live_editor	The command needs a running editor; connect with --connect

Revisions

Every edit, selection change, undo and redo advances the document’s revision. Pass the revision you last read to make an edit conditional:

• CLI: --expected-revision N
• MCP: an expected_revision field in the tool’s arguments

If anything changed in between, the command fails with revision_conflict and changes nothing. Read the current state again before retrying. This lets an agent and a person work on the same project without overwriting each other.

Undo

Each successful command is one undo step, including multi-step operations such as scene.batch (up to 64 commands applied atomically). Agents undo and redo with history.undo and history.redo; in the editor, the same history is on Edit → Undo and Cmd/Ctrl+Z.

Pending editor edits

A person may have unapplied edits in the editor, such as an unsaved script buffer or a Blueprint that has not been applied. engine.status reports them. Before making a conflicting change, call editor.commit to validate and apply them, or editor.discard to drop them explicitly.

Editor layout

In a live session, an agent can arrange the editor for the task at hand. editor.workspace.get lists the workspaces (level, terrain, art, logic, gameplay, story, ship) with their panels, and reports the current workspace and the panels open and in front. editor.workspace.set switches to one; reset: true restores its default arrangement. Neither changes the project or its revision, and switching is refused during Play.

feather-cli --connect .feather-session.json command editor.workspace.set --json '{"id":"ship"}'

Checking results

To check	Use
Project data	project.inspect, scene.get, and each domain’s .get command
Gameplay and physics	game.simulate returns a report without a renderer; see Simulation
Runtime messages	runtime.logs in a live session
Visuals	viewport.capture, then viewport.image; see MCP setup
Performance	runtime.stats; see Profiler

Automate it

# Discover every command and its schema.
feather-cli catalog

# Inspect a live editor before editing.
feather-cli --connect .feather-session.json command engine.status

Next: Command-line control and MCP setup.