Plugin SDK

Plugins extend ShapeBox beyond its built-in feature set. Unlike scene scripts (which are attached to a single object in one project), a plugin is a reusable, shareable module that can be installed across multiple projects and distributed to all ShapeBox users via the Marketplace.

What plugins can do

• Add new object types that appear in the Add menu
• Create custom Inspector panels with rich settings UI
• Hook into editor lifecycle events (object added, scene saved, published)
• Add toolbar buttons and context menu items
• Import assets from third-party services
• Connect scenes to external data sources and REST APIs
• Be published to the Marketplace and monetised

Plugin structure

A plugin is a JavaScript/TypeScript module that exports a default plugin definition object:

// my-plugin/index.ts
import type { PluginDefinition } from '@shapebox/plugin-sdk'

const plugin: PluginDefinition = {
  id: 'my-company.my-plugin',       // Unique reverse-domain ID
  name: 'My Plugin',
  version: '1.0.0',
  description: 'A short description of what this plugin does.',
  author: 'Your Name',

  // Called once when the plugin is installed into a project
  onInstall(context) {
    console.log('Plugin installed!')
  },

  // Called once per frame while the scene is running
  onUpdate(context, delta) {},

  // Register custom object types
  objects: [
    {
      type: 'my-company.bouncy-ball',
      displayName: 'Bouncy Ball',
      icon: 'circle',
      onAdd(scene, object) {
        object.physics.enabled = true
        object.physics.restitution = 0.9
      },
    },
  ],

  // Register custom Inspector panels
  panels: [
    {
      id: 'my-company.bouncy-settings',
      label: 'Bouncy Ball Settings',
      render({ object, ui }) {
        return ui.panel([
          ui.slider({ label: 'Bounciness', key: 'restitution', min: 0, max: 1 }),
          ui.slider({ label: 'Friction', key: 'friction', min: 0, max: 1 }),
          ui.toggle({ label: 'Always Active', key: 'alwaysActive' }),
        ])
      },
    },
  ],
}

export default plugin

Setting up a local development environment

1. Create a new plugin project

npm create @shapebox/plugin my-plugin
cd my-plugin
npm install

This scaffolds a TypeScript plugin project with hot-reload support.

2. Start the dev server

npm run dev

The local dev server starts at http://localhost:3456.

3. Connect to the editor

In the ShapeBox editor, open Plugins → Developer Mode and enter your local server URL. The plugin loads immediately and hot-reloads as you edit your code.

Building for production

npm run build

This produces a single dist/plugin.js bundle ready for upload.

Installing a local build in a project

1. In the editor, open Plugins → Upload Custom Plugin.
2. Select dist/plugin.js.
3. The plugin appears immediately in your scene.

Publishing to the Marketplace

Once your plugin is polished and ready to share:

1. Create a listing at marketplace.shapebox.io/publish.
2. Provide a name, description, screenshots, feature list, and pricing (free or paid).
3. Upload your dist/plugin.js bundle.
4. Submit for review — the ShapeBox team reviews plugins within 3 business days.

Published plugins are visible to all ShapeBox users directly inside the in-editor Marketplace.

Revenue share: Paid plugins use a 70/30 split — 70% goes to you, 30% to ShapeBox. Payments are processed monthly.

Plugin API reference

Install the SDK package locally for full type definitions and IDE autocomplete:

npm install --save-dev @shapebox/plugin-sdk

Key exported types: