Spatial tool reference

The canonical ngram_entity integration registers the tools below. A connected Spatial session can receive actions from another conversation with the same Entity. A messaging conversation does not create a Spatial session by itself. Blender authoring can run on the execution host before a surface connects. This reference follows the current Python schemas on main, including updates after v1.0.1. Download the machine-readable definitions. Read the running registry when connecting to an older installation.

Figments

The Figment guide covers authoring, named behavior, grips and portable publishing. Physics describes bodies, collision shapes, sensors and constraints.

Tool	Commands	Payload
`ar_figment`	`capabilities`, `inspect`, `attach`, `configure`, `detach`	`id`, `definition`, optional `preset`, `physics`, `start`; inspect supports `includeSource`
`ar_figment_physics`	`physics`	`id`, `physics`
`ar_figment_behavior`	`behavior`	`id`, `source`, optional `hz`, `start`; or `id`, `action` (`pause`, `resume`, `reset`)
`ar_figment_interact`	`properties`, `action`	`id`, `values`; or `id`, `action`, optional `data`
`ar_figment_library`	`library`, `publish`, `export`, `import`, `place`	`id` for publish; `packageId` for export/place; `url` or `package` for import; optional `place`, `position`

Each tool takes command and an optional payload object. Publishing stores a local immutable version. Export downloads a self-contained file; it does not upload to a public service or return binary content through the model. Place returns a new paused instance.

A tool can queue an action before the surface renders it. Optional capture, media, or motion features still depend on the connected browser and configured backend. See capabilities.

Creations and Blender

ar_world

Create, inspect, edit, and program a persistent creation world. The result comes from the connected surface. Call capabilities for the detailed world and JavaScript contracts.

Parameter	Type	Required	Details
`command`	`string`	Yes	One of the commands below
`payload`	`object`	No	Command-specific data

Commands	Payload and purpose
`capabilities`	Current operations, schemas, program API, features, and limits
`observe`	Optional `ids`, `tag`, `offset`, `limit`, and `includeGeometry`; returns live objects and program/asset status
`apply`	`{requestId, baseRevision?, operations}`; validates and commits a batch
`events`	`{after}`; reads events after a sequence cursor without starting inference
`program`	`{command, id?, program?, params?, includeSource?}`; install, inspect, pause, resume, remove, or update parameters
`assets`	`{command, id?}`; `inspect`, `retry`, or `cancel` an asset load
`pause`, `resume`	Pause or resume physics and local programs
`save`, `export`, `import`	Save with optional `name`, export a world document, or import that document as the payload
`load`, `fork`	Select or create a named local world using `id`; `fork` also accepts `name`
`undo`, `redo`	Pause creations and apply scene history
`workshop`, `garden`	Create a built-in example at optional `origin: [x,y,z]`
`perform`	`{action: "look" or "approach", target: entityId}`; direct the avatar toward an existing creation

Approach returns an accepted task; use the correlated perform.completed or perform.cancelled event to establish its outcome. Observe important results once rather than repeatedly polling with model calls. See Creations and Programs for complete examples and human interaction controls.

ar_blender

Author a persistent headless Blender project on the configured execution host and publish GLB previews into Spatial.

Parameter	Type	Required	Details
`command`	`string`	Yes	`capabilities`, `create`, `execute`, `publish`, `render`, `status`, `stop`, or `show`
`payload`	`object`	No	Project and command-specific data

Command	Payload and purpose
`capabilities`	Inspect executable discovery and execution workspace
`create`	`{name, project_id?, blend_file?}`; create a project, optionally from a workspace `.blend` file
`execute`	`{project_id, source, executable?, timeout?, request_id?, position?}`; run Python with `bpy` and `publish()`, then publish automatically
`publish`	`{project_id, executable?, timeout?, request_id?, position?}`; publish the current project without another edit
`render`	`{project_id, executable?, timeout?, request_id?, options?}`; return a rendered image without publishing another revision; see Vision for options
`status`	`{project_id}` for one project; omit the ID to list projects
`stop`	`{project_id}`; terminate the process while retaining published checkpoints
`show`	`{project_id, position?}`; attach a saved project’s preview to the connected surface

position is an initial Spatial placement in metres. Subsequent revisions preserve human transforms. execute can call publish() several times during one script; progress delivery does not require further model calls. Read Blender for installation, persistence, cancellation, and export limits.

Skies and scene lighting

ar_environment

Configure the surrounding sky and the renderer’s actual lighting. The environment guide covers procedural atmospheres, Blender panoramas, imported HDR/EXR, and human controls.

