Figmin XR Scripting API

getLocalPlayer

Get the PlayerInfo for the local player.

Use this to access the local player bodyparts (e.g., pass to getPlayerBodypart).

getPlayers

Get a snapshot of all players currently present in the session as an array of PlayerInfo objects (includes the local player).

This is a snapshot at call time; listen for changes via onPlayerConnected and onPlayerDisconnected.

getPlayerById

Get a PlayerInfo by numeric ID.

Useful when you have only a player ID (e.g., from input connect) and want to read properties like displayName.

getPlayerBodypart

Get the FigminObject representing a specific player's body part (head or hands). Contains a bodypart component at obj.bodypart and a read-only transform.

Returns a FigminObject immediately; the lookup completes asynchronously. Subscribe to onStart and onError on the returned object to determine the outcome.

Data is only valid if the bodypart is tracked, consult the bodypart component for more information.

// We'll attach a spotlight to the player's right hand, and turn it on and off as tracking state changes
// Get the local player's right hand
const localPlayer = figmin.getLocalPlayer();
const rightHand = figmin.getPlayerBodypart(localPlayer, figmin.BodypartType.RIGHT_HAND); 

// We must wait until the FigminObject starts 
rightHand.onStart((handObj) => {
  // The light will be rotated in the direction of the hand ray
  const lightLocalRotation = handObj.bodypart.rayLocalRotation;
  const lightRange = 5;
  // Attach a light component to the hand FigminObject, its range depends on whether it’s tracked
  handObj.addComponent(figmin.ComponentType.LIGHT, {
    type: figmin.lights.LightType.SPOT,
    range: handObj.bodypart.tracked ? lightRange : 0,
    spotlightAngle: 25,
    rotation: lightLocalRotation,
    shadowType: figmin.lights.ShadowType.SOFT
  });
  // When tracking changes, the light turns on and off
  handObj.bodypart.onTrackingChanged((obj, isTracked) => {
    // We use the light range to toggle. 
    // We check if light exists because it can be removed by another script
    if (obj.light) {
      obj.light.range = isTracked? lightRange : 0;
    }
  });
});
// If the system can't find right hand an error will be reported
rightHand.onError((handObj) => {
  console.warn("Couldn't find right hand FigminObject");
});

onPlayerConnected

Register (or clear) a callback fired when a player joins the session.

Pass a function to receive a PlayerInfo for the newly connected player. Pass null to clear the callback. Fires only for subsequent joins; use getPlayers for the current snapshot.

onPlayerDisconnected

Register (or clear) a callback fired when a player leaves the session.

Pass a function to receive a PlayerInfo for the player that disconnected. Pass null to clear the callback.

createObject

Create a new object in the scene.

Returns a FigminObject immediately but UNINITIALIZED, objects load asynchronously, use obj.onStart to detect when the object becomes ready.

Consult the Creating Objects section for more details.

 // Create a text object that is owned by the scene (will persist after this script ends)
const obj = figmin.createObject(figmin.ObjectType.TEXT3D, {
    position: { x: 0, y: 1, z: 0 },
    rotation: { x: 0, y: 180, z: 0 },
    colliderType: figmin.ColliderType.APPROXIMATE,
    text: "Hello world",
    scenePersistent: true
});

findObjectByName

Find a scene object by name and begin tracking it. Object names are returned by various API calls.

Returns a FigminObject handle immediately but UNINITIALIZED; the lookup completes asynchronously. Listen for obj.onStart to determine whether the object was found, and obj.onError if it wasn't.

Found objects are not owned by the script and will not be destroyed automatically when execution ends.

setUpdateFunction

Registers a callback that runs once per engine frame.

Synchronized with the main Figmin XR rendering loop (higher framerate than the embedded web-view). Recommended for animations, object updates, physics logic, and other time-based calculations. Only one update function can be active at a time; calling this again replaces the previous one.

