Scene tools

Orient yourself, query and save scenes, and batch many edits into one undo step.

11 tools in the scene category. Badges: read-only tools never change the project; mutating tools are undoable and attributed; open-world tools reach outside the engine and MCP clients ask before running them.

Tool	Summary
engine_info	Version, renderer, play state, component types and tool categories.
scene_overview	Compact outline of the whole scene: every entity as one line (id, name, mesh/color, position, tags) in hierarchy order, plus environment, selection and the scene file (path; empty until saved).
scene_query	Find entities by name glob (e.g.
batch	Run many tool calls atomically as ONE undo step.
scene_save	Save the scene as JSON (.sky.json).
scene_load	Load a scene file (replaces the current scene and clears history).
scene_new	Start a new scene.
scene_flow_info	The running game's scene flow: the current scene (alias or path), the pending change (target, preloaded assets, loading scene), loading progress, the transition (kind, phase out|loading|in|idle, alpha), loaded sub-scenes with their entity counts, the carried entities (carried: carry components, game.json sceneFlow.carry), game.json scene aliases and every scene file.
scene_change	Moves the running game to another scene, as Wander's change_scene does: the scene is a game.json "scenes" alias or a .sky.json path (unknown names get a did-you-mean).
scene_additive_load	Adds a scene's entities to the running game (a room, a streaming chunk, a UI overlay) with fresh entity ids and returns its handle.
scene_additive_unload	Removes a sub-scene loaded with scene_additive_load or Wander's load_additive: exactly the entities it created.

engine_info

Engine info read-only

Version, renderer, play state, component types and tool categories. Call once at the start of a session. shaders reports how the shader library was loaded (library "metallib" precompiled or "source" compiled at startup), shaderCompileMs, renderer startupMs and the pipeline cache (hits/misses, archive path).

Takes no arguments.

Tool callCLIMCP request

engine_info {}

skywalker call engine_info '{}' --project my_game

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "engine_info",
    "arguments": {}
  }
}

scene_overview

Scene overview read-only

Compact outline of the whole scene: every entity as one line (id, name, mesh/color, position, tags) in hierarchy order, plus environment, selection and the scene file (path; empty until saved). Start here before editing.

Argument	Type	Required	Description	Values
max_entities	integer		Limit lines (default 300)

Tool callCLIMCP request

scene_overview {"max_entities": 200}

skywalker call scene_overview '{"max_entities": 200}' --project my_game

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "scene_overview",
    "arguments": {
      "max_entities": 200
    }
  }
}

scene_query

Find entities read-only

Find entities by name glob (e.g. "tree*"), tag, component, or proximity. Returns one line per match.

Argument	Type	Required	Description	Values
name	string		Name glob, case-insensitive (* and ?)
tag	string		Required tag
component	string		Required component (transform, mesh, light, camera, behaviors)
near	number[3]		Only entities within radius of this point
radius	number		Radius for near (default 5)
limit	integer		Max results (default 50)

Tool callCLIMCP request

scene_query {"name": "tree*", "near": [0, 0, 0], "radius": 25, "limit": 20}

skywalker call scene_query '{"name": "tree*", "near": [0, 0, 0], "radius": 25, "limit": 20}' --project my_game

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "scene_query",
    "arguments": {
      "name": "tree*",
      "near": [
        0,
        0,
        0
      ],
      "radius": 25,
      "limit": 20
    }
  }
}

batch

Batch operations mutating

Run many tool calls atomically as ONE undo step. If any operation fails, everything is rolled back and the failing index is reported. Use for building scenes efficiently.

Argument	Type	Required	Description	Values
operations	object[]	yes	Operations in order
operations[].tool	string	yes	Tool name
operations[].args	object		Tool arguments
label	string		History label, e.g. "Build village"

Tool callCLIMCP request

batch {"label": "Camp", "operations": [{"tool": "entity_create", "args": {"name": "Tent", "mesh": "cone", "color": "#c8a165", "position": [0, 1, 0], "scale": [2, 2, 2]}}, {"tool": "entity_create", "args": {"name": "Fire", "components": {"light": {"kind": "point", "intensity": 6, "color": "#ff9a4a", "range": 14}, "transform": {"position": [3, 0.6, 1]}}}}]}

skywalker call batch '{"label": "Camp", "operations": [{"tool": "entity_create", "args": {"name": "Tent", "mesh": "cone", "color": "#c8a165", "position": [0, 1, 0], "scale": [2, 2, 2]}}, {"tool": "entity_create", "args": {"name": "Fire", "components": {"light": {"kind": "point", "intensity": 6, "color": "#ff9a4a", "range": 14}, "transform": {"position": [3, 0.6, 1]}}}}]}' --project my_game

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "batch",
    "arguments": {
      "label": "Camp",
      "operations": [
        {
          "tool": "entity_create",
          "args": {
            "name": "Tent",
            "mesh": "cone",
            "color": "#c8a165",
            "position": [
              0,
              1,
              0
            ],
            "scale": [
              2,
              2,
              2
            ]
          }
        },
        {
          "tool": "entity_create",
          "args": {
            "name": "Fire",
            "components": {
              "light": {
                "kind": "point",
                "intensity": 6,
                "color": "#ff9a4a",
                "range": 14
              },
              "transform": {
                "position": [
                  3,
                  0.6,
                  1
                ]
              }
            }
          }
        }
      ]
    }
  }
}

