Overview: voluxPlugin API
The versioned public API seam for extending the Volux editor — what window.voluxPlugin exposes and when to reach for it.
Volux ships most of its own features — speakers, particles, physics, video layers, post-processing — as feature modules, no differently from what an extension registers. The public surface for doing the same is a single frozen JavaScript object: window.voluxPlugin. It appears once the editor (or the public frontend) has booted, and it is versioned: code you write against it keeps working across Volux releases until the API version changes.
This page maps what the object exposes and when extending is the right tool. The following pages cover each piece in depth: registerModule & Module Anatomy, the Capabilities Reference, the Command Bus, and a complete first module example.
What the API exposes
window.voluxPlugin carries exactly four members — the object is frozen, so nothing else can be added to it at runtime:
Prop
Type
A quick sanity check from the browser console on any page running the editor:
window.voluxPlugin;
// { version: '1.0.0', registerModule: ƒ, getCommandBus: ƒ, describeCapabilities: ƒ }When does the global appear?
The editor boot installs it after the command bus is bound, so on an editor page the full surface is live by the time your code runs. The public frontend and the preview iframe install the same global through their own boot, but never install a bus binding — getCommandBus() answers null there, and only the shared-realm concerns of a module (runtime mounts, capability rows, offered actions) can apply.
The command bus
getCommandBus() is how an extension runs Volux's commands and queries instead of reaching into the editor's internals:
const bus = window.voluxPlugin.getCommandBus();
const tree = bus.queryScene('scene.tree', {});
if (tree.ok) {
console.log(tree.data.objects3d);
} else {
console.error(tree.error.code, tree.error.message);
}Every call returns a settled envelope — { ok: true, data } or { ok: false, error: { code, message } } — so failures are values, never exceptions. Commands mutate documents and participate in undo; queries are read-only. The full catalog, envelope shapes, and the AI-exposure note live on the Command Bus page.
When to extend — and when not to
Reaching for voluxPlugin is the right move when you want to:
- Add feature content the registry can carry: runtime mounts beside the scene, panel sections, event-action executors, material-layer kinds, tool entries.
- Compose capability flags onto existing object kinds — the way the physics module owns
collisionon the mesh rows. - Register commands that other surfaces (panels, the AI Builder) can invoke through the same typed bus Volux itself uses.
- Ship Pro-tier features as a separate bundle that registers late, after the editor has booted.
It is the wrong move when you want to:
- Edit a document from outside the editor. Document writes go through the command bus and the ops it wraps — driving the editor's Redux store directly from extension code bypasses undo, tree sync, and validation, and breaks the moment internals shift.
- Render 3D content on your own. The frontend portal pipeline (Publishing) already mounts scenes by shortcode; a parallel canvas fights it for the shared renderer.
- Toggle built-in features per page. Edition capabilities are a server-side, per-boot decision — not something a client script should or can flip.
Registration is first-wins, ids are unique
Registering a module whose id is already taken throws. Pro-style bundles namespace their ids (the pro. prefix) to stay collision-free with the built-ins. If a module you register does not appear, check the returned outcome object — it names the reason and the blocking module or entitlement.
Next
- registerModule & Module Anatomy — the module record, the two-tree split, and activation semantics.
- Capabilities Reference — the per-kind capability matrix and how modules compose it.
- Command Bus —
executeCommand,queryScene, and the descriptor catalog. - Example: Your First Module — a complete working module, step by step.
Extend Volux
Register feature modules, command-bus families, and panels through the public voluxPlugin API.
registerModule & Module Anatomy
The anatomy of a feature module — the module record, the two-tree split, dependency and entitlement gating, and late registration semantics.
Last updated on