Volux Docs

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 collision on 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

Last updated on

On this page