Spatial tool reference

The 23 native spatial tools, including programmable worlds and persistent Blender projects.

The canonical ngram_entity integration registers 23 spatial tools. 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 shipped Python schemas. Download the machine-readable definitions.

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, 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
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.

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

ask the user-controlled surface for a current view image.

Parameter	Type	Required	Details
prompt	string	No	See the action behavior above.

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.