Volux Docs

Example: Your First Module

A complete, small feature module from registration to a working panel — every field mirrors the real API.

This page builds a small but complete feature module — pro.notes — in one file: it registers through the public API, contributes one command to the catalog, and adds a panel section that every box object's panel picks up. Every field, type, and import below is the real API surface; the module mirrors the same shapes Volux's own pilot modules (speaker, physics, particles) declare.

What you need before starting:

  • An editor page to register against (open any document in the Volux editor).
  • Ten minutes. No plugin internals required — the whole example runs against the four members of window.voluxPlugin.

Step 1: Register a minimal module

Everything starts with the module record. Open the console on an editor page and register the smallest module that exists:

const outcome = window.voluxPlugin.registerModule({
  id: 'pro.notes',
  dependsOn: ['core-builtin'],
  capabilities: {}
});

console.log(outcome.status); // "applied"

Three things happened: the registry stored the record (a duplicate id would have thrown), the kernel classified it against the boot activation — core-builtin is always registered, so the module qualifies — and its (empty) feed slice was applied to the realms. The returned outcome is the contract: applied with the applied slice, absent with a reason and blocker, or pre-activation when the boot has not run yet. Always inspect it.

Step 2: The complete module

The full module is a source file that rides the Volux build graph — its imports (@mui/material, volux-commands) resolve inside the plugin's bundle, which a bare console snippet cannot do. If you ran Step 1 in the live console, refresh the editor page first: registering the same id twice throws. Here is the whole pro.notes module — registration, a command, a panel section — as one file:

/**
 * pro.notes.tsx — a minimal Volux feature module: one command in the catalog,
 * one trailing panel section on every box object.
 */
import { Stack, Typography } from '@mui/material';

import { defineCommand } from 'volux-commands/define-command';

import type { RegisteredCommandRecord } from 'volux-commands/define-command';
import type { FeatureModule } from 'volux-registry';

/** The panel section — renders at the end of every box object's panel. */
function NotesSection() {
  return (
    <Stack spacing={0.5} sx={{ px: 2, py: 1 }}>
      <Typography variant="subtitle2">Notes</Typography>
      <Typography variant="body2" color="text.secondary">
        Provided by the pro.notes module.
      </Typography>
    </Stack>
  );
}

const commands: RegisteredCommandRecord[] = [
  defineCommand({
    id: 'notes.report',
    title: 'Notes Report',
    description: 'Counts the scenes and objects of the open document.',
    schema: { type: 'object', properties: {}, additionalProperties: false },
    undoable: false,
    realm: 'editor',
    exposure: 'ui-only',
    handler: (ctx) => {
      const canvas = ctx.getState().editorCanvas.present;
      return {
        scenes: Object.keys(canvas.scenes).length,
        objects: Object.keys(canvas.objects3d).length
      };
    }
  })
];

const PRO_NOTES_MODULE: FeatureModule = {
  id: 'pro.notes',
  dependsOn: ['core-builtin', 'editor-builtin'],
  capabilities: {
    commands,
    panels: [{ objectType: 'box', slot: 'trailing', components: [NotesSection] }]
  }
};

const outcome = window.voluxPlugin.registerModule(PRO_NOTES_MODULE);

if (outcome.status === 'applied') {
  console.log('pro.notes applied');
} else if (outcome.status === 'absent') {
  console.warn(`pro.notes absent: ${outcome.absent.reason} (${outcome.absent.blocker})`);
}

The CodeBlock above has a copy button in its corner — take the listing from there.

Step by step

The module record. id is unique (the pro. prefix keeps extension ids away from Volux's built-ins — a duplicate id throws). dependsOn names core-builtin (the always-registered base) and editor-builtin (the editor's own base, which carries the core command families). Depending on a module that never registered — or never activated — is the main way a module ends up absent with reason missing-dependency.

The command. defineCommand wraps a handler with schema validation and error mapping. The descriptor fields:

  • id — unique across the whole catalog (189 built-in ids; pick a namespaced one).
  • schema — a JSON-Schema subset; additionalProperties: false keeps payloads closed. This command takes an empty payload.
  • undoable: false — the handler only reads state, so there is nothing to undo. A command that writes the document sets undoable: true (and usually a gestureGroup for drag-style interactions).
  • realm: 'editor' — the command runs where the store lives.
  • exposure: 'ui-only' — the command is not offered to the AI Builder. Set 'ai' if a model should drive it.
  • handler — receives the ops context (ctx). ctx.getState() reads the store snapshot; write paths go through the same context's dispatch and sync ports, which is what makes undo and tree sync work.

The handler returns a plain value — it lands as data on the success envelope.

The panel section. The panels concern maps an object type to section components. objectType: 'box' targets the box kind. Without a slot the entry lands in the per-type pilot slot — where a pilot's fed sections replace the static chain — while slot: 'trailing' mounts the section at the very end of it. The trailing slot renders under its own capability gate: the section shows while box carries the collision capability (true on an all-on build, because the physics module composes that flag onto the mesh rows), and stays hidden where the physics module is absent. The component itself is props-free — it renders, and it can read editor state through the store hooks just like Volux's own sections do.

Registration. window.voluxPlugin.registerModule(PRO_NOTES_MODULE) registers and — because the boot activation has already run — late-applies the module: the kernel builds its feed slice (enriched where concerns need the full world), the shared applier runs, and because the bus binding is installed on an editor page, the editor and command appliers run too. The commands entries land in the catalog; the panel section joins the box panel.

Step 3: Verify activation

The outcome already told you the module applied. Now use it — run the command through the bus and watch the panel:

const bus = window.voluxPlugin.getCommandBus();
bus.executeCommand('notes.report');
// { ok: true, data: { scenes: 1, objects: 3 } }

Select a box in the viewport and open its panel in the right sidebar — the Notes section renders at the bottom of the panel (the trailing gate above applies). Delete the module's registration? There is no unregister: registration is for the page lifetime, which is why the outcome object — not optimism — is the verification step.

Going further from here

  • Type your command's payload and result. The built-in families extend a compile-time call map by interface merging, so executeCommand('notes.report') type-checks from TypeScript the same way it does at runtime:

    type NotesReportPayload = Record<string, never>;
    
    declare module 'volux-commands/types' {
      interface CommandMap {
        'notes.report': { payload: NotesReportPayload; result: { scenes: number; objects: number } };
      }
    }
  • Add runtime content. The runtimeMounts concern mounts components beside (or around) the scene content chain, in the editor, the frontend, or both — that is how the speaker and post-processing pilots render.

  • Compose capabilities. The contributesCapabilities concern overlays capability flags onto existing object kinds — the physics module owns collision on the mesh rows exactly this way.

  • Split the trees. When a module grows a frontend presence, split it into a portable half and an editor half, the way every pilot does — see registerModule & Module Anatomy.

Next

Last updated on

On this page