> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ngram.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Spatial tool reference

> The 28 native spatial tools, including Figments, 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](/assets/spatial-tools.json).

## Figments

The [Figment guide](/spatial/figments) covers authoring, named behavior, grips and portable publishing. [Physics](/spatial/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.

<Note>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](/spatial/capabilities).</Note>

## 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](/spatial/creations) and [Programs](/spatial/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](/spatial/blender) for installation, persistence, cancellation, and export limits.

## Movement and expression

<AccordionGroup>
  <Accordion title="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`.                                                   |
  </Accordion>

  <Accordion title="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`. |
  </Accordion>

  <Accordion title="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.                                                                                                    |
  </Accordion>

  <Accordion title="ar_look_at">
    queue gaze toward the user or away.

    | Parameter | Type     | Required | Details                              |
    | --------- | -------- | -------- | ------------------------------------ |
    | `target`  | `string` | Yes      | Gaze target. Values: `away`, `user`. |
  </Accordion>

  <Accordion title="ar_go_idle">
    return to a relaxed idle stance.

    No parameters.
  </Accordion>

  <Accordion title="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). |
  </Accordion>
</AccordionGroup>

## Panels and media

<AccordionGroup>
  <Accordion title="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`. |
  </Accordion>

  <Accordion title="ar_hide_panel">
    close a spatial panel by id.

    | Parameter  | Type     | Required | Details                        |
    | ---------- | -------- | -------- | ------------------------------ |
    | `panel_id` | `string` | Yes      | See the action behavior above. |
  </Accordion>

  <Accordion title="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. |
  </Accordion>

  <Accordion title="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.                                                                                      |
  </Accordion>

  <Accordion title="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.                               |
  </Accordion>
</AccordionGroup>

## Objects and environment

<AccordionGroup>
  <Accordion title="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.                                                                                     |
  </Accordion>

  <Accordion title="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.                                                                                                 |
  </Accordion>

  <Accordion title="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.                        |
  </Accordion>

  <Accordion title="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. |
  </Accordion>

  <Accordion title="ar_clear_objects">
    clear all spawned scene objects when the user asks to reset or clean the space.

    No parameters.
  </Accordion>

  <Accordion title="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. |
  </Accordion>

  <Accordion title="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`. |
  </Accordion>
</AccordionGroup>

## Inspection and optional backends

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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. |
  </Accordion>

  <Accordion title="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.                            |
  </Accordion>
</AccordionGroup>

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