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

# Build things you can touch

> Create persistent objects, simulations, and controls that people can move and use.

An agent can build a sculpture, a working mechanism, or a small interactive world. You can pick it up, change its scale, and operate its controls while the agent continues working.

Use **Objects** in the top bar to inspect creations. This drawer and the agent's `ar_world` tool edit the same scene.

## Choose how to build

| Route                         | Use it for                                                                                                         |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `ar_world`                    | Shapes, custom meshes, groups, materials, lights, physics bodies, joints, and controls                             |
| [Blender](/spatial/blender)   | Original meshes and authored materials, built on the agent's execution computer and published into Spatial         |
| [Programs](/spatial/programs) | Local JavaScript that animates creations and responds to human interaction                                         |
| [Figments](/spatial/figments) | Portable interactive objects with named parts, grips, exposed properties, adjustable physics and editable behavior |

The older `ar_spawn_object` and `ar_spawn_toy` tools remain available. Their legacy objects are separate from the editable creation world; use the IDs and APIs reported by the appropriate tool.

## Try a working example

Open **Objects → Examples** and select **Kinetic workshop** or **Resonance garden**. The same examples are available to the agent:

```json theme={"theme":"github-light-default"}
{
  "name": "ar_world",
  "arguments": {
    "command": "workshop",
    "payload": { "origin": [0, 0, -2] }
  }
}
```

`workshop` creates a mechanism with physics, joints, and controls. `garden` creates a field of instanced geometry with local behavior. Choose an origin in clear space in your current scene; the coordinates above are world coordinates, not a camera-relative placement.

Each example uses stable IDs. Creating the same example twice returns an error instead of duplicating it. Both examples resume the creation world, so check any existing creations before starting one.

## Build through the agent

Ask:

> Use ar\_world to build a small kinetic sculpture with a speed slider and an on/off toggle. Keep it within arm's reach, make it grabbable, and run its animation locally. Verify the result, then finish your turn.

The agent first calls `ar_world` with `command: "capabilities"` for the current schema. It uses `apply` to submit validated batches, `observe` to read the actual scene, and `program` to install behavior.

```json theme={"theme":"github-light-default"}
{
  "name": "ar_world",
  "arguments": {
    "command": "apply",
    "payload": {
      "requestId": "create-study-cube-v1",
      "operations": [{
        "op": "entity.create",
        "entity": {
          "id": "study.cube",
          "name": "Study cube",
          "geometry": { "shape": "box", "size": [0.2, 0.2, 0.2] },
          "material": { "color": "#6E7DFF" },
          "transform": { "position": [0, 1, -1.5] },
          "grabbable": true
        }
      }]
    }
  }
}
```

Reuse a `requestId` only when retrying the same batch. Give a new edit a new ID. An optional `baseRevision` checks that the world has not changed since the agent inspected it. A batch validates before it commits.

World units are metres, Euler XYZ radians, and seconds, with Y up. Child transforms are relative to their parent group.

## Move and operate creations

| Input                            | Action                                                        |
| -------------------------------- | ------------------------------------------------------------- |
| Drag a grabbable object          | Move it through the scene                                     |
| Scroll while holding it          | Change its depth                                              |
| Shift-scroll while holding it    | Resize it                                                     |
| Alt-scroll while holding it      | Rotate it                                                     |
| Release a dynamic physics object | Throw it using the release motion                             |
| Click a scene button or toggle   | Activate its control                                          |
| Drag a scene slider              | Change its value                                              |
| Objects inspector                | Edit position, rotation, scale, or color; duplicate or delete |

Touch uses the same pointer interaction path. On a supported immersive surface, tracked controller rays can grab objects; two tracked pointers can scale and rotate a held object. Physical headset interaction still needs testing on your device.

A human grab owns the object's transform until release. Agent edits and local programs cannot pull it away while you hold it. New Blender previews wait until release, then update the geometry without replacing the human placement.

## Save, pause, and recover

**Pause creations** pauses physics and local programs. **Resume creations** continues them. These controls do not pause the Entity's inference or terminate a Blender process; see [stop controls](/guides/usage-and-controls#stop-a-response-or-stop-the-process).

Scene edits autosave in this browser origin. **Save** checkpoints the world; **Export** downloads a `.ngram.json` document; **Import** restores one. Programs restore paused. **Undo** and **Redo** operate on scene edits and pause creations before applying history.

An export contains scene data, program source/state, and asset references. It does not embed GLB files or Blender projects. Back up those artifacts separately. A different browser, device, or origin has a separate local world library; this is not shared multiplayer or cloud synchronization.

If a saved program references a deleted object, the scene can still restore and the program reports a failure for repair. If the world itself cannot restore, automatic saving is blocked to preserve its saved data. Import a repaired world to resume saving.

## Runtime budgets

The current contract allows 512 entities per world, 256 operations per batch, 12 programs, 8 assets, and 8 lights. The world has a combined budget of 30,000 raw geometry vertices and 2,048 instance offsets. Assets are limited to 32 MB; imported GLB geometry is limited to 100,000 vertices per asset.

These are validation ceilings, not a performance guarantee for every headset. Use `observe` for asset readiness, errors, bounds, program status, and current performance measurements.