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	Original meshes and authored materials, built on the agent’s execution computer and published into Spatial
Programs	Local JavaScript that animates creations and responds to human interaction
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:

{
  "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.

{
  "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.

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.