AI scene manipulation

Updated: Apr 17, 2026

The Meta Spatial Editor includes mse-agent, a built-in command-line tool that AI agents can invoke to create and manipulate 3D scenes programmatically using natural language — no separate installation required. Run mse-agent readme for the full command reference.

mse-agent location

Platform	Path
Mac	`/Applications/Meta Spatial Editor.app/Contents/MacOS/mse-agent`
Windows	`C:\Program Files\Meta Spatial Editor\V*\Resources\mse-agent` (use the latest version folder)
Linux	`<package-root>/mse-agent` (located at the root of the downloaded package)

Before you start

1. Verify installation

Check that Meta Spatial Editor is installed by verifying the mse-agent path exists for your platform (see table above).

If Meta Spatial Editor is not installed, download it from:

Mac

Windows

Linux (headless CLI only)

2. Launch the editor

Launch Meta Spatial Editor with your project scene. Run the commands below from the project root directory.

Note: The editor is a long-running GUI process. You must launch it in the background so it does not block your current process. On Mac, open already returns immediately. On Windows, use start to spawn a separate process. On Linux, the Meta Spatial Editor runs in headless mode. Always wait a few seconds after launching before running mse-agent ping to confirm the editor is ready.

Mac:

open -a "/Applications/Meta Spatial Editor.app" "app/scenes/Main.metaspatial"

Windows:

cmd /c start /B "" "C:\Program Files\Meta Spatial Editor\V*\MetaSpatialEditor.exe" "app/scenes/Main.metaspatial"

Linux:

<package-root>/MetaSpatialEditorCLI serve -p app/scenes/Main.metaspatial &>/dev/null &

3. Verify connection

mse-agent ping

4. Get command reference

mse-agent readme

When to use mse-agent

Use Meta Spatial Editor (mse-agent) when entities are static and primarily define scene composition or layout. Scenes are visible in Spatial Editor, which makes review and iteration faster than runtime-only entity creation.

Use Kotlin runtime entity creation when entities must be created dynamically. Spatial Editor scenes are static — if entity creation depends on runtime data, variable counts, or entities that appear and disappear based on state, runtime code is the better fit since you cannot know what to author ahead of time.

Use a hybrid approach when a scene has both static and dynamic aspects. Authoring the static entities in Spatial Editor keeps them visible for inspection and lets designers iterate on composition independently, while keeping runtime-driven content in Kotlin lets engineers focus on behavior and logic in code.