figmin.setUpdateFunction((deltaTime) => {
// Update logic here
    obj.transform.rotation.y += 90 * deltaTime;
});

getWindowSpawnPosition

Calculates a position offset from the app window’s edges—handy for spawning objects near or around the user’s view.

Use with figmin.getWindow().transform.rotation if you want the spawned object to face the same direction as the window.

getCamera

Gets the player camera object. The returned FigminObject exposes a read-only transform and an intrinsics property.

The camera cannot be destroyed and does not support attaching components.

getApp

Get the FigminObject that represents this spatial app container.

The returned object is fully mutable: you can move/rotate/scale it, attach components, and even destroy it (which ends the script).

getWindow

Get the FigminObject that represents the app’s window surface.

The window object exposes its transform.size, which reflects the visible 2D surface area of the app (excluding system buttons). Its transform is read-only.

The window’s position/rotation may differ from the app’s transform when special modes are active (e.g., figmin.AppMode.HUD, figmin.AppMode.OBJECT).

This is info is available to non-spatial apps, in contrast to getApp()

getScene

Get the scene component representing the active scene.

Unlike normal FigminObjects, the scene has no transform. It exposes global lighting, floor, boundary, and shadow settings, and includes a status component for lifecycle events. The scene cannot be destroyed or re-created by user code.

isSpatialApp

Returns whether the app is running as a spatial app (deployed in the scene) rather than in the built-in web browser.

Use this check to gate features or trigger a “Deploy as spatial app” flow via figmin.requireSpatialApp.

requireSpatialApp

Ensures the app is running as a spatial app.

If not already spatial, this prompts the user to deploy the app into the scene and aborts further execution in the browser context.

// If you require spatial app features early out rather than letting the system do it for you
if (!figmin.isSpatialApp()) {
    figmin.requireSpatialApp();
    return;
}

getVersion

Returns the Figmin XR runtime version (host application)

isMasterClient

Returns whether this app instance is the master client in a multiplayer session.

Only the master client may perform most state-changing operations; non-master calls are ignored.

// Good practice: early-out on non-master clients to avoid no-ops
if (!figmin.isMasterClient()) {
    return;
}

isMultiplayer

Returns whether this app is in a multiplayer session.

saveState

Saves the current state of all supported HTML elements that include a figmin-persist-state attribute (its value must be a unique key). The data is stored with the app so it can persist across sessions.

The app itself must be saved to disk (in the scene or as an object) for the data to persist. In other words, this doesn't grant explicit file system access.

Note that the data does persist temporarily if the spatial app's is reloaded. (e.g: user presses "Reload Page")

// Earlier in the HTML (tag supported elements with a unique key):
<input type="text"   id="textInput"   figmin-persist-state="persistKey1" value="Hello World" />
<input type="number" id="numberInput" figmin-persist-state="persistKey2" value="42" />

// Saves all elements marked with `figmin-persist-state`, plus a custom string
figmin.saveState("custom data");

loadState

Restores the state of all supported HTML elements marked with the figmin-persist-state attribute.

Optionally accepts a callback to to be notified when loading occurs and to receive user-defined data previously saved via figmin.saveState.

// Restore all persisted elements; receive optional user-defined data (if any)
figmin.loadState((userData) => {
    console.log(userData);
});

useNegativeZForward

Sets the coordinate system so that -Z is considered the forward direction.

This is typically needed when integrating WebGL-based frameworks like Three.js. Call only if you have a concrete reason—this path isn’t thoroughly tested.

// Configuring Z-forward must be done during FigminPreload
document.addEventListener("FigminPreload", () => figmin.useNegativeZForward(true));

setRenderMode

Sets the rendering mode for your app, including stereoscopic 3D modes such as side-by-side (SBS) and over-under (OU).

If you use stereo you must display your content in stereo, this function will render each side to the approriate camera eye.

setAppMode

Configure the display mode of the spatial app window.

setObjectModeBounds

