Give creations their own behavior

The agent writes a program once. The browser runs its animation and interaction handlers locally, including after the agent finishes speaking. A sculpture can turn when you press a button; a slider can change its speed without another model request.

A working turntable

Download the complete tool-call example. It creates a grabbable box, a numeric toggle, and a speed slider, installs a scoped program, and resumes the world. Ask the agent to execute the calls in order through ar_world after choosing a clear origin. The file contains tool calls, so do not use the world Import button for it. Its JavaScript source is:

return {
  tick() {
    const model = api.get('turntable.model');
    const toggle = api.get('turntable.toggle');
    const slider = api.get('turntable.speed');
    if (!model || model.heldBy || !toggle || !slider) return;
    if (toggle.control.value === 0) return;
    const rotation = model.transform.rotation.slice();
    rotation[1] += slider.control.value * api.dt;
    api.emit([{
      op: 'entity.patch',
      id: model.id,
      patch: { transform: { rotation } }
    }]);
  }
};

The program starts with the toggle off. It reads the live rotation each frame, so a human rotation becomes its new starting point. It preserves position and scale and skips a held object. Toggle values are numbers: 0 is off and 1 is on. Use the same pattern with a Blender asset: obtain its ID from ar_world observe, substitute that ID for turntable.model, and include it in the program’s entityIds. This controls the imported asset’s scene transform. It is not direct access to Blender’s Python process or every internal mesh node.

Install through the agent

Call ar_world with command: "program" and a payload containing command: "install" and program:

Program field	Meaning
`id`	Stable program ID; installing it again replaces the previous version after validation
`name`	Optional human-readable label
`source`	JavaScript returning `tick`, `event`, or both
`entityIds`	Existing objects the program can read and control
`params`	JSON settings that can be updated without changing the source
`state`	Mutable JSON state saved at checkpoints
`hz`	Tick rate from 1 to 30 Hz

Create the objects before installing their program. For manual experiments, select an object, open Objects → Programs, enter source, and choose Run on selected object. That editor scopes the program to the selected object only; use the agent API when a program needs multiple objects and controls.

Runtime API

API	Value or behavior
`api.get(id)`	Live scoped entity snapshot, including transform, controls, and `heldBy`
`api.dt`	Seconds since the previous simulation step, bounded by the runtime
`api.time`	Program simulation time in seconds
`api.params`	Current JSON parameters
`api.state`	Mutable JSON state
`api.emit(operations)`	Validated world operations for the program’s allowed objects

An event(event) handler receives scoped grab, release, control, collision, and edit events. Events include type, target, actor, and data; a control change supplies data.value. Read the current capabilities result for the full contract. Programs can patch transforms, geometry, materials, visibility, and controls, apply impulses, and drive joints whose bodies are both in scope. They cannot create or delete objects, install more programs, use the DOM, import code, or access the network. The runtime also rejects changes to held objects even if a program forgets to check heldBy.

Inspect, pause, and resume

{
  "name": "ar_world",
  "arguments": {
    "command": "program",
    "payload": { "command": "inspect", "id": "turntable.rotation", "includeSource": true }
  }
}

Inspect reports state, errors, frames, and simulation time. Use program commands pause, resume, remove, or parameters with its ID. The parameters command takes a params object. Pause all creations with ar_world pause or the Pause creations button. World exports retain source, parameters, JSON state, and simulation time. Imported and restored programs remain paused until resumed. Local programs stop stepping while the page is hidden. The runtime allows 12 programs and 64,000 source characters per program. A worker that fails or exceeds its 500 ms response budget terminates without blocking the main scene. Keep work per tick small; use instancing or authored GLB animation for repeated visual structure.

Model usage

Program frames, physics, control events, and Blender preview delivery do not initiate model calls. Asking the Entity to design or change a creation does use inference. Other background Entity tasks remain independent; use Pause inference when you want to stop model use globally.

Getting started

Build

Reference

Give creations their own behavior

A working turntable

Install through the agent

Runtime API

Inspect, pause, and resume

Model usage

​A working turntable

​Install through the agent

​Runtime API

​Inspect, pause, and resume

​Model usage

A working turntable

Install through the agent

Runtime API

Inspect, pause, and resume

Model usage