Figmin XR Scripting API

https://www.figmin.com/api/
Admin
Comprehensive reference for the Figmin XR Scripting API, an award-winning spatial computing platform...
Tokens:193,750
Snippets:2,966
Trust Score:6.2
Update:3 months ago
Show doc for...
Tokens:
Raw
### AudioClip Example Usage

Source: https://www.figmin.com/api/documentation.html

Example demonstrating how to load, configure, and control an AudioClip.

```APIDOC
```javascript
const engine = obj.audio.loadClip("engine", "https://example.com/engine.ogg");

engine.spatialize = true;
engine.loop = true;
engine.volume = 0.7;
engine.dopplerLevel = 1.0;

engine.play();

// Later...
engine.stop();
```
```

--------------------------------

### Figmin XR Quick Start Template

Source: https://www.figmin.com/api/SKILL.md

A basic HTML and JavaScript template for a Figmin XR spatial application. It includes setup for event listeners, checks for spatial app context, and demonstrates object creation triggered by a button click.

```html
<!DOCTYPE html>
<html>
<head>
    <meta name="figmin">
    <title>My Spatial App</title>
</head>
<body>
    <button id="spawn">Spawn Object</button>
    <script>
        document.addEventListener("FigminReady", init);

        function init() {
            // Require spatial app context
            if (!figmin.isSpatialApp()) {
                figmin.requireSpatialApp();
                return;
            }

            // Only master client creates objects in multiplayer
            if (!figmin.isMasterClient()) return;

            document.getElementById("spawn").addEventListener("click", () => {
                const obj = figmin.createObject(figmin.ObjectType.TEXT3D, {
                    position: figmin.getWindowSpawnPosition(0.3, "right"),
                    rotation: figmin.getWindow().transform.rotation,  // TEXT3D faces user directly
                    text: "Hello XR!",
                    targetSize: 0.15
                });

                obj.onStart(() => {
                    console.log("Object ready:", obj.name);
                    // Per-object update loop: obj.onUpdate((dt) => { ... });
                });
            });

            // Optional: game loop
            figmin.setUpdateFunction((deltaTime) => {
                // Called every frame
            });
        }
    </script>
</body>
</html>
```

--------------------------------

### Start Python HTTP Server

Source: https://www.figmin.com/api/SKILL.md

Use this command to start Python's built-in HTTP server in your application folder for local web serving.

```bash
python -m http.server 8000
```

--------------------------------

### onStart(callback)

Source: https://www.figmin.com/api/documentation.html

Registers a one-time callback invoked when the object has started and is safe to use. This is the recommended method for initializing objects.

```APIDOC
## onStart(callback)

### Description
Registers a one-time callback invoked when the object has started and is safe to use. Always use this to safely initialize your objects.

### Method
Not applicable (SDK method)

### Endpoint
None

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
Param | Type | Required | Description
---|---|---|---
callback | function(FigminObject) | Yes | Called when the object starts

### Response
#### Success Response (200)
void

#### Response Example
None

### Important
An object starts when it's status.`state` reaches READY. If the object is already READY the callback runs on the next frame. This is a very important callback, generally speaking you should not operate on FigminObjects until after they start.

### Request Example
```javascript
const obj = figmin.createObject( figmin.ObjectType.TEXT3D, {
        position: figmin.getWindowSpawnPosition(0.1, "right"),
        text: "Physics!"
} );
// Wait till the object Starts before adding the physics component
obj.onStart((o) => {
    // The object has started and it's safe to use, add a physics component
    o.addComponent(figmin.ComponentType.PHYSICS, {
        mass: 1,
        drag: 0
    });
});
```
```

--------------------------------

### Load and Configure AudioClip

Source: https://www.figmin.com/api/documentation.html

Load an audio clip, configure its spatialization, looping, and volume, and then start playback. Use `stop()` later to halt playback.

```javascript
const engine = obj.audio.loadClip("engine", "https://example.com/engine.ogg");

engine.spatialize = true;
engine.loop = true;
engine.volume = 0.7;
engine.dopplerLevel = 1.0;

engine.play();

// Later...
engine.stop();
```