Define the interaction bounding box size for the app window when in figmin.AppMode.OBJECT.

By default, the window’s surface size is used as its bounding box, which may not match the shape of the 3D content rendered inside the WebView.

getObjectModeBounds

Get the interaction bounding box previously set with figmin.setObjectModeBounds.

Returns the local bounding box size (at unit scale) or null if no custom bounds have been defined.

setTransparentBackground

Enables or disables transparent background mode for your spatial app.

When enabled, the HTML background becomes fully transparent so the 3D scene behind it shows through—useful for floating UI, holographic panels, or HUDs.

print

Displays a transient text message in front of the local user.

Use for short notifications; the message fades automatically after a brief duration.

showNavigationArrow

Display a temporary navigation arrow that moves from one point in space to another.

The arrow animates from startPosition toward endPosition in world space—useful for directing the user’s attention to a specific location (e.g., when creating a new object).

// after creating obj we show where it spawned
figmin.showNavigationArrow(figmin.getWindow().transform.position, obj.transform.position);

debugDraw

Draw a temporary curve in 3D space for a single frame to the local user.

The curve is defined by the ordered list of world-space points. Rendering lasts only for the current frame; the curve is automatically erased on the next frame.

showLogConsole

Shows the developer log console.

This function is useful when developing in non standard app modes, such as AppMode.OBJECT, where the UI to manually open the developer logs is unavailable.

enableInputConnect

Enable motion-controller input connection for a spatial app.

// Input example
let isConnected = false;

document.addEventListener("FigminReady", () => {
  // Show a connect icon and request A/B button inputs
  figmin.enableInputConnect(
    "Connection test",
    [figmin.InputCode.A, figmin.InputCode.B],
    onConnectionChanged // optional callback
  );

  // Per-frame polling of inputs
  figmin.setUpdateFunction(update);
});

function onConnectionChanged(connected, playerId) {
  isConnected = connected;
  // (optional) console.log(`Input ${connected ? "connected" : "disconnected"} for player ${playerId}`);
}

function update(deltaTime) {
  if (!isConnected) return;

  if (figmin.getInputDown(figmin.InputCode.A)) {
    console.log("A pressed");
  }
  if (figmin.getInputDown(figmin.InputCode.B)) {
    console.log("B pressed");
  }
}

disableInputConnect

Disable motion-controller input connection for the app.

Removes the connect icon from the app window (or the target object if one was specified) and stops delivering controller inputs to the app.

disconnectFromInput

Request disconnection from an active input connection.

Equivalent to the user pressing the “Disconnect” button in the connection UI.

getInput

Get the current value of a connected input as a float.

Analog controls (e.g., triggers, thumbstick axes) return values in [0..1]. Digital controls (buttons) return 0 when not pressed and 1 when pressed.

getInputDown

Check if a connected input button was pressed on this frame.

Returns true only on the first frame the input transitions from not pressed to pressed. Useful for detecting discrete button presses.

getInputUp

Check if a connected input button was released on this frame.

Returns true only on the first frame the input transitions from pressed to not pressed. Useful for detecting discrete button releases.

raycast

Cast a ray into the world and invoke a callback with the first hit (if any).

Provide a world-space origin and direction. Optionally filter layers, set a max distance, and request object lookup data.

The callback is always invoked: it receives a single hit info when something is struck, or null if nothing is hit.

figmin.raycast(
    {
        origin: { x: 0, y: 1, z: 0 },
        direction: { x: 0, y: 0, z: 1 } 
    },
    (hit) => {
        if (!hit) return;
        console.log("raycast hit at", hit.point, "normal:", hit.normal, "distance:", 
            hit.distance, "layer:", hit.layer);
    }
);

raycastAll

Cast a ray into the world and invoke a callback with all hits along the ray (if any).

The callback is always invoked: it receives an array of hit info when something is struck, or null if nothing is hit.

raycastSphere

