Volux Docs

Events & Actions

Wire visitor interactions — mouse, keyboard, distance, collision, drag — to actions on objects and page elements.

Events make content interactive: a visitor clicks, hovers, or gets close, and the object's action list fires. This guide covers adding events to 3D objects, what each trigger fires on, which actions are offered where, and the special drag interaction. DOM page elements use the same editor with a smaller trigger set — see the end of this page.

Interactions run on the public site

Events fire for visitors on the published page, not in the editor canvas. Verify them on the frontend — click the eye icon beside PUBLISH to open the page the way visitors see it.

Add an event to an object

  1. Select the object and find the Events section on its panel. Click +.
  2. The add menu groups the triggers that actually fire:
    • Mouse — Mouse Up (the click), Mouse Down, Mouse Press, Mouse Hover.
    • Keyboard — Key Up, Key Down, Key Press. Key events carry the key they listen for.
    • Interaction — Drag & Drop (hidden until the object's drag is armed — below).
    • Logic / Scene — Start (scene load), Distance (a target enters or leaves a range), State Change (another object's state flips), Collision (physics contact starts or ends).
    • External — Screen Resize (the viewport crosses a device band).
  3. Click a trigger to add it. The event editor opens where you stack its actions.
The event type menu on a Box
The event type menu on a Box

Stack actions

  1. In the event editor, click the add button on the action list and pick an action: Transition (tween the object — or a target object or element — into one of its states), Open Link, Switch Camera, Particles Control, Speaker Control, Video, Physics Control, Timeline Animation, Create Object, Destroy Object, or Apply Force.
  2. Each action carries its own config row — a Transition picks target and state slots, Open Link takes a URL and a tab mode, and so on.
  3. Condition events — Distance, State Change, Collision, Screen Resize, and Drag & Drop — carry a Branch toggle: actions on the Then list fire on the enter edge, Else fires when the condition exits.
  4. Reverse on Release (Mouse Press and Mouse Hover only) re-runs the action list backwards on the disengage edge — a transition animates the object back to where it started.

The menu only offers what makes sense

The action add menu filters per event. Switch Camera isn't offered on Scroll; Open Link isn't offered on Screen Resize, Collision, or drag events; spawning actions (Create Object, Apply Force, Particles Control) skip Mouse Hover so a hover can't spam. Transitions and Timeline Animation are offered everywhere.

Arm a drag

Drag & Drop is a per-frame interaction, not a moment trigger: the object follows the pointer while grabbed. The mechanics live on the object itself, not in the event.

  1. Select the object and open its Interaction section. Flip the section's switch on and set the Mode to Drag. The Drag block exposes the cursor, damping (higher = more lag), the drag plane (aligned with the camera, adaptive, or fixed XY/XZ/YZ), per-axis limits, and drop snapping.
  2. With drag armed, the Drag & Drop event becomes addable on that object. Its Then actions fire at grab (after a 3-px slop so a click is never a drag) and its Else actions fire after the drop lands — a transition authored in Else never fights the snap tween.
  3. Drop targets: objects marked as drop areas (their Interaction section has the Drop area switch, optionally grouped) highlight green while you drag. Set what the mesh does on release — stay, return to its original spot, or return to the last snapped target.
  4. Arming a drag suppresses presentation controls (rotate/orbit) on that same object — they would fight over the same pointer-down.

Target other objects

Actions that point at something — Transition's target, Switch Camera's camera, Apply Force's body — default to the event's own object and accept any object in the document, across scenes. A Transition's state list can also pick the Live slot: whatever state the target is in at the moment of the fire.

Debugging a pointer event that never fires

If clicks reach an object on the frontend but its event never runs, inspect the mesh in the browser console: an event count of zero (mesh.__r3f.eventCount === 0) means the event handlers never reached the mesh — the event list is attached to a different or stale object. Also check that no drag session is holding the object: a grab claims the mesh and swallows mid-drag fires until the drop lands.

Elements on the page

Page elements — the DOM around your scenes — carry the same states and events. Open the Structure drawer, switch to the DOM tab, and click an element row: its panel carries States, Events, Structure (the reverse scene-link lookup), and Visibility.

  • Element triggers are exactly three: Mouse Up (click), Mouse Hover, and Scroll. Keyboard, distance, and the rest are object-only.
  • Element transitions tween opacity and transform only — the compositor-friendly pair.
  • The overlay of an HTML object, unlike an element, never emits pointer events; it is a target only. See HTML Overlays & DOM Interactivity.

Next

Last updated on

On this page