--------------------------------

### Initialize and Place 3D Model

Source: https://www.figmin.com/api/privacy/privacy/terms/terms/privacy/terms/learn.html

This example demonstrates how to load a 3D model and position it in front of the user's camera using the Figmin XR API.

```APIDOC
## Initialize and Place 3D Model

### Description
This code snippet shows how to load a 3D model and place it in front of the user within the Figmin XR environment. It utilizes the `figmin.createObject` function to instantiate a model and an `onStart` callback to handle its placement and orientation relative to the camera.

### Method
```javascript
function init() {
  // Load a 3D model and place it in front of the user
  const model = figmin.createObject(figmin.ObjectType.MODEL3D, {
    url: "https://example.com/spaceship.glb",
    targetSize: 0.5
  });

  model.onStart((obj) => {
    // Position it 1.5m in front of the camera
    const cam = figmin.getCamera();
    const p = cam.transform.position;
    const fwd = cam.transform.forward;
    const DIST = 1.5;

    obj.transform.position = {
      x: p.x + DIST * fwd.x,
      y: p.y + DIST * fwd.y,
      z: p.z + DIST * fwd.z,
    };
    obj.transform.rotation = cam.transform.rotation;
  });
}
document.addEventListener("FigminReady", init);
```

### Parameters
#### Request Body
- **figmin.createObject**: Creates a new object in the scene.
  - **figmin.ObjectType.MODEL3D** (enum): Specifies the type of object to create as a 3D model.
  - **options** (object): Configuration options for the object.
    - **url** (string): The URL of the 3D model file (e.g., GLB format).
    - **targetSize** (number): The desired size of the model.
- **model.onStart**: Callback function executed when the model has started.
  - **obj** (object): The created 3D model object.
    - **transform** (object): The transformation properties of the object.
      - **position** (object): The position of the object (x, y, z).
      - **rotation** (object): The rotation of the object.
- **figmin.getCamera**: Retrieves the main camera object.
  - **transform** (object): The transformation properties of the camera.
    - **position** (object): The position of the camera (x, y, z).
    - **forward** (object): The forward direction vector of the camera (x, y, z).

### Event Listener
- **FigminReady**: This event is fired when the Figmin XR environment is ready to accept commands.
```

--------------------------------

### Cycle Through Model Animations

Source: https://www.figmin.com/api/documentation.html

This example demonstrates how to play all animations of a 3D model sequentially. Ensure the model is loaded before operating on its animations.

```javascript
// This example makes a 3d model cycle through all its animations
const OBJECT_URL = "INSERT 3D MODEL URL";
let obj = figmin.createObject(figmin.ObjectType.MODEL3D, {
            url: OBJECT_URL,
            position: figmin.getWindowSpawnPosition(0.2, "right"),
            rotation: figmin.getWindow().transform.rotation,
            targetSize: 0.163 //This will be the height in meters of the character
        });

// Wait till it starts before operating on the model3d, this ensures the object has loaded
obj.onStart(() => {
    const names = obj.model3d.getAnimationNames(); // An array with all the animation names
    if (!names || names.length === 0) return; // If it has no animations there's nothing to do
    let i = 0; // The current animation index

    // This function plays all the animations of the object one after the other.
    function cycleAnimation() {
        // stop quietly if the object was deleted
        if (obj.status.state === figmin.ObjectState.DESTROYED) return;

        const name = names[i]; // The current animation name
        i = (i + 1) % names.length; // Cycle the animation index for the next run

        // play the animation once (no loop)
        obj.model3d.play(name, false);

        // chain to the next animation after this one finishes
        const durationSeconds = obj.model3d.getAnimationDuration(name);
        setTimeout(cycleAnimation, Math.round(durationSeconds * 1000));
    }

    // Cycle through all the animations
    cycleAnimation();
});
```

--------------------------------

### Initialize FigminObject on Start

Source: https://www.figmin.com/api/documentation.html