Cast a swept sphere into the world and invoke a callback with the first hit (if any).

Provide a world-space origin, direction, and sphere radius. Optionally filter layers, set a max distance, and request object lookup data.

The callback is always invoked: it receives a single hit info when something is struck, or null if nothing is hit.

raycastSphereAll

Cast a swept sphere into the world and invoke a callback with all hits along the ray (if any).

The callback is always invoked: it receives an array of hit info when something is struck, or null if nothing is hit.

sketch.stroke

Create a brush stroke object for use with figminObj.sketch.setBrushStrokes().

This helper packages a brush reference, color, max size, and an array of control points (created with figmin.sketch.point()) into the compact format the sketch component expects.

The maximum pressure determines the maximum width of the brush stroke in meters, it is modulated by each control point pressure.

// Use a brush object from the catalog
const brush = figmin.brushes.MetallicTube;

// Two control points for a straight line in the object's local space 
const p0 = figmin.sketch.point(
    { x: 0, y: 0,   z: 0 },
    { x: 0, y: 0,   z: 0 },
    brush.minPressure // We use the minimum pressure of this brush to start
);

const p1 = figmin.sketch.point(
    { x: 0, y: 0.2, z: 0 },   // 20 cm above
    { x: 0, y: 0,   z: 0 },
    1 // Final point uses the maximum pressure
);

// Create the stroke with the brush object 
const stroke = figmin.sketch.stroke(
    brush,
    "#40E0D0",
    0.05,  // max size; actual size modulated per-point by pressure
    [p0, p1]
);

// Apply to a Sketch component on your FigminObject
obj.sketch.setBrushStrokes([stroke]);

sketch.point

Create a control point object for a brush stroke made with figmin.sketch.stroke().

A control point contains a local-space position, rotation, and pressure, representing the state of the motion controller at that moment in the stroke. If rotation or pressure are omitted, defaults are used (identity rotation, pressure = 1).

sketch.getBrushById

Look up a brush object in the Brush Catalog by its id.

You’ll need this function because figminObj.sketch.getBrushStrokes() returns only brush IDs, not the full brush objects. This helper converts an ID back into a catalog entry.

Note: old sketches may contain deprecated brushes that cannot be resolved. In that case this function returns null. You may still create strokes with deprecated brushes by passing the raw ID string directly.

sketch.translateStroke

Translates a stroke by the given offset vector, this operation mutates the positions in place

Use this to reposition an existing stroke in sketch space (all coordinates are relative to the sketch), while preserving point rotations and pressure values.

// Move an existing stroke up by 0.2m
figmin.sketch.translateStroke(aStroke, { x: 0, y: 0.2, z: 0 });

sketch.rotateStroke

Rotates a stroke by the given rotation (Euler or Quaternion). Positions are rotated around a pivot (local origin if none is provided). This operation mutates the stroke in place.

Use this to reorient an existing stroke in sketch space. If a point contains an orientation quaternion r, it is composed as r' = qRot * r.

// Rotate a stroke 90° around Z, about the local origin (no pivot provided)
figmin.sketch.rotateStroke(aStroke, 
    { x: 0, y: 0, z: 90 }   // Euler degrees but you can pass a quaternion as well
);

sketch.scaleStroke

Scales a stroke by either a uniform factor (number) or a non-uniform vector {x,y,z}. Point positions are scaled; orientations are preserved. Thickness behavior depends on the type of scale (see Notes). This operation mutates the stroke in place.

// 1) Uniform scale: enlarge by 1.5× about origin (thickness scales too)
figmin.sketch.scaleStroke(aStroke, 1.5);

// 2) Non-uniform scale: flatten along Z about origin (thickness unchanged)
figmin.sketch.scaleStroke(aStroke, { x: 1, y: 1, z: 0.5 });

sketch.calculateStrokeCenter

Computes the axis-aligned bounding-box center of a stroke’s points and returns it as {x,y,z}.

