scene

30 public commands in this category.

• clear_selection

  Deselect all entities

  Scope: scene:read. Token cost: 0.

• create_checkpoint

  Save a named recovery checkpoint of the whole project (a restorable snapshot of every scene)

  Scope: scene:write. Token cost: 0.

  label string (optional)

  Optional label for the checkpoint; defaults to a timestamp

• create_joint

  Create a physics joint between two entities. Requires physics enabled on both. Joint types: fixed, revolute, spherical, prismatic, rope, spring. Applied in both the editor and exported (runtime) games (#9550).

  Scope: scene:write. Token cost: 0.

  connectedEntityId string (required)

  Entity ID of the other body to connect to

  entityId string (required)

  Entity ID to attach the joint to

  anchorOther array (optional)

  Local anchor point on the connected entity [x, y, z]

  anchorSelf array (optional)

  Local anchor point on this entity [x, y, z]

  axis array (optional)

  Joint axis for revolute/prismatic [x, y, z]

  jointType string (optional)

  Type of joint constraint

  limits object (optional)

  Optional joint limits

  motor object (optional)

  Optional motor settings

• create_scene

  Create a new empty scene in the project

  Scope: scene:write. Token cost: 0.

  name string (required)

  Name for the new scene

• delete_checkpoint

  Delete a saved recovery checkpoint by ID (missing IDs are a no-op)

  Scope: scene:write. Token cost: 0.

  checkpointId string (required)

  ID of the checkpoint to delete

• delete_entities

  Delete one or more entities by their IDs

  Scope: scene:write. Token cost: 0.

  entityIds array (required)

  Array of entity IDs to delete

• delete_scene

  Delete a scene from the project

  Scope: scene:write. Token cost: 0.

  sceneId string (required)

  Scene ID or name to delete

• despawn_entity

  Remove an entity from the scene by ID

  Scope: scene:write. Token cost: 0.

  entityId string (required)

  Entity ID to remove

• duplicate_entity

  Duplicate an entity (creates a copy with offset position)

  Scope: scene:write. Token cost: 0.

  entityId string (required)

  Entity ID to duplicate

• duplicate_scene

  Create a copy of an existing scene

  Scope: scene:write. Token cost: 0.

  sceneId string (required)

  Scene ID or name to duplicate

  name string (optional)

  Name for the duplicate

• export_scene

  Export the current scene as a JSON string (.forge format). Triggers a SCENE_EXPORTED event with the full scene data.

  Scope: scene:read. Token cost: 0.

• list_scenes

  List all scenes in the project with metadata

  Scope: scene:read. Token cost: 0.

• load_scene

  Load a scene from a JSON string (.forge format). Replaces the entire current scene.

  Scope: scene:write. Token cost: 0.

  json string (required)

  Complete scene JSON in .forge format

• load_scene_with_transition

  Load a different scene with a visual transition effect. Can be used during play mode for level changes.

  Scope: scene:write. Token cost: 0.

  sceneName string (required)

  Name of the scene to load

  color string (optional)

  Transition color (hex)

  direction string (optional)

  Wipe direction: left, right, up, down

  duration number (optional)

  Transition duration in milliseconds

  transitionType string (optional)

  Transition type: fade, wipe, instant

• new_scene

  Clear the current scene and start fresh with default settings

  Scope: scene:write. Token cost: 0.

• remove_joint

  Remove a physics joint from an entity. Applied in both the editor and exported (runtime) games (#9550).

  Scope: scene:write. Token cost: 0.

  entityId string (required)

  Entity ID to remove joint from

• rename_entity

  Change the display name of an entity

  Scope: scene:write. Token cost: 0.

  entityId string (required)

  name string (required)

  New display name

• rename_scene

  Rename a scene

  Scope: scene:write. Token cost: 0.

  name string (required)

  New name for the scene

  sceneId string (required)

  Scene ID or name

• reparent_entity

  Move an entity to a new parent in the hierarchy

  Scope: scene:write. Token cost: 0.

  entityId string (required)

  Entity to move

  index integer (optional)

  Position among siblings (optional)

  newParentId string (optional)

  New parent entity ID (null for root)

• restore_checkpoint

  Restore a recovery checkpoint by ID, replacing the active project with its snapshot

  Scope: scene:write. Token cost: 0.

  checkpointId string (required)

  ID of the checkpoint to restore

• select_entities

  Select multiple entities at once

  Scope: scene:read. Token cost: 0.

  entityIds array (required)

  mode string (optional)

  Selection mode (default: replace)

• select_entity

  Select an entity in the viewport

  Scope: scene:read. Token cost: 0.

  entityId string (required)

  mode string (optional)

  Selection mode (default: replace)

• set_completion_mode

  Set how the open scene's game counts as complete. "win" (what a scene with no mode plays as) lets Play start only when at least one win condition the player can complete exists; "endless", "sandbox" and "narrative" let a game with no win condition play and pass verification. A win condition the scene does have is still validated in every mode. Saved with the scene file and undoable from Scene Settings. Set it when the creator asks for a sandbox, endless or story game; never infer it from entity names.

  Scope: scene:write. Token cost: 0.

  mode string (required)

  win: requires a completable win condition. endless: score or survival, no final win. sandbox: a toy with no goal. narrative: ends through authored story progression.

• set_default_transition

  Set the default transition configuration used when switching scenes

  Scope: scene:write. Token cost: 0.

  color string (optional)

  Transition color (hex)

  direction string (optional)

  Wipe direction: left, right, up, down

  duration number (optional)

  Duration in milliseconds

  easing string (optional)

  Easing: linear, ease-in, ease-out, ease-in-out

  transitionType string (optional)

  Transition type: fade, wipe, instant

• set_start_scene

  Set which scene loads first when the game starts

  Scope: scene:write. Token cost: 0.

  sceneId string (required)

  Scene ID or name to set as start

• set_visibility

  Show or hide an entity

  Scope: scene:write. Token cost: 0.

  entityId string (required)

  visible boolean (required)

• spawn_entity

  Create a new entity in the scene (mesh primitive or light)

  Scope: scene:write. Token cost: 0.

  entityType string (required)

  Type of entity to spawn

  id string (optional)

  Caller-supplied entity id, letting the caller address the entity immediately instead of waiting for the async selection event. Trimmed, then honored only if 1-64 BYTES with no control characters - an id that fails those checks is NOT an error: the engine silently falls back to a random UUID. Auto-generated if omitted.

  name string (optional)

  Display name (auto-generated if omitted)

  position array (optional)

  World position [x, y, z]

• switch_scene

  Switch to a different scene by name or ID

  Scope: scene:write. Token cost: 0.

  sceneId string (required)

  Scene ID or name to switch to

• update_joint

  Update joint properties on an entity. Applied in both the editor and exported (runtime) games (#9550).

  Scope: scene:write. Token cost: 0.

  entityId string (required)

  Entity ID with the joint

  anchorOther array (optional)

  Update other anchor [x, y, z]

  anchorSelf array (optional)

  Update self anchor [x, y, z]

  axis array (optional)

  Update joint axis [x, y, z]

  connectedEntityId string (optional)

  Change connected entity

  jointType string (optional)

  Change joint type

  limits objectnull (optional)

  Set or remove limits (null to remove)

  motor objectnull (optional)

  Set or remove motor (null to remove)

• update_transform

  Set the position, rotation, and/or scale of an entity

  Scope: scene:write. Token cost: 0.

  entityId string (required)

  position array (optional)

  [x, y, z]

  rotation array (optional)

  [rx, ry, rz] in degrees

  scale array (optional)

  [sx, sy, sz]