Safely initialize your FigminObjects by using this callback, which is invoked once the object has started and is ready for use. The object is guaranteed to be safe to operate on after this callback.

```javascript
const obj = figmin.createObject( figmin.ObjectType.TEXT3D, {
        position: figmin.getWindowSpawnPosition(0.1, "right"),
        text: "Physics!"
} );
// Wait till the object Starts before adding the physics component
obj.onStart((o) => {
    // The object has started and it's safe to use, add a physics component
    o.addComponent(figmin.ComponentType.PHYSICS, {
        mass: 1,
        drag: 0
    });
});
```

--------------------------------

### Show Navigation Arrow with figmin.showNavigationArrow

Source: https://www.figmin.com/api/documentation.html

Use figmin.showNavigationArrow to display a temporary arrow guiding the user from a start position to an end position. This is useful for directing attention, for example, after creating a new object.

```javascript
figmin.showNavigationArrow(figmin.getWindow().transform.position, obj.transform.position);
```

--------------------------------

### getAnimationDuration

Source: https://www.figmin.com/api/documentation.html

Gets the duration in seconds of a specific animation clip at a speed of 1. Returns 0 if the clip is not found. Requires the object to have started.

```APIDOC
## getAnimationDuration(name)

### Description
Get the duration (seconds) of an animation clip at speed = 1 (requires the object to have **started**). Returns `0` if the clip is not found.

### Parameters
#### name (string, Yes)
Animation clip name (case-insensitive).

### Returns
number
```

--------------------------------

### Get Node Names (Promise Style)

Source: https://www.figmin.com/api/documentation.html

Retrieves all node names from the 3D model using a Promise. Ensure the object has started before calling.

```javascript
const names = await obj.model3d.getNodeNames();
console.log(names);
```

--------------------------------

### Get Node Names (Callback Style)

Source: https://www.figmin.com/api/documentation.html

Retrieves all node names from the 3D model using a callback function. Ensure the object has started before calling.

```javascript
obj.model3d.getNodeNames((names) => {
    console.log(names);
});
```

--------------------------------

### Audio Component Initialization and Clip Playback

Source: https://www.figmin.com/api/documentation.html

Demonstrates how to add the audio component to a FigminObject, load an audio clip, configure its spatial properties, loop, volume, and then play it.

```APIDOC
## Component: audio
The audio component adds spatial audio playback to a FigminObject.
This component may be added at runtime via `FigminObject.addComponent` using `figmin.ComponentType.AUDIO`. Access it through the `audio` property on a FigminObject.
The `audio component` manages a collection of named `AudioClip` objects. You load clips by name, then control each clip individually.
**Notes:  
** - Supported formats: `.ogg` (recommended), `.wav`, `.mp3`.  
- Audio does not use addComponent creation parameters. Clips are configured individually after loading.  
- Each loaded clip has its own playback state and spatial settings. 
```
obj.addComponent(figmin.ComponentType.AUDIO);

const engine = obj.audio.loadClip("engine", "https://example.com/engine.ogg");
engine.spatialize = true;
engine.loop = true;
engine.volume = 0.7;
engine.play();
```
```

--------------------------------

### createObject

Source: https://www.figmin.com/api/documentation.html

Creates a new object in the scene. The object is returned immediately but uninitialized; use `obj.onStart` to detect when it's ready. This function requires the master client.

```APIDOC
## createObject

### Description
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.

### Signature
`figmin.createObject(type, params?) => FigminObject`

### Parameters
- **type** (`figmin.ObjectType`) - Required - The type of object to create (e.g., `TEXT3D`, `MODEL3D`, `SKETCH`, `IMAGE`, `PORTAL`).
- **params** (`object`) - Optional - Initial properties for the new object. Common fields include:
  - `position`: `{x,y,z}` - world-space position.
  - `rotation`: `{x,y,z}` - Euler degrees.
  - `targetSize`: `number` - uniform size in meters; scales the object so its largest dimension matches this value.
  - `colliderType`: `figmin.ColliderType` - defaults to `BOX`.
  - `scenePersistent`: `boolean` - keep the object after the app unloads/reloads. Default: `false`.

### Requirements
- Master client: Yes

### Request Example
```javascript
// 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
});
```
```