Command	Payload and result
`capabilities`	Exact sky, lighting, fog, exposure, and ground contract
`inspect`	Applied configuration, revision, loading status, errors, and effective scene state
`configure`	`{sky?, lighting?, fog?, exposure?, ground?}`; apply after resources load successfully
`clear`	Cancel a pending load and restore the base preset

Like ar_world, the tool takes command and optional payload. Omitted blocks stay unchanged; a supplied block replaces its previous value; null resets it. A failed panorama load leaves the working environment intact. The tool waits for a renderer result; avoid repeated model polling. ar_blender render with options.projection: "equirectangular" returns an image and a skybox object ready to use as the configure payload. Sky rendering needs no continuous Blender process once the artifact exists. Keep foreground geometry and interactions in GLB assets and Figments. XR keeps passthrough unless sky.immersive is explicitly enabled. Scene capture still excludes physical passthrough imagery.

Movement and expression

ar_move_to

Request movement in the connected scene. An accepted action is not proof of completed movement; inspect its outcome when needed.

Parameter	Type	Required	Details
`target`	`string`	Yes	Where to move in the scene. Values: `away`, `forward`, `left`, `random`, `right`, `user`.
`speed`	`string`	No	Movement speed. Values: `fast`, `walk`.

ar_gesture

queue a physical gesture (wave, nod, point, dance, …).

Parameter	Type	Required	Details
`gesture`	`string`	Yes	Physical gesture to perform. Values: `breakdancing`, `celebrate`, `cheering`, `clapping`, `coding`, `dance`, `drunkWalk`, `enteringCode`, `explain`, `greet`, `handRaising`, `hipHop`, `macarena`, `no`, `nod`, `point`, `shrug`, `terrified`, `texting`, `thinking`, `twerking`, `twistDance`, `wave`.

ar_emote

queue a bodily emotional expression.

Parameter	Type	Required	Details
`emotion`	`string`	Yes	Emotion to express bodily. Values: `attentive`, `calm`, `concerned`, `curious`, `excited`, `happy`, `thoughtful`.
`intensity`	`number`	No	0–1 intensity.

ar_look_at

queue gaze toward the user or away.

Parameter	Type	Required	Details
`target`	`string`	Yes	Gaze target. Values: `away`, `user`.

ar_go_idle

return to a relaxed idle stance.No parameters.

ar_speak

speak mid-turn (visible + TTS) before your final reply. Use for reactions while reasoning; final answer can still go in normal reply text.

Parameter	Type	Required	Details
`text`	`string`	Yes	Words to speak in the AR surface (mid-turn).

Panels and media

ar_show_panel

show a readable spatial panel for substantial information.

Parameter	Type	Required	Details
`panel_id`	`string`	Yes	Stable panel identifier.
`content`	`string`	Yes	Panel body.
`title`	`string`	No	Optional title.
`panel_type`	`string`	No	Values: `card`, `chart`, `code`, `html`, `image`, `markdown`.

ar_hide_panel

close a spatial panel by id.

Parameter	Type	Required	Details
`panel_id`	`string`	Yes	See the action behavior above.

ar_terminal

write a concise status or result to the spatial terminal.

Parameter	Type	Required	Details
`output`	`string`	Yes	Short visible terminal text.
`tool`	`string`	No	See the action behavior above.
`error`	`boolean`	No	See the action behavior above.
`clear`	`boolean`	No	See the action behavior above.

ar_open_browser

open an HTTP(S) page on the spatial browser surface.

Parameter	Type	Required	Details
`url`	`string`	Yes	HTTP(S) webpage to open. Do not use this for YouTube playback; use ar_play_youtube with a specific video instead.
`title`	`string`	No	See the action behavior above.

ar_play_youtube

play a specific YouTube video in the dedicated media player. On desktop this opens the desktop player; in immersive AR the surface uses its headset-safe playback flow. Search for a specific video first when needed.

Parameter	Type	Required	Details
`video`	`string`	Yes	A specific YouTube video ID or watch URL.
`title`	`string`	No	Song or video title.
`volume`	`number`	No	Minimum: 0. Maximum: 100.
`start_at`	`number`	No	Minimum: 0.

Objects and environment

ar_spawn_object

spawn a real 3D geometric primitive. Use for requests naming a shape such as cube, sphere, cylinder, cone, torus, or plane. Physics defaults on. Do not use ar_spawn_text as a substitute for geometry.