Use this center as a convenient pivot for transforms like rotateStroke or scaleStroke when you want an operation “about the stroke itself.”

// Rotate a stroke 90° around Z, about its own center (AABB center)
const pivot = figmin.sketch.calculateStrokeCenter(original);
const rotated = figmin.sketch.rotateStroke(
    original,
    { x: 0, y: 0, z: 90 },  // Euler degrees
    pivot
);

// Scale the stroke down uniformly 0.8× about its center
const scaled = figmin.sketch.scaleStroke(original, 0.8, pivot);

sketch.cloneStroke

Creates and returns a deep copy of a stroke. The clone is safe to modify without affecting the original.

// Make an independent copy before editing
const copy = figmin.sketch.cloneStroke(original);

sketch.boxStroke

Creates a single-stroke, axis-aligned box wireframe centered at the origin. The path visits all 12 edges (re-walking where needed) so the stroke remains continuous with no jumps. You can also create rectangles by setting one dimension to 0 (e.g., depth = 0).

// Create a 1m × 0.5m × 0.25m box wireframe
const stroke = figmin.sketch.boxStroke(
    figmin.brushes.Wire, "#4CAF50", 0.004, 1.0, 0.5, 0.25);

sketch.capsuleStroke

Creates a single-stroke capsule (two hemispherical caps plus a cylindrical side), Y-up and centered at the origin. The stroke path is continuous, tracing the profile without spatial jumps. Total height is length + 2 * radius.

// A 0.12 radius capsule with 0.3 length and 2 side loops
const stroke = figmin.sketch.capsuleStroke(
    figmin.brushes.ToonHull, "#4CAF50", 0.001, 0.12, 0.30, 2);

sketch.circleStroke

Creates a single-stroke circle in the XY plane (normal +Z), centered at the origin.
For ellipses, create a circle and then apply scaleStroke with non-uniform factors.

// Circle with radius 0.25
const stroke = figmin.sketch.circleStroke(
    figmin.brushes.MatteHull, "#4CAF50", 0.004, 0.25);

sketch.coneStroke

Creates a single-stroke cone with the tip at +Y and the base at −Y. The path spirals from tip to base for a continuous stroke; loops controls how many full turns it makes.

// A cone: radius 0.2, height 0.4, 1.25 loops from tip to base
const stroke = figmin.sketch.coneStroke(
    figmin.brushes.ToonHull, "#4CAF50", 0.004, 0.2, 0.4, 1.25);

sketch.cylinderStroke

Creates a single-stroke helical path over a cylinder (optionally tapered), centered at the origin with poles on +Y (top) and −Y (bottom). The path starts at the top rim, wraps loops times, and ends at the bottom rim.

// Helix with 2.5 loops over a tapered cylinder (top 0.15 → bottom 0.25, height 0.6)
const stroke = figmin.sketch.cylinderStroke(
    figmin.brushes.ShinyHull, "#4CAF50", 0.004, 0.15, 0.25, 0.6, 2.5);

sketch.rectangleStroke

Creates a single-stroke rectangle in the XY plane (normal +Z), centered at the origin.

// Rectangle 1.2 × 0.6
const stroke = figmin.sketch.rectangleStroke(
    figmin.brushes.ToonHull, "#4CAF50", 0.004, 1.2, 0.6);

sketch.roundedBoxStroke

Creates a brush stroke that approximates a rounded box using a superquadric point distribution, smaller exponents round more aggressively; larger exponents approach a sharp-edged box. Points are axis-aligned and centered at the origin.

Designed for HULL-category brushes (e.g., ToonHull, DiamondHull), non-HULL brushes may not produce a proper shape..

// Rounded box (hull brush), mildly rounded corners
const stroke = figmin.sketch.roundedBoxStroke(
    figmin.brushes.ToonHull, "#4CAF50", 0.004, 1.0, 0.6, 0.4, 0.35, 0.35);