--------------------------------

### Initialize Figmin API on Ready

Source: https://www.figmin.com/api/SKILL.md

Listen for the FigminReady event to initialize your application. Ensures the API is ready before proceeding. Includes a check to require a spatial app context.

```javascript
document.addEventListener("FigminReady", init);

function init() {
    if (!figmin.isSpatialApp()) {
        figmin.requireSpatialApp();
        return;
    }
    // Your app logic
}
```

--------------------------------

### Create and Load Content into a Spatial App

Source: https://www.figmin.com/api/SKILL.md

Demonstrates creating a new spatial app, loading custom HTML content, and optionally loading a URL. It also shows how to enable and retrieve console logs from the app.

```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(`<html>
      <body style="background:#1a1a2e;color:#eee;">
        <h1>Hello from Figmin XR</h1>
      </body>
    </html>`);

    // 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);
});
```

--------------------------------

### Player API: Get Body Part

Source: https://www.figmin.com/api/SKILL.md

Access specific body parts of a player, such as hands. The `onStart` callback can be used to get tracking data for the body part.

```javascript
const hand = figmin.getPlayerBodypart(player, figmin.BodypartType.RIGHT_HAND);
hand.onStart((handObj) => {
    // Use handObj.bodypart for tracking data
});
```

--------------------------------

### Create MODEL3D Object and Control Animations

Source: https://www.figmin.com/api/SKILL.md

Instantiate a 3D model from a GLB URL. Use `targetSize` to fit the model. Access and control animations via the `onStart` callback, which is available only after the object is initialized.

```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
});

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();
});
```

--------------------------------

### Get Scene Window and Positioning

Source: https://www.figmin.com/api/SKILL.md

Access the read-only transform of the application window, the mutable transform of the spatial app object, and the player's camera. Also, get spawn positions relative to the window.

```javascript
const window = figmin.getWindow();       // Read-only transform
const app = figmin.getAppObject();          // Mutable (spatial app only)
const camera = figmin.getCamera();       // Player camera

// Spawn position relative to window
const pos = figmin.getWindowSpawnPosition(0.3, "right");
// directions: "right", "left", "up", "down", "front", "back"
```

--------------------------------

### Create Text3D Object and Wait for Start

Source: https://www.figmin.com/api/documentation.html

Creates a 3D text object with specified position, rotation, text content, and colors. It's recommended to wait for the object's start callback before performing operations on it.

```javascript
let obj = figmin.createObject( figmin.ObjectType.TEXT3D, {
    position: figmin.getWindowSpawnPosition(0.1, "right"),
    rotation: figmin.getWindow().transform.rotation,
    text: "Hello",
    font: "caveat",
    frontColor: "#FFE6C6"
    sideColor: "#310E65"
});

obj.onStart((o) => {
    // add components, read sizes, etc.
});
```

--------------------------------

### hasAnimation

Source: https://www.figmin.com/api/documentation.html

Checks if an animation with the specified name exists. This requires the object to have started.

```APIDOC
## hasAnimation(name)

### Description
Check if an animation with the given name exists (requires the object to have **started**).

### Parameters
#### name (string, Yes)
Animation clip name (case-insensitive).

### Returns
boolean
```

--------------------------------

### Master Client Initialization and Late Joiner Handling

Source: https://www.figmin.com/api/SKILL.md

Implement an early exit for non-master clients during initialization. Use `onPeerReady` to detect late joiners and send them the current game state.

```javascript
function init() {
    // Early out pattern - check once at init
    if (!figmin.isMasterClient()) return;

    // Master-only logic
    createGameObjects();
    figmin.setUpdateFunction(gameLoop);

    // Handle late joiners
    var appObj = figmin.getAppObject();
    appObj.app.onPeerReady((playerId) => {
        var name = figmin.getPlayerById(playerId).displayName;
        console.log(name + " joined, sending state...");
        appObj.app.sendMessage({ action: "gameState", state: gameState }, figmin.MessageRecipient.player(playerId));
    });
}
```

