API Overview

ShapeBox includes a built-in scripting API that lets you add custom logic, interactions, and third-party integrations to your scenes using JavaScript or TypeScript. Scripts are written directly inside the editor — no local development environment is needed.

The ShapeBox API is a feature of the ShapeBox platform, not a separate library to install. Scripts run inside your published scene in ShapeBox's cloud infrastructure.

Where scripts run

Scripts are attached to objects in your scene via Inspector → Scripts. They run:

In the browser of every visitor when they view your published scene.
In Preview mode inside the editor while you test.

Scripts are sandboxed, client-side modules that interact with your scene's objects, state, and events. They do not run on a backend server.

Writing your first script

Select an object in the editor.
In the Inspector, scroll to Scripts and click Add Script.
The built-in code editor opens. Write your logic:

import { onStart, onUpdate } from '@shapebox/api'

onStart(() => {
  console.log('Scene loaded!')
})

onUpdate((delta) => {
  // Rotate the object 45 degrees per second
  this.rotation.y += 45 * delta
})

Click Save — your script takes effect immediately in Preview mode.

Core API modules

Module	Description
`@shapebox/api`	Scene objects, lifecycle events, transforms, and state
`@shapebox/physics`	Apply forces, detect collisions, read velocity
`@shapebox/network`	Share real-time state between visitors in the same scene
`@shapebox/ui`	Create in-scene HTML overlays and interactive UI elements
`@shapebox/xr`	VR/AR controller input and spatial events
`@shapebox/media`	Control audio playback, video, and streaming sources

Lifecycle events

import { onStart, onUpdate, onDestroy } from '@shapebox/api'

onStart(() => { /* runs once when the scene loads */ })
onUpdate((delta) => { /* runs every frame; delta = seconds since last frame */ })
onDestroy(() => { /* runs when the scene is unloaded */ })

Responding to user interaction

import { on } from '@shapebox/api'

on('click', () => console.log('Object clicked!'))
on('hover', () => console.log('Object hovered!'))
on('collision', (other) => console.log('Collided with', other.name))

Controlling other objects

import { getObject, getObjects } from '@shapebox/api'

// Get a single object by name
const door = getObject('Door')
door.rotation.y = 90

// Get all objects with a specific tag
const lights = getObjects({ tag: 'spotlight' })
lights.forEach((l) => (l.visible = false))

Sharing state between visitors

The @shapebox/network module lets you synchronise data across all visitors viewing the scene at the same time:

import { syncState, onStateChange } from '@shapebox/network'

// Broadcast a value to all visitors
syncState('score', 42)

// React when any visitor changes the value
onStateChange('score', (value) => {
  console.log('New score:', value)
})

TypeScript support

All ShapeBox API modules ship with full TypeScript definitions. For IDE autocomplete when writing scripts in an external editor, install the types package:

npm install --save-dev @shapebox/types

This package provides type definitions only — it does not run any ShapeBox code and is not required to publish scenes. It is purely a developer-experience tool.

Next steps

Build reusable, shareable functionality with the Plugin SDK.
See practical scripting examples in the Guides section.