sketch.roundedRectangleStroke

Creates a single-stroke rounded rectangle in the XY plane (normal +Z), centered at the origin. roundness is a unitless corner fillet factor from 0 (sharp 90°) to 1 (maximum rounding without overlap).

// Rounded rectangle 1.0 × 0.6 with 40% corner roundness
const stroke = figmin.sketch.roundedRectangleStroke(
    figmin.brushes.SmoothHull, "#4CAF50", 0.004, 1.0, 0.6, 0.4);

sketch.sphereStroke

Creates a single-stroke sphere lattice path centered at the origin. The curve weaves around the sphere (mix of latitude/longitude arcs) as one continuous stroke.

// Sphere lattice, radius 0.35
const stroke = figmin.sketch.sphereStroke(
    figmin.brushes.MetallicSmoothHull, "#4CAF50", 0.004, 0.35);

ObjectType

The various object types found in FigminObjects.

Each FigminObject type contains a specific a built-in component that can't be removed.

Most object types can be used by figmin.createObject with the exception of BODYPART which is only found in objects returned by figmin.getPlayerBodypart.

ComponentType

Valid component types used by FigminObject.addComponent to attach components at runtime.

Use these to extend an object’s capabilities beyond its built-in component.

ObjectState

Lifecycle states reported via a FigminObject’s status component (obj.status.state).

InteractionState

This state controls whether a FigminObject allows user interaction or not.

Scripts can always interact with objects no matter the interaction state, this is a user facing setting only.

ColliderType

Collider shapes assignable to an object’s collider component (collider.type).

The collider is the physical shape of the model.

BodypartType

Valid player body part types used to address tracked anatomy (head and hands).

Consumed by getPlayerBodypart and exposed on bodypart components via bodypart.bodypartType.

Layers

Raycastable layers used to filter what your ray tests can hit.

Consumed by raycast, raycastAll, raycastSphere, and raycastSphereAll.

RenderMode

Valid rendering modes used by figmin.setRenderMode.

Controls whether the app renders as standard 2D UI or in stereoscopic 3D layouts.

AppMode

Different modes the app can be set to via figmin.setAppMode.

Controls how the app window is presented in the scene.

MotionEndBehavior

Controls what happens when a motion path reaches its end, used by the motion component.

If not specified in the component’s parameters, the default is LOOP.

InputCode

The different inputs that can be requested via figmin.enableInputConnect and queried with the getInput, getInputDown, and getInputUp APIs.

Request only the inputs you intend to read to keep processing lightweight.

InputType

The type of input mechanism a bodypart is using.

physics.CollisionDetectionMode

How the physics engine detects collisions for a body (see physics component).

Choose a mode based on speed/accuracy needs vs. performance. Default in physics params: CONTINUOUS.

physics.ForceFieldType

The shape of the force field applied by the physics component.

Controls how acceleration is distributed in space.

physics.ForceFieldForceType

Force falloff model for a physics component force field.

Determines how acceleration changes with distance.

physics.ForceFieldDirection

Direction of a planar (FLAT) force field on the physics component.

Applied in the object’s local coordinate system.

physics.Combine

How two physics materials combine their friction/bounce, used by the physicsMaterial component.

The effective contact uses both colliders’ materials and the selected combine modes.

lights.LightType

Types of lights supported by the light component.

Select the light’s emission model. Default in light: POINT.

lights.ShadowType

Shadow rendering modes for the light component.

Controls if/how the light casts shadows. Default in light: NONE.

lights.LightEffect

Special visual effects for the light component.

Applies time-based or reactive behaviors. Default: NONE.

lights.LightProjection

“Cookie” projection patterns for the light component.

Projects a texture-like pattern through the light. Default: NONE.

lights.SceneShadowMode

Global shadow override for the active scene (via getScene → scene.shadowMode).

Forces shadows on/off or defers to the system default. Default: DEFAULT.