--------------------------------

### getAnimationNames

Source: https://www.figmin.com/api/documentation.html

Retrieves a list of all available animation clip names. This requires the object to have started.

```APIDOC
## getAnimationNames()

### Description
Get a list of available animation clip names (requires the object to have **started**).

### Parameters
None

### Returns
string[]
```

--------------------------------

### Initialize and Place 3D Model in Figmin XR

Source: https://www.figmin.com/api/terms/privacy/terms/terms/privacy/privacy/privacy/index.html

This JavaScript snippet demonstrates how to load a 3D model and position it in front of the user's camera upon initialization. It utilizes the `figmin.createObject` and `figmin.getCamera` functions, and sets up an event listener for `FigminReady`.

```javascript
function init() {
  // Load a 3D model and place it in front of the user
  const model = figmin.createObject(figmin.ObjectType.MODEL3D, {
    url: "https://example.com/spaceship.glb",
    targetSize: 0.5
  });

  model.onStart((obj) => {
    // Position it 1.5m in front of the camera
    const cam = figmin.getCamera();
    const p = cam.transform.position;
    const fwd = cam.transform.forward;
    const DIST = 1.5;

    obj.transform.position = {
      x: p.x + DIST * fwd.x,
      y: p.p + DIST * fwd.y,
      z: p.z + DIST * fwd.z,
    };
    obj.transform.rotation = cam.transform.rotation;
  });
}
document.addEventListener("FigminReady", init);

```

--------------------------------

### Image URL Property

Source: https://www.figmin.com/api/SKILL.md

Set or get the URL for an image component. This property is read-write.

```javascript
obj.image.url   // string (read-write)
```

--------------------------------

### Initialize and Place a 3D Model

Source: https://www.figmin.com/api/privacy/terms/terms/privacy/terms/privacy/terms/index.html

Loads a 3D model from a URL and positions it in front of the user's camera. The model's position and rotation are set after it has started loading.

```javascript
function init() {
  // Load a 3D model and place it in front of the user
  const model = figmin.createObject(figmin.ObjectType.MODEL3D, {
    url: "https://example.com/spaceship.glb",
    targetSize: 0.5
  });

  model.onStart((obj) => {
    // Position it 1.5m in front of the camera
    const cam = figmin.getCamera();
    const p = cam.transform.position;
    const fwd = cam.transform.forward;
    const DIST = 1.5;

    obj.transform.position = {
      x: p.x + DIST * fwd.x,
      y: p.p + DIST * fwd.y,
      z: p.z + DIST * fwd.z,
    };
    obj.transform.rotation = cam.transform.rotation;
  });
}
document.addEventListener("FigminReady", init);
```

--------------------------------

### Get Body Parts

Source: https://www.figmin.com/api/SKILL.md

Retrieves a specific body part of a player and allows for tracking its state.

```APIDOC
## Get Body Parts

Retrieves a specific body part of a player and provides methods for tracking its state.

### Method
`figmin.getPlayerBodypart(player, bodypartType)`

### Parameters
- **player** (object) - Required - The `PlayerInfo` object of the player.
- **bodypartType** (enum) - Required - The type of body part to retrieve (e.g., `figmin.BodypartType.RIGHT_HAND`).

### Response
- Returns an object representing the body part. This object has an `onStart` method.

### Bodypart Tracking
- **`bodypart.onStart(callback)`**: Registers a callback function that is executed when tracking data for the body part becomes available. The callback receives an object containing `bodypart` for tracking data.

### BodypartType Enum
- `figmin.BodypartType.RIGHT_HAND`
- `figmin.BodypartType.LEFT_HAND`
- (Other body part types may be available)
```

--------------------------------

### sketch Component

Source: https://www.figmin.com/api/SKILL.md

Enables the use of procedural sketch system, allowing setting and getting brush strokes.

```APIDOC
## Component: sketch

### 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}`
```
Tokens:
Raw