scene_save

Save scene mutating

Save the scene as JSON (.sky.json). Path is relative to the project.

Argument	Type	Required	Description	Values
path	string		e.g. scenes/level1.sky.json (default: current file)

Tool callCLIMCP request

scene_save {"path": "scenes/main.sky.json"}

skywalker call scene_save '{"path": "scenes/main.sky.json"}' --project my_game

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "scene_save",
    "arguments": {
      "path": "scenes/main.sky.json"
    }
  }
}

scene_load

Load scene mutating destructive

Load a scene file (replaces the current scene and clears history).

Argument	Type	Required	Description	Values
path	string	yes	Scene path

Tool callCLIMCP request

scene_load {"path": "scenes/main.sky.json"}

skywalker call scene_load '{"path": "scenes/main.sky.json"}' --project my_game

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "scene_load",
    "arguments": {
      "path": "scenes/main.sky.json"
    }
  }
}

scene_new

New scene mutating destructive

Start a new scene. By default it contains a ground plane, a cube and a camera; empty=true for nothing.

Argument	Type	Required	Description	Values
name	string		Scene name
empty	boolean		Start completely empty

Tool callCLIMCP request

scene_new {"empty": true}

skywalker call scene_new '{"empty": true}' --project my_game

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "scene_new",
    "arguments": {
      "empty": true
    }
  }
}

scene_flow_info

Scene flow state read-only

The running game's scene flow: the current scene (alias or path), the pending change (target, preloaded assets, loading scene), loading progress, the transition (kind, phase out|loading|in|idle, alpha), loaded sub-scenes with their entity counts, the carried entities (carried: carry components, game.json sceneFlow.carry), game.json scene aliases and every scene file. Use it before and after scene_change / scene_additive_load, and to explain why something did not carry over.

Takes no arguments.

Tool callCLIMCP request

scene_flow_info {}

skywalker call scene_flow_info '{}' --project my_game

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "scene_flow_info",
    "arguments": {}
  }
}

scene_change

Change scene (play) mutating

Moves the running game to another scene, as Wander's change_scene does: the scene is a game.json "scenes" alias or a .sky.json path (unknown names get a did-you-mean). Entities with a carry component, game.json sceneFlow.carry names and keep carry over with their behaviors running; the rest is replaced. The change runs over the next ticks (transition out, preloading, swap, transition in); step the simulation to see it, or pass immediate: true to swap now. Stopping play returns the editor to the scene play started in. Example: {"scene": "level2", "transition": "fade", "duration": 0.4, "spawn_at": "Door_West"}.

Argument	Type	Required	Description	Values
scene	string	yes	Alias or .sky.json path
transition	any		"none" | "fade" | "crossfade", or
duration	number		Transition seconds (0..10)
color	string		Fade color, e.g. "#000000"
keep	string[]		More entities to carry over this time
spawn_at	string		Entity of the new scene the player moves to (carry.spawn, else tag "player")
loading	string		Loading scene shown while the target preloads ("" = none; default game.json sceneFlow.loadingScene)
immediate	boolean		Swap now, without transition or preloading (default false)

Tool callCLIMCP request

scene_change {"scene": "level2", "transition": "fade", "duration": 0.4, "spawn_at": "Door_West"}

skywalker call scene_change '{"scene": "level2", "transition": "fade", "duration": 0.4, "spawn_at": "Door_West"}' --project my_game

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "scene_change",
    "arguments": {
      "scene": "level2",
      "transition": "fade",
      "duration": 0.4,
      "spawn_at": "Door_West"
    }
  }
}

scene_additive_load

Load a sub-scene (play) mutating

Adds a scene's entities to the running game (a room, a streaming chunk, a UI overlay) with fresh entity ids and returns its handle. The sub-scene owns exactly the entities it created, so scene_additive_unload removes those and nothing else. Options: id (handle; default the alias or file name), parent (entity to load under), offset (added to its root positions). Loads now (between ticks); on scene_loaded runs next tick. Example: {"scene": "rooms/cellar", "offset": [40, 0, 0]}.

Argument	Type	Required	Description	Values
scene	string	yes	Alias or .sky.json path
id	string		Handle for unloading (default: alias or file name, made unique)
parent	integer | string		Entity to load under (default: the root)
offset	number[3]		Added to the sub-scene's root positions

Tool callCLIMCP request

scene_additive_load {"scene": "rooms/cellar", "offset": [40, 0, 0]}

skywalker call scene_additive_load '{"scene": "rooms/cellar", "offset": [40, 0, 0]}' --project my_game

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "scene_additive_load",
    "arguments": {
      "scene": "rooms/cellar",
      "offset": [
        40,
        0,
        0
      ]
    }
  }
}

scene_additive_unload

Unload a sub-scene (play) mutating

Removes a sub-scene loaded with scene_additive_load or Wander's load_additive: exactly the entities it created. Entities the game added under them at run time are kept and moved to the root (listed as orphans). Removes now (between ticks). Example: {"handle": "cellar"}.

Argument	Type	Required	Description	Values
handle	string	yes	Sub-scene handle (scene_flow_info lists them)

Tool callCLIMCP request

scene_additive_unload {"handle": "cellar"}

skywalker call scene_additive_unload '{"handle": "cellar"}' --project my_game

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "scene_additive_unload",
    "arguments": {
      "handle": "cellar"
    }
  }
}