Parameter	Type	Required	Details
`object_id`	`string`	Yes	Stable unique id for later removal.
`shape`	`string`	Yes	The actual 3D primitive to create. Use sphere for a geometric ball. Values: `cone`, `cube`, `cylinder`, `plane`, `sphere`, `torus`.
`position`	`string`	No	Values: `above`, `front`, `here`, `left`, `right`.
`color`	`string`	No	See the action behavior above.
`size`	`number`	No	Minimum: 0.03. Maximum: 2.0.
`label`	`string`	No	Optional caption; not a substitute for the shape.
`physics`	`boolean`	No	Enable gravity and collision. Defaults to true.

ar_spawn_toy

spawn an interactive physics toy. Use this for balls, bouncy balls, beach balls, dice, and marbles; use ar_spawn_object for generic geometry.

Parameter	Type	Required	Details
`object_id`	`string`	Yes	Stable unique id for later removal.
`toy_type`	`string`	Yes	Ready-made physics toy. For requests to spawn a ball, use ball or bouncy_ball. Values: `ball`, `beach_ball`, `bouncy_ball`, `dice`, `marble`.
`position`	`string`	No	Values: `above`, `front`, `here`, `left`, `right`.
`color`	`string`	No	See the action behavior above.
`impulse`	`object`	No	Optional initial velocity for tossing the toy.

ar_spawn_text

place visible lettering in the scene. Use only when the user asks for text or a label; never use it to represent a requested physical object or shape.

Parameter	Type	Required	Details
`object_id`	`string`	Yes	See the action behavior above.
`text`	`string`	Yes	See the action behavior above.
`position`	`string`	No	Values: `above`, `front`, `here`, `left`, `right`.
`color`	`string`	No	See the action behavior above.
`size`	`number`	No	Minimum: 0.2. Maximum: 4.0.

ar_remove_object

remove one previously spawned object, toy, text, image, or model by id.

Parameter	Type	Required	Details
`object_id`	`string`	Yes	See the action behavior above.

ar_clear_objects

clear all spawned scene objects when the user asks to reset or clean the space.No parameters.

ar_draw_annotation

place a labeled callout at scene coordinates.

Parameter	Type	Required	Details
`drawing_id`	`string`	Yes	See the action behavior above.
`text`	`string`	Yes	See the action behavior above.
`x`	`number`	Yes	See the action behavior above.
`y`	`number`	Yes	See the action behavior above.
`z`	`number`	Yes	See the action behavior above.
`color`	`string`	No	See the action behavior above.

ar_set_environment

change the shell’s environment preset.

Parameter	Type	Required	Details
`preset`	`string`	Yes	Values: `cozy`, `default`, `focus`, `nature`, `night`, `party`, `space`, `workshop`.

Inspection and optional backends

ar_inspect_surface

inspect the current embodied surface contract, live context, and available spatial API tools. Use this instead of scanning workspace files when asked what the spatial body can do.No parameters.

ar_request_capture

Receive actual virtual-scene images in the current tool round. The human controls permission through the camera button. A separate inspection camera preserves their viewpoint.

Parameter	Type	Required	Details
`prompt`	`string`	No	Purpose of the inspection.
`options`	`object`	No	Target, named angles, camera pose, size, isolation, diagnostic style, mesh node, and collider overlay. See Vision.

ar_generate_motion

request a novel humanoid motion from the configured external GPU provider. Use only when generated motion adds clear value.

Parameter	Type	Required	Details
`prompt`	`string`	Yes	Physical motion to generate.
`duration_seconds`	`number`	No	Minimum: 0.5. Maximum: 30.0.
`root_target`	`string`	No	Values: `forward`, `left`, `right`, `stationary`, `user`.
`loop`	`boolean`	No	See the action behavior above.

Design for the current surface

Use primitives for geometry and text tools for lettering. Use ar_spawn_toy for prepared physics objects, and ar_play_youtube for a specific video rather than opening a YouTube search page in the browser panel. ar_terminal displays text; it does not execute a shell command. ar_request_capture requests a rendered surface frame; it does not establish access to passthrough cameras. ar_generate_motion needs a configured external motion provider.

Getting started

Build

Reference

Spatial tool reference

Figments

Creations and Blender

ar_world

ar_blender

Skies and scene lighting

ar_environment

Movement and expression

Panels and media

Objects and environment

Inspection and optional backends

Design for the current surface

​Figments

​Creations and Blender

​ar_world

​ar_blender

​Skies and scene lighting

​ar_environment

​Movement and expression

​Panels and media

​Objects and environment

​Inspection and optional backends

​Design for the current surface

Figments

Creations and Blender

ar_world

ar_blender

Skies and scene lighting

ar_environment

Movement and expression

Panels and media

Objects and environment

Inspection and optional backends

Design for the current surface