---
name: figmin-xr-scripting
description: >-
Comprehensive reference for the Figmin XR Scripting API. Use this skill
whenever writing JavaScript for Figmin XR spatial apps, creating or
manipulating 3D objects, working with the MCP agent bridge, or building
XR experiences. Covers object creation, transforms, physics, sketches,
input, raycasting, multiplayer, the Agent camera object (MCP), and all
component APIs. Platforms: Meta Quest, Steam VR, Windows, Vision OS, iOS.
API docs: https://www.figmin.com/api
---
# Figmin XR Scripting API Reference
Comprehensive reference for building spatial apps in Figmin XR. This document provides the core details needed to write Figmin XR spatial apps, including key concepts, APIs, and patterns. For an in-depth look including additional examples, full app demos, and downloadable code—visit the official documentation at https://www.figmin.com/api
## What is a Spatial App?
A **Spatial App** is an HTML page deployed into the 3D scene (not just viewed in Figmin's built-in browser). Spatial apps can:
- Create and manipulate 3D objects in the scene
- Control their own position, rotation, and scale in the scene (via `getAppObject()`)
- Access player body parts (hands, head) for interaction
- Use physics, lighting, and other scene features
- Persist beyond the browser session
When you load an HTML page in Figmin's browser, it runs in "browser mode". To access most API features, you must **deploy** it as a spatial app (the system prompts for this, or you can call `figmin.requireSpatialApp()`).
**Note**: Some API functions work in browser mode (e.g., `getWindow()`, `getCamera()`, `print()`), but most require spatial app mode (e.g., `createObject()`, `getAppObject()`, input connection).
## UI Design Guidelines
Figmin XR apps may be operated via **eye tracking** and **hand tracking**, not just controllers. Design your UI accordingly:
- **Use large buttons** (minimum 48x48px, prefer 64x64px or larger)
- **Add spacing between interactive elements** to prevent mis-taps
- **Avoid small text** - use at least 16px font size
- **Provide visual feedback** for hover/focus states
- **Keep UI simple** - fewer elements work better in XR
## Quick Start Template
```html
My Spatial App
```
## Coordinate System
- **+X** = Right
- **+Y** = Up
- **+Z** = Forward (Unity-style)
- Units: **meters** for positions/sizes, **degrees** for Euler rotations
**World Origin**: The coordinate `(0, 0, 0)` represents the center of the user's room/play space at floor level. Objects positioned at `y: 0` will be on the floor.
## Events
### FigminPreload
Fires early, before API is ready. Used for engine configuration before initialization.
### FigminReady
Fires when API is initialized. Start your app here:
```javascript
document.addEventListener("FigminReady", init);
function init() {
if (!figmin.isSpatialApp()) {
figmin.requireSpatialApp();
return;
}
// Your app logic
}
```
---
## FigminObject
Core entity (similar to Unity GameObject). All scene objects are FigminObjects.
### Properties
| Property | Type | Access | Description |
|----------|------|--------|-------------|
| `oid` | string | read-only | Internal object id, scoped to this script/session (not visible to other apps, doesn't persist across reloads) |
| `name` | string | read-only | Globally addressable name, set via `createObject` params. Names are enforced unique — if taken, Figmin auto-adjusts it, so read back `obj.name` after `onStart` if you need it later |
| `objectType` | ObjectType | read-only | The `figmin.ObjectType` of this object |
| `active` | boolean | read-write | Visibility (true=visible) |
| `interactionState` | InteractionState | read-write | ENABLED or LOCKED |
| `scenePersistent` | boolean | read-only | true = survives script end |
| `parent` | FigminObject\|null | read-write | Parent object (set to parent, null to unparent) |
| `children` | FigminObject[] | read-only | Direct child objects |
### Components (always present)
- `status` - Lifecycle state
- `transform` - Position, rotation, scale
- `collider` - Collision shape
### Type-specific Components
- TEXT3D → `text3d`
- MODEL3D → `model3d`
- IMAGE → `image`
- SKETCH → `sketch`
- PORTAL → `portal`
- BODYPART → `bodypart`
- AGENT → `agent` (MCP sessions only)
- APP → `app`
### Lifecycle Methods
```javascript
// Called when object becomes READY
obj.onStart((object) => { });
// Called when object is destroyed
obj.onDestroy((object) => { });
// Called on error (e.g., model load failed)
obj.onError((object) => { });
// Called each frame (per-object)
// NOTE: Unlike other callbacks, onUpdate receives ONLY deltaTime, not (object, deltaTime).
// Access the object via its outer variable reference.
obj.onUpdate((deltaTime) => { });
obj.onUpdate(null); // stop per-object update loop
```
### Object Methods
```javascript
// Add runtime component
obj.addComponent(figmin.ComponentType.PHYSICS, { mass: 1.0 });
obj.addComponent(figmin.ComponentType.LIGHT, { type: figmin.lights.LightType.POINT });
obj.addComponent(figmin.ComponentType.MOTION);
obj.addComponent(figmin.ComponentType.PHYSICS_MATERIAL, { bounciness: 0.8 });
// Remove component
obj.removeComponent(figmin.ComponentType.PHYSICS);
// Destroy object
// NOTE: You can only destroy objects owned by this script, calls to destroy foreign objects will simply make them untracked.
obj.destroy();
```
### Object Parenting
Objects can be parented to form hierarchies. The transform provides both **world-space** and **local-space** accessors. When parented, `localPosition` / `localRotation` are relative to the parent (Unity-standard behavior — parent scale affects local-to-world conversion). `position` / `rotation` always return world-space values regardless of hierarchy depth. To parent objects, set `.parent` after creation — create objects first, then assign the hierarchy.
```javascript
// Create objects first, then parent
child.parent = parentObj;
// Unparent (returns to scene)
child.parent = null;
// Read parent
if (obj.parent) {
console.log("Parent is: " + obj.parent.name);
}
// World vs local
console.log(child.transform.position); // world-space position
console.log(child.transform.localPosition); // position relative to parent
console.log(child.transform.scale); // world scale
console.log(child.transform.localScale); // scale relative to parent
```
**Restrictions:**
- **Physics** and parenting are mutually exclusive: remove one before adding the other
- When parent is **destroyed**, all children are also destroyed (if script-owned)
---
## Creating Objects
### figmin.createObject(type, params?)
Returns FigminObject immediately (UNINITIALIZED). Wait for `onStart()`.
**Requirements**: Master client only
### ObjectType.TEXT3D
```javascript
const obj = figmin.createObject(figmin.ObjectType.TEXT3D, {
position: { x: 0, y: 1, z: 0 },
rotation: figmin.getWindow().transform.rotation, // Faces user (no flip needed)
text: "Hello World",
size: 0.08, // capital-letter height in meters
font: "roboto", // see fonts list below
material: "metallic", // see materials list below
depth: 0.01, // depth in meters
bend: 0, // degrees (-360 to 360)
frontColor: "#FFE6C6",
sideColor: "#310E65",
colliderType: figmin.ColliderType.BOX
});
```
**TEXT3D Sizing**:
Use `size` for readable text; it sets capital-letter height in meters.
Use `targetSize` only to fit the entire text object into a maximum overall size.
Do not pass both; `targetSize` takes precedence and can make long text tiny.
**Supported Fonts**: `"default"`, `"pixels"`, `"curved"`, `"classic"`, `"open sans"`, `"roboto"`, `"caveat"`
**Supported Materials**: `"standard"`, `"metallic"`, `"unlit"`, `"matcap"`, `"hologram"`, `"fire"`, `"hypercolor"`, `"hueshift"`, `"diamond"`, `"rainbow"`
### ObjectType.MODEL3D
```javascript
const obj = figmin.createObject(figmin.ObjectType.MODEL3D, {
position: { x: 0, y: 0, z: 1 },
rotation: { x: 0, y: 0, z: 0 },
url: "https://example.com/model.glb", // GLB only (not GLTF)
targetSize: 0.5,
colliderType: figmin.ColliderType.APPROXIMATE
// transparent: false — optional; alpha-blended rendering (not recommended, cutout is default)
});
obj.onStart((o) => {
// Access animations (only available after onStart)
console.log(o.model3d.getAnimationNames()); // string[]
o.model3d.play("Walk", true); // name, loop
o.model3d.setAnimationSpeed(1.5);
o.model3d.stop();
});
```
### ObjectType.IMAGE
```javascript
const obj = figmin.createObject(figmin.ObjectType.IMAGE, {
position: { x: 0, y: 1.5, z: 0 },
url: "https://example.com/image.png",
targetSize: 0.3
});
```
### ObjectType.SKETCH
```javascript
const obj = figmin.createObject(figmin.ObjectType.SKETCH, {
position: { x: 0, y: 1, z: 0 },
brushStrokes: [stroke1, stroke2] // Required — see SKETCH gotcha above
});
```
### ObjectType.PORTAL
```javascript
const obj = figmin.createObject(figmin.ObjectType.PORTAL, {
position: { x: 0, y: 0, z: 2 },
targetSize: 1.0,
scene: "https://share.figmin.com/asset/4807d1be-0464-11ed-8b86-0236d6272b39"
});
```
### ObjectType.AGENT
**MCP sessions only** — The Agent object carries a camera that lets you visually verify your own work. Create and manipulate objects first, then use the agent camera to check the results when needed.
**You do NOT need to create an agent camera at the start of every session.** Only create one when you want to see something you've built or modified. The scene may be empty when you start — there's nothing to look at until you've created something.
**Limitations**: Agent objects are **local-only** (not networked). They do not support `addComponent`, cannot be found via `findObjectByName`, have no colliders, and cannot be created with `scenePersistent`. They are automatically destroyed when the script/session ends.
```javascript
// After creating some objects, set up a camera to check your work
window.agentObj = figmin.createObject(figmin.ObjectType.AGENT, {
position: figmin.getWindowSpawnPosition(0.5, "front"),
rotation: figmin.getWindow().transform.rotation,
fieldOfView: 60,
backgroundColor: "#0F486C"
});
// Point the camera at a specific object you created, then capture
window.agentObj.agent.lookAtObject(myCreatedObject);
const img = await window.agentObj.agent.captureView(512, 80);
console.image(img.data, "image/" + img.format);
```
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `fieldOfView` | number | 50 | Starting field of view of the agent camera (degrees) |
| `backgroundColor` | string | "#0F486C" | Camera background color as hex |
### ObjectType.APP
Creates a spatial app — a browser surface living in 3D space. Through the `app` component you can load HTML or URLs, access the app's console logs, and query ownership information.
This is particularly useful for AI agents running live sessions (e.g. through MCP). Instead of modifying their own app context, agents can create independent APP objects, load self-contained HTML apps into them, and monitor their output via console logs. Each spawned app runs in its own isolated context and persists independently, enabling the agent to build and deploy spatial apps into the scene rather than managing everything within a single script.
**Security**: In multiplayer sessions, only the master client (the player who owns the app) can perform state-changing operations on it. Cross-player modification is forbidden — see `isMasterClient` in the app component.
```javascript
const myApp = figmin.createObject(figmin.ObjectType.APP, {
position: figmin.getWindowSpawnPosition(0.3, "right"),
rotation: figmin.getWindow().transform.rotation
});
myApp.onStart(() => {
// Load custom HTML
myApp.app.loadHTML(`
Hello from Figmin XR
`);
// Or load a URL
myApp.app.loadURL("https://www.figmin.com");
// Monitor logs
myApp.app.showConsole(true);
const logs = await myApp.app.getConsoleLogs(10);
console.log(logs);
});
```
**Cross-app messaging**: Apps can communicate with each other using `sendMessage` and `onMessage`. Always send from your own app and target the other app by name.
```javascript
// Agent creates a child app with an echo bot
const child = figmin.createObject(figmin.ObjectType.APP, {
position: figmin.getWindowSpawnPosition(0.3, "right"),
rotation: figmin.getWindow().transform.rotation
});
child.onStart(() => {
child.app.loadHTML(`
Echo Bot
`);
});
// Agent listens for replies on its own app
const myApp = figmin.getAppObject();
myApp.app.onMessage((senderName, data) => {
console.log("Reply from " + senderName + ": " + JSON.stringify(data));
});
// Agent sends a message from its own app, targeting the child
myApp.app.sendMessage({ action: "ping" }, figmin.MessageRecipient.ALL, child.name);
```
### Common Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `position` | {x,y,z} | Initial world-space position in meters |
| `rotation` | {x,y,z} | Initial Euler degrees |
| `targetSize` | number | Uniform scale (largest dimension = this) |
| `colliderType` | ColliderType | BOX, SPHERE, APPROXIMATE, EXACT, NONE |
| `scenePersistent` | boolean | Survives script end (default: false) |
---
## Object Lifecycle
Objects created via `createObject()` go through lifecycle states, but **use event callbacks** instead of checking state:
- `onAwake()` - Called when object is created (before loading)
- `onStart()` - Called when object is **READY** - use this before accessing properties/components
- `onError()` - Called if object fails to load
- `onDestroy()` - Called when object is destroyed
**No promise support**: These lifecycle events are **callback-only**. They do not return promises. Unlike raycast functions, lifecycle events are not guaranteed to fire (e.g. an object may silently fail to load, get stuck in LOADING, or be destroyed before reaching READY), so awaiting them could hang indefinitely.
```javascript
const obj = figmin.createObject(figmin.ObjectType.MODEL3D, params);
obj.onStart(() => {
// Safe to access properties and add components here
obj.addComponent(figmin.ComponentType.PHYSICS);
});
obj.onError(() => {
console.error("Failed to load object");
});
```
---
## Components Reference
### Component: status
```javascript
obj.status.state // ObjectState enum
obj.status.code // Error code (if ERROR state)
obj.status.description // Error description
obj.status.onStatusChanged((object) => { });
```
**ObjectState**: `UNINITIALIZED`, `LOADING`, `READY`, `DESTROYED`, `ERROR`
### Component: transform
```javascript
// World-space accessors (walk the parent hierarchy; for root objects, same as local)
obj.transform.position // {x, y, z} world-space meters
obj.transform.rotation // {x, y, z} world-space Euler degrees
obj.transform.rotationq // {x, y, z, w} world-space quaternion
obj.transform.scale // number (world scale — the value synced with C#)
// Local-space accessors (relative to parent; for root objects, same as world)
obj.transform.localPosition // {x, y, z} local-space meters (Unity-standard: parent scale affects conversion)
obj.transform.localRotation // {x, y, z} local-space Euler degrees
obj.transform.localRotationq // {x, y, z, w} local-space quaternion
obj.transform.localScale // number (scale relative to parent, derived from world scales)
// Read-only
obj.transform.size // {x, y, z} world-space bounding-box (bounds × world scale)
obj.transform.bounds // {x, y, z} raw geometry bounding-box, unaffected by scale
obj.transform.forward // {x, y, z} world-space unit vector
obj.transform.up // {x, y, z} world-space unit vector
obj.transform.right // {x, y, z} world-space unit vector
// Events
obj.transform.onBoundsChanged((objectRef, bounds) => {
// bounds: {x, y, z} - raw geometry bounding-box size in meters
// objectRef.transform.size - world-space bounding-box (accounts for scale)
});
// Methods
obj.transform.lookAt(position, up?);
// Rotates this object so transform.forward points at a world-space target position.
// Works correctly for parented objects (automatically converts to local rotation).
// position: {x,y,z} - world-space target point (not a direction)
// up: {x,y,z} - optional world up direction, defaults to {x:0, y:1, z:0}
// Example: make an object face the player camera
const target = figmin.getCamera().transform.position;
obj.transform.lookAt(target);
```
### Component: collider
```javascript
obj.collider.type = figmin.ColliderType.SPHERE;
// Collision callback — onCollisionEnter is the ONLY collision event.
// There are no exit or trigger callbacks in the API.
obj.collider.onCollisionEnter((payload) => {
console.log("Hit:", payload.objectName, "at", payload.point);
}, ["objectName", "point", "normal", "velocity"]); // requestedData array
obj.collider.onCollisionEnter(null); // unregister — collision events are only computed while a callback is registered
// requestedData options: "velocity", "impulse", "layer", "point", "normal", "object", "objectName"
// Request only the fields you need — fewer fields = better performance.
```
**Note**: `payload.object` is `null` when the hit object wasn't created by this script. Use `payload.objectName` with `findObjectByName()` to start tracking it; after that, `object` will be valid in future callbacks.
**ColliderType**: `NONE`, `BOX`, `SPHERE`, `APPROXIMATE`, `EXACT`
- Physics requires: BOX, SPHERE, or APPROXIMATE (not EXACT/NONE)
### Component: text3d
```javascript
obj.text3d.text = "New Text";
obj.text3d.font = "roboto"; // see fonts list in ObjectType.TEXT3D
obj.text3d.material = "metallic"; // see materials list in ObjectType.TEXT3D
obj.text3d.size = 0.1; // capital letter height in meters
obj.text3d.depth = 0.03; // extrusion thickness in meters
obj.text3d.bend = 45; // arc angle in degrees
obj.text3d.frontColor = "#00FF00"; // front face color
obj.text3d.sideColor = "#005500"; // side/extrusion color
```
**Note**: Changing `text` rebuilds the geometry — the object cycles **READY → LOADING → READY** and `onBoundsChanged` fires again. Use that to react to the new size (see the dynamic text background pattern).
### Component: model3d
**Supported format**: GLB only. Animation data / Node access available only after `onStart`.
```javascript
// Properties (read-only)
obj.model3d.url // string - model URL
obj.model3d.transparent // boolean - transparency mode
// Animation playback
obj.model3d.play(name?, loop?, speed?, normalizedStart?); // Play animation
obj.model3d.stop(); // Stop animation
obj.model3d.setAnimationSpeed(speed); // Set playback speed
obj.model3d.getAnimationSpeed(); // Returns number
// Animation info (call after onStart)
obj.model3d.getAnimationNames(); // Returns string[]
obj.model3d.hasAnimation(name); // Returns boolean
obj.model3d.getAnimationDuration(name); // Returns number (seconds)
obj.model3d.isLooping(); // Returns boolean
obj.model3d.getCurrentAnimationName(); // Returns string | null
obj.model3d.getCurrentAnimationTime(); // Returns number (seconds)
obj.model3d.getCurrentAnimationNormalizedTime(); // Returns number (0..1)
// Node access (for animating parts of the model)
const names = await obj.model3d.getNodeNames(); // Returns string[] of all node names
const node = obj.model3d.getNode("wheel-front-left"); // Returns ModelNode handle
// ModelNode — local-space transform (write-only, relative to parent in GLB hierarchy). Always make full assignments
node.localPosition = { x: 0, y: 0.2, z: 0 }; // meters
node.localRotation = { x: 0, y: 45, z: 0 }; // Euler degrees
node.localRotationq = { x: 0, y: 0.38, z: 0, w: 0.92 }; // quaternion
node.localScale = { x: 1.2, y: 1, z: 1 }; // per-axis (unlike FigminObject's uniform scale)
node.active = false; // hide node and children
```
**Note**: Animation names are case-insensitive.
**Note**: Node names are **case-sensitive**. Use `getNodeNames()` to discover available names at runtime. `getNode()` is currently write-only — default bone values are not sent from C#.
### Component: image
```javascript
obj.image.url // string (read-only, set at creation)
obj.image.material // "unlit" | "lit" | "unlit_transp" | "lit_transp" (read-only, set at creation)
```
**Supported formats**: PNG, JPG, WEBP, GIF. Default material is `"unlit"` (unlit cutout — recommended); `lit` variants receive scene lighting, `_transp` variants use smooth alpha blending. Both properties are fixed at creation — to change them, destroy and recreate the object.
### Component: portal
Present only on PORTAL objects. Links to another published scene.
```javascript
obj.portal.scene // string (read-only, set at creation) — target scene id
obj.portal.activate(); // Request the scene switch. WARNING: ends the current script/app context.
```
Figmin XR includes a procedural sketch system derived from Tilt Brush. The entire brush catalog (flat paints, 3D tubes, convex hulls, particles, audio-reactive variants) is available via the API. You can generate 3D geometry procedurally using shape generators (boxes, spheres, cylinders, etc.) and stroke manipulation functions.
**Sketch components are not limited to SKETCH objects** — you can add a sketch component to any object using `addComponent(figmin.ComponentType.SKETCH)`. This is useful for attaching procedural geometry to TEXT3D, MODEL3D, or other objects (e.g. adding a background panel behind text).
### Component: sketch
```javascript
// Set brush strokes (positions and rotations are in the sketch object's local space)
obj.sketch.setBrushStrokes([stroke1, stroke2]);
// Get brush strokes (async, returns strokes in the sketch object's local space)
obj.sketch.getBrushStrokes((strokes) => {
// strokes: array of {id, c, s, pts}
});
```
### Component: physics
**Requires**: Compatible collider (BOX, SPHERE, APPROXIMATE)
```javascript
obj.addComponent(figmin.ComponentType.PHYSICS, {
mass: 1.0,
drag: 0.1,
angularDrag: 0.05,
gravityStrength: 1.0,
kinematic: false,
sleeping: false,
freezePosition: false, // freezes translation on ALL axes (single boolean)
freezeRotationAxes: { x: false, y: false, z: false }, // freeze rotation per axis
collisionDetectionMode: figmin.physics.CollisionDetectionMode.CONTINUOUS // default
// velocity, angularVelocity, maxAngularVelocity (default 14), motorTorque also accepted here
});
// Properties
obj.physics.mass = 2.0;
obj.physics.velocity = { x: 0, y: 5, z: 0 };
obj.physics.angularVelocity = { x: 0, y: 1, z: 0 };
obj.physics.maxAngularVelocity = 30; // rad/s (default: 14)
obj.physics.gravityStrength = 0.5;
obj.physics.kinematic = true;
obj.physics.sleeping = false;
obj.physics.motorTorque = { x: 0, y: 2, z: 0 }; // constant angular acceleration, local space (rad/s²)
obj.physics.freezePosition = true; // boolean — all axes
obj.physics.freezeRotationAxes = { x: false, y: true, z: false };
// Force field (create gravity wells, etc.)
obj.physics.forceFieldType = figmin.physics.ForceFieldType.SPHERE;
obj.physics.forceFieldAcceleration = 10;
obj.physics.forceFieldReach = 2.0;
obj.physics.forceFieldRepulsive = false;
obj.physics.forceFieldForceType = figmin.physics.ForceFieldForceType.SQUARED; // SQUARED (falls off) or CONSTANT
obj.physics.forceFieldDirection = figmin.physics.ForceFieldDirection.UP; // for FLAT fields
obj.physics.forceFieldDrag = 0; // extra drag applied to bodies inside the field
obj.physics.forceFieldAngularDrag = 0; // extra angular drag inside the field
// Apply forces (local space)
obj.physics.applyForce({ x: 0, y: 100, z: 0 }); // Newtons
obj.physics.applyImpulse({ x: 0, y: 10, z: 0 }); // N·s
obj.physics.applyTorque({ x: 0, y: 5, z: 0 }); // N·m
obj.physics.applyAcceleration({ x: 0, y: 9.8, z: 0 }); // m/s²
obj.physics.applyAngularAcceleration({ x: 0, y: 3, z: 0 }); // rad/s²
```
**Notes**: All physics vectors (force, impulse, acceleration, torque, motorTorque) are in the object's **local** space. Mass scales linearly with `transform.scale` (deliberate simplification). Vector-like properties (`velocity`, `angularVelocity`, `motorTorque`, `freezeRotationAxes`) follow the assign-a-new-object rule — never mutate in place.
### Component: physicsMaterial
```javascript
obj.addComponent(figmin.ComponentType.PHYSICS_MATERIAL, {
bounciness: 0.8,
staticFriction: 0.3,
dynamicFriction: 0.3,
bounceCombine: figmin.physics.Combine.AVERAGE,
frictionCombine: figmin.physics.Combine.AVERAGE
});
// Properties
obj.physicsMaterial.bounciness = 0.4;
obj.physicsMaterial.staticFriction = 0.6;
obj.physicsMaterial.dynamicFriction = 0.6;
obj.physicsMaterial.bounceCombine = figmin.physics.Combine.MAXIMUM;
obj.physicsMaterial.frictionCombine = figmin.physics.Combine.MINIMUM;
```
**Important**: Physics requires a built collider, so always add it inside `onStart` — not immediately after `createObject`:
```javascript
const ball = figmin.createObject(figmin.ObjectType.MODEL3D, {
url: "https://example.com/ball.glb",
position: spawnPos,
targetSize: 0.1,
colliderType: figmin.ColliderType.SPHERE
});
ball.onStart((b) => {
b.addComponent(figmin.ComponentType.PHYSICS, {
mass: 0.5,
gravityStrength: 1.0
});
b.physics.velocity = { x: 0, y: 5, z: 3 };
b.collider.onCollisionEnter((hit) => {
console.log("Hit:", hit.objectName);
});
});
```
### Component: light
```javascript
obj.addComponent(figmin.ComponentType.LIGHT, {
type: figmin.lights.LightType.SPOT,
color: "#FFFFFF",
range: 5.0,
spotlightAngle: 30,
rotation: { x: -45, y: 0, z: 0 },
shadowType: figmin.lights.ShadowType.SOFT,
shadowNearPlane: 0.1,
effect: figmin.lights.LightEffect.NONE,
projectionPattern: figmin.lights.LightProjection.NONE
});
// Runtime changes
obj.light.color = "#FF0000";
obj.light.range = 10;
obj.light.type = figmin.lights.LightType.POINT;
```
**LightType**: `POINT` (default), `SPOT`, `DIRECTIONAL`
**ShadowType**: `NONE`, `HARD`, `SOFT`
**LightEffect**: `NONE`, `FLICKER`, `AUDIO_REACTIVE`, `PULSE`, `RAINBOW`
**LightProjection**: `NONE`, `FLASHLIGHT1`, `SPOTLIGHT1`, `SPOTLIGHT2`
**Defaults**: color `#d47e13` (warm orange — set explicitly if you want white), range `4.0` m (POINT/SPOT only), shadowType `NONE`, shadowNearPlane `0.15`. For `rotation`, assign a new `{x,y,z}` object (never mutate in place).
### Component: motion
```javascript
obj.addComponent(figmin.ComponentType.MOTION, {
speed: 1.0,
endDelay: 0,
randomizeDelay: false,
endBehavior: figmin.MotionEndBehavior.LOOP
});
// Set keyframes
obj.motion.setKeyframes([
{ p: {x:0, y:0, z:0}, r: {x:0, y:0, z:0}, t: 0 },
{ p: {x:0, y:1, z:0}, r: {x:0, y:90, z:0}, t: 1 },
{ p: {x:0, y:0, z:0}, r: {x:0, y:180, z:0}, t: 2 }
], false); // fixedPlacement: false = keyframes relative to the object; true = world space
// Get keyframes (rotations always come back as quaternions)
obj.motion.getKeyframes((data) => {
// data: { frames: [{p:{x,y,z}, r:{x,y,z,w}, t:number}, ...], fixedPlacement: boolean }
});
```
**MotionEndBehavior**: `LOOP`, `PING_PONG`
### Component: audio
Adds spatial audio with support for multiple simultaneous clips. Each named clip has independent playback and spatial settings backed by its own AudioSource.
```javascript
obj.addComponent(figmin.ComponentType.AUDIO);
// Load clips (supported formats: .ogg, .wav, .mp3). Callback is optional
var engine = obj.audio.loadClip("engine", "https://example.com/engine.ogg", function(success, duration) {
if (success) {
console.log("Ready! Duration: " + duration + "s");
}
});
// Per-clip properties (read-write)
engine.spatialize = true; // 3D positional audio (default: false = flat 2D)
engine.dopplerLevel = 1.0; // 0–5, pitch shift on moving objects (default: 0 = off; only applies when spatialize is true)
engine.volume = 0.7; // 0–1 (default: 0.7)
engine.pitch = 1.0; // 0.1–3.0 (default: 1.0)
engine.loop = true; // default: true
engine.playing = false; // read-write playback state (default: true — clips start playing when loaded; set false before load to prevent autoplay)
// Playback is a persistent and networked state (default: true)
engine.play();
engine.stop();
// Read-only
engine.name; // "engine"
engine.url; // the loaded URL
engine.loaded; // true after load completes
engine.duration; // clip length in seconds (available after load)
// Component-level
obj.audio.getClip("horn"); // AudioClip or null
obj.audio.clipNames; // ["engine", "horn"]
obj.audio.stopAll();
```
**loadClip callback**: `loadClip(name, url, callback?)` — optional callback fires when the clip finishes loading or fails: `(success: boolean, duration: number)`. Properties like volume, pitch, loop can be set before the clip finishes downloading — they are applied when ready.
**Spatialize**: When `true`, audio is 3D — volume and panning change as the listener moves relative to the object. When `false`, audio is 2D (same volume everywhere). Use `false` for background music or UI sounds.
### Component: trail
Adds dynamic brush trails to an object, supporting multiple simultaneous trail emitters. Each named trail uses a brush from the `figmin.brushes` catalog to generate stroke geometry that follows the object as it moves. Use for smoke, fire, light trails, and motion effects.
```javascript
obj.addComponent(figmin.ComponentType.TRAIL); // takes no creation params — configure emitters after
// Load trails using brushes from figmin.brushes
var flame = obj.trail.loadTrail("flame", figmin.brushes.Light2);
var smoke = obj.trail.loadTrail("smoke", figmin.brushes.Smoke);
// Per-trail properties (read-write)
flame.color = "#AAAAAA"; // hex #RRGGBB (default: "#AAAAAA")
flame.size = 0.01; // stroke width in parent-local units (default: 0.01)
flame.lifetime = 0.5; // seconds before points fade (default: 0.5)
flame.maxLength = 0.05; // max trail length in parent-local units, negative = unlimited (default: -1)
flame.baseVelocity = {x: 0, y: 0.25, z: 0}; // drift in parent-local units, e.g. fire rising (default: {x:0, y:0.015, z:0})
flame.localPosition = {x: 0, y: 0.1, z: 0}; // offset relative to parent (default: {x:0, y:0, z:0})
flame.localRotation = {x: 0, y: 0, z: 0}; // Euler degrees relative to parent (default: {x:0, y:0, z:0})
flame.localRotationq = {x: 0, y: 0, z: 0, w: 1}; // quaternion alternative (default: identity)
flame.reverseDirection = false; // render trail backwards (default: false)
flame.active = true; // toggle emission (default: true). Existing points fade smoothly when disabled.
// Read-only
flame.name; // "flame"
flame.brush; // brush id string
// Component-level
obj.trail.getTrail("smoke"); // BrushTrail or null
obj.trail.removeTrail("smoke"); // remove by name
obj.trail.trailNames; // ["flame", "smoke"]
```
**Brush selection**: Pass a brush object from `figmin.brushes` (e.g., `figmin.brushes.Smoke`, `figmin.brushes.Light2`, `figmin.brushes.Fire`). The brush is validated against the catalog — invalid brushes log an error. Good trail brushes include `Smoke`, `SmokeTiny`, `Light2`, `Fire`, `Embers`, `NeonPulse`, and `SoftHighlighter`.
**Size and scale**: `size`, `baseVelocity`, and `maxLength` are in the parent's local space, not world meters. They are automatically multiplied by the parent's current scale at render time. To achieve a desired world size: `trail.size = desiredWorldSize / obj.transform.scale`. Subsequent scale changes are handled automatically.
**maxLength vs lifetime**: Use `lifetime` to control how long trail points persist (fade over time). Use `maxLength` to spatially cap the trail (e.g., flames that should not stretch when moving fast). Set `maxLength` to a negative value to disable the spatial cap.
### Component: bodypart
Retrieved via `figmin.getPlayerBodypart()`, not addable.
```javascript
const player = figmin.getLocalPlayer();
const hand = figmin.getPlayerBodypart(player, figmin.BodypartType.RIGHT_HAND);
hand.onStart((handObj) => {
// Read-only properties
handObj.bodypart.tracked // boolean
handObj.bodypart.playerId // number
handObj.bodypart.bodypartType // BodypartType
handObj.bodypart.inputType // InputType
// Ray origin (for pointing) — all read-only
handObj.bodypart.rayPosition // {x,y,z} world space
handObj.bodypart.rayRotation // {x,y,z} Euler
handObj.bodypart.rayRotationq // {x,y,z,w} quaternion
handObj.bodypart.rayForward // {x,y,z} direction
handObj.bodypart.rayUp // {x,y,z} up direction
handObj.bodypart.rayLocalPosition // ray origin offset relative to the bodypart's transform
handObj.bodypart.rayLocalRotation // (also rayLocalRotationq)
handObj.bodypart.pointerDistance // recommended ray-to-cursor distance — place pointers/tools
// at rayPosition + rayForward * pointerDistance
// Callbacks
handObj.bodypart.onTrackingChanged((obj, isTracked) => { });
handObj.bodypart.onGrabChanged((obj, isGrab, targetName, targetObj) => { });
// targetObj is null if the grabbed object isn't tracked by this script —
// use findObjectByName(targetName) to start tracking it.
});
```
**BodypartType**: `HEAD`, `LEFT_HAND`, `RIGHT_HAND`
**InputType**: `HAND_TRACKING`, `MOTION_CONTROLLER`, `TOUCH_SCREEN`
### Component: agent
**MCP sessions only** — Present only on objects of type `figmin.ObjectType.AGENT`. Provides camera capture capabilities so you can visually verify your work during an MCP session. Use it to check the results of objects you've created or modified — not as a first step before doing anything.
Access via the `agent` property on a FigminObject.
```javascript
// Properties (read-write)
obj.agent.fieldOfView // number - camera FOV in degrees
obj.agent.backgroundColor // string - camera background color hex (e.g. "#0F486C")
// Methods
// captureView(resolution?, quality?, callback?)
// Captures a screenshot from the agent's camera.
// resolution: number - size in pixels of the square capture (default: 512)
// quality: number - 0 = PNG (lossless), 1-100 = JPG at that quality (default: 0)
// Returns Promise<{format, data}> if no callback; data is base64-encoded.
const img = await obj.agent.captureView(1024, 80);
console.image(img.data, "image/" + img.format); // Send image back through MCP
// focus(rect)
// Reframe the camera to focus on a normalized screen-space rectangle.
// Rotates the agent so the rect center becomes the view center,
// then narrows fieldOfView so the rect roughly fills the square capture.
// Camera position does NOT change.
// rect: {x, y, w?, h?} - normalized coords, (0,0)=top-left, (1,1)=bottom-right
obj.agent.focus({ x: 0.25, y: 0.25, w: 0.5, h: 0.5 });
// lookAtObject(figminObject)
// Rotate and zoom the camera so a target object fits maximally in view.
// Adjusts fieldOfView so the object's bounding box fills the square capture.
// Camera position does NOT change.
obj.agent.lookAtObject(someObject);
```
### Component: app
Present on objects of type `figmin.ObjectType.APP`, and the object returned by `figmin.getAppObject()`.
Provides control over a spatial app instance — a browser surface living in 3D space. This is particularly useful for AI agents running live sessions (e.g. through MCP). Instead of modifying their own app context, agents can create independent APP objects, load self-contained HTML apps into them, and monitor their output via console logs. Each spawned app runs in its own isolated context and persists independently, enabling the agent to build and deploy spatial apps into the scene rather than managing everything within a single script. This component also enables inter-app communication as well as communication between different multiplayer instances of the same app.
**Security**: Most operations require `isMasterClient` to be `true` except for messaging. In multiplayer sessions the player who created the app is the master.
Access via the `app` property on a FigminObject.
```javascript
// Properties (read-only)
obj.app.isMasterClient // boolean - whether this app belongs to the master client
// showConsole(doShow)
// Shows or hides this app's log console.
// The console MUST be visible before calling getConsoleLogs() or clearConsoleLogs().
// Requires isMasterClient to be true.
obj.app.showConsole(true);
// getConsoleLogs(logCount?, callback?)
// Retrieves the latest log entries from this app's console.
// Returns Promise if no callback. Resolves to null if not master client.
// Requires isMasterClient to be true and console to be visible.
obj.app.showConsole(true);
const logs = await obj.app.getConsoleLogs(10);
console.log(logs);
// clearConsoleLogs()
// Clears all log entries from this app's console.
// Requires isMasterClient to be true and console to be visible.
obj.app.clearConsoleLogs();
// reload()
// Reloads this app, refreshing its current page content.
// Requires isMasterClient to be true.
obj.app.reload();
// loadHTML(html)
// Loads an HTML string into this app, replacing its current content.
// Base64-encoded internally — double quotes and special chars are supported.
// Can include inline