Make objects come alive

A Figment is an interactive object built from an existing Spatial creation. Its definition adds named parts, grips, properties, actions, and local JavaScript behavior. Geometry can come from Blender, a primitive, or an assembly of objects. A lamp can pulse while you carry it. A machine can expose motor speed and spring stiffness. A crystal can react to impacts. Agents can write the behavior themselves; presets are editable starting points.

Try a Figment

Download the working lantern tool calls. Ask your agent to execute them in order. The example creates a glowing orb, attaches the lantern preset, adds a grip and adjustable physics, and starts its behavior. This is a tool-call recipe, not a package for the Import button. Open Objects, select the lantern, and change its light, brightness, pulse, or tint. Toggle light invokes its action. Double-clicking the object or pressing E invokes its first action. In XR, squeeze the controller while holding it. A trigger or pinch near a grip aligns the object with the hand; two-hand grips can aim an object or scale it. The drawer shows whole creations by default. Show parts reveals their components. Duplicate copies a Figment’s complete assembly and remaps its references; Delete removes the assembly.

Agent tools

The Figment bundle extends the existing Spatial tools. These tools work from a connected Spatial conversation or another surface, such as Telegram, belonging to the same Entity.

Tool	Commands
`ar_figment`	`capabilities`, `inspect`, `attach`, `configure`, `detach`
`ar_figment_physics`	`physics`
`ar_figment_behavior`	`behavior`
`ar_figment_interact`	`properties`, `action`
`ar_figment_library`	`library`, `publish`, `export`, `import`, `place`

Start with ar_figment capabilities for the current contract and preset source. Direct provider bindings expose the same names without the ar_ prefix. Every command returns a correlated renderer result; a timeout means execution is unknown, so do not blindly replay placement.

Attach a definition

Create or load the geometry first, then inspect its real ID. The following call attaches an editable lantern to the lantern object created by the downloadable recipe:

{
  "name": "ar_figment",
  "arguments": {
    "command": "attach",
    "payload": {
      "id": "lantern",
      "preset": "lantern",
      "definition": {
        "title": "Pocket lantern",
        "version": "1.0.0",
        "anchors": {
          "handle": { "position": [0, 0.1, 0], "rotation": [0, 0, 0] }
        },
        "grips": {
          "hold": { "anchor": "handle", "hand": "either", "twoHand": "aim" }
        }
      }
    }
  }
}

attach and configure merge top-level definition fields. Named maps replace in full, so include every entry you want to retain. New or changed behavior starts paused unless start: true is supplied. Editing a title, grip, or physical property preserves unchanged behavior state.

Definition field	Meaning
`protocol`	`ngram.figment/1`; filled automatically when omitted
`title`, `description`, `version`	Human-readable identity; version uses `major.minor.patch`
`parts`	Names mapped to entity IDs; `self` always refers to the Figment root
`joints`	Names mapped to world joint IDs whose bodies are named parts
`anchors`	Named positions and rotations, with optional `part` and unique GLB `node` name
`grips`	Named grips referencing an anchor; `hand`, grab `radius`, and `twoHand` mode
`properties`	Typed values with labels, editability, and optional numeric bounds
`actions`	Named actions mapped to `{ "label": "Button label" }`
`behavior`	`{ "source": "JavaScript", "hz": 20 }`
`source`	Optional `{ "url": "...", "filename": "project.blend" }`

Figment roots are world roots. Parts cannot belong to two Figments. Children of a named group travel with the assembly. Separate physical parts remain world roots and connect through joints. Anchors use part-local metres and Euler XYZ radians. A node selects a uniquely named node inside an imported GLB. Missing or ambiguous nodes are reported rather than silently attaching a grip to another location. Keep Blender node names stable across mesh revisions. In the Grips section, you can inspect these errors, reveal markers, adjust offsets, and choose hand or two-hand behavior.

Write behavior

Agent-authored JavaScript uses the same sandbox as creation programs. It returns tick, event, or both. This example changes the lantern when its action fires:

return {
  event(e) {
    if (e.type === "action" && e.data.action === "toggle") {
      api.setProperty("on", !api.property("on"));
    }
  },
  tick() {
    api.patch("self", {
      material: {
        emissive: api.property("tint"),
        glow: api.property("on") ? api.property("brightness") : 0
      }
    });
  }
};

Install it through ar_figment_behavior with command: "behavior" and payload: {id, source, hz, start}. Without source, use payload: {id, action: "pause"}, "resume", or "reset". Reset clears behavior state and leaves it paused. Resuming a behavior also resumes world physics; other paused programs stay paused.

API	Purpose
`api.self`, `api.part(name)`	Live root or named-part snapshot, including `heldBy`
`api.anchor(name)`	Resolved world position and quaternion, readiness or error
`api.property(name)`	Current typed property value
`api.setProperty(name, value)`	Change a property through validation
`api.patch(part, patch)`	Patch a named part’s transform, geometry, material, control, visibility or physics
`api.impulse(part, xyz, torque?)`	Apply a physical impulse to a dynamic part
`api.motor(name, velocity, strength?)`	Drive a named hinge or slider
`api.signal(name, data)`	Emit a local signal event for this Figment
`api.state`, `api.time`, `api.dt`	Persistent JSON state and local simulation timing

Use named bindings instead of hard-coded instance IDs so imported copies run the same source. Programs cannot create/delete objects, install code, use the DOM, import modules, or access the network. Humans retain physical control while holding an object; its properties, glow and other nonphysical responses can continue to work. Events include action (data.action), property (data.name, data.value), grab, grip, release, collision, collision.end, sensor.enter, sensor.exit, and signal. See Physics for contact data. Events and animation never trigger model inference. ar_figment inspect accepts payload: {id, includeSource: true} when you need the source. Routine observations omit source text. Figment behaviors share the world’s 12-program budget, run at 1–30 Hz, and have a 60,000-character authoring limit. Keep each tick small. Objects → Publish & share → Publish version freezes a version in this browser’s Figment library. A published title/version cannot be replaced with different content; increase its version to publish a revision. The package contains the assembly, its physical settings and joints, grips, typed properties, and editable JavaScript. Model assets are included by content hash. Linked Blender projects also include their matching .blend revision; custom sources can be supplied explicitly. Source files remain available through Download Blender source. Export to share downloads a .figment.json file. Send that file through your preferred channel. Another person can choose Figment library → Import Figment, then Place. Imported assets are checked against SHA-256 hashes and package boundaries. The placed copy receives new IDs and remains paused until resumed. Agent equivalents:

Command	Payload
`publish`	`{ "id": "lantern" }`
`library`	`{}`
`export`	`{ "packageId": "published SHA-256 ID" }`
`import`	`{ "url": "package URL", "place": false }`, or a `package` object
`place`	`{ "packageId": "published SHA-256 ID", "position": [0, 1, -1] }`

Export starts a download on the human’s device and returns a small receipt; it does not stream model binaries into the conversation. Publishing is a local library operation. There is no hosted public gallery or cloud synchronization in this version. Packages allow 128 MB of combined binary content and 192 MB of serialized JSON. Rendered GLBs retain the 32 MB and 100,000-source-vertex limits. Binary assets and published versions live in IndexedDB; active worlds and program checkpoints use the existing creation storage. Export packages for backups: clearing site data removes the local library, and a world JSON alone does not carry packaged binary assets.

Getting started

Build

Reference

Make objects come alive

Try a Figment

Agent tools

Attach a definition

Write behavior

​Try a Figment

​Agent tools

​Attach a definition

​Write behavior

​Publish and share

Try a Figment

Agent tools

Attach a definition

Write behavior

Publish and share