Documentazione

Message bus (DiscoVR.bus)

La documentazione tecnica è in inglese.

When several parts of an experience need to talk to each other - a button that opens a door, a trigger that starts a video, a score shown on a sign - plain DOM events get awkward: you need a reference to the other object's element, you have to wait for it to exist, and a message sent before the listener is ready is lost. DiscoVR.bus is a small page-wide message bus built for exactly that.

DiscoVR.bus exists as soon as discovr-core.js has run, before the scene does, so a script can subscribe at load time. It works without creating a DiscoVR instance.

DiscoVR.bus.on("door:open", function (payload) {
    console.log("opening at speed", payload.speed);
});

DiscoVR.bus.emit("door:open", { speed: 2 });

#Topics

A topic is a string without spaces, conventionally area:action (door:open, score, quiz:answer:correct).

In a subscription, * is a wildcard:

Emitted topics are always literal.

#API

message is { topic, payload, time, retained, replayed }. Handlers run synchronously, in subscription order. A handler that throws is logged and does not stop the others. A chain of more than 32 nested emits is cut and logged (it is almost always a message loop).

#Retained messages: never "too early"

DiscoVR.bus.set("score", 10);                       // somewhere, early

// ...much later, from another script or component - still gets 10 right away:
DiscoVR.bus.watch("score", function (value) { sign.setAttribute("value", "Score: " + value); });

#Cleaning up automatically

Inside an A-Frame component, subscribe through a scope: everything is removed when the component - or the whole entity - is removed, so remove() has nothing to undo.

AFRAME.registerComponent("door", {
    init: function () {
        this.bus = DiscoVR.bus.scope(this);
        this.bus.on("door:open", this.open.bind(this));
    },
    open: function () { this.el.setAttribute("visible", false); }
});

Outside components, var scope = DiscoVR.bus.scope(); ... scope.destroy();.

#Wiring without code: the i-bus component

<!-- click -> publishes "door:open" -->
<a-box class="raycastable" i-bus="on: click; emit: door:open"></a-box>

<!-- hears "door:open" -> hides itself -->
<a-entity id="door" i-bus="listen: door:open; do: hide"></a-entity>

A sound entity already publishes the DOM event sound-ended when it finishes by itself, so on: sound-ended; emit: ... chains sounds or actions.

An entity can carry several rules: i-bus__open="...", i-bus__close="...".

Actions: show, hide, toggle (visibility); set; xray-on, xray-off, xray-toggle (the target's i-xray); animation-play, animation-pause, animation-toggle (the target's animation-mixer); mixer-set, mixer-toggle (the audio mixer, below); move, rotate (degrees), scale (animated transforms); sound-play (restarts), sound-stop, sound-toggle (the target's sound component); sound-once (plays the audio file in value - #assetId or a URL - once, flat, without needing a sound entity); emit (publish the topic in value with the same payload - chain topics).

#Sound zones: i-sound-zone

Makes an entity's sound play only while the visitor is inside an area, fading in on entry and out on exit - room ambience, or narration that starts when someone comes close:

<a-entity sound="src: #rain; loop: true; positional: false" i-sound-zone="shape: box; size: 10 4 10; fade: 2"></a-entity>

The entity also gets the DOM events zone-enter / zone-exit (usable as on: in an i-bus rule). The zone decides when the sound plays - its autoplay is overridden.

#The audio mixer: i-audio-mixer and i-sound-channel

Every sound belongs to a channel - effects, ambience, music or narration - and is heard at its own volume x master x its channel. The scene's i-audio-mixer (created automatically; set it yourself to choose the starting mix) holds the gains and changes them while the page runs:

<a-scene i-audio-mixer="master: 0.8; music: 0.4"> ...
<a-entity sound="src: #theme; loop: true" i-sound-channel="channel: music"></a-entity>

DiscoVR.bus.emit("mixer:music", 0.2);                           // fade to 20%
DiscoVR.bus.emit("mixer:master", { value: 0, duration: 1500 }); // mute over 1.5 s (duration in ms, 0 = at once)
DiscoVR.bus.emit("mixer:music", { toggle: true });              // mute / restore the previous level

The background music (audio:bgMusic) is on the music channel. In i-bus rules use do: mixer-set; attribute: music; value: 0.2; duration: 500 and do: mixer-toggle; attribute: master. A command sent before the scene has finished loading is not delivered. An entity with i-sound-zone has the mixer applied to its zone volume.

#Messages from outside: i-net-feed

An outside system (a sensor gateway, a PLC bridge, a customer's backend) can drive a scene through DiscoVR NET. The scene listens with i-net-feed:

<a-scene i-net-feed="server: wss://net.discovr-engine.eu; room: plant-3; channels: telemetry, alarm">

Every message the outside system broadcasts on one of those channels becomes a bus message whose topic is the channel and whose payload is its data, retained by default (retain: false to turn that off). From there, i-bus rules or scripts react to it: i-bus="listen: alarm; do: show" on a warning sign, or do: set with value: $payload to use the data itself as a value (send a string or a number for that; an object is for scripts, DiscoVR.bus.on("telemetry", (data) => data.temp)).

The outside system is a plain WebSocket client, in any language:

const ws = new WebSocket("wss://net.discovr-engine.eu");
ws.onopen = () => {
  ws.send(JSON.stringify({ event: "joinRoom", data: { room: "plant-3", app: "default" } }));
  setInterval(() => ws.send(JSON.stringify({
    event: "broadcast",
    data: { type: "telemetry", data: { temp: 23.5 } },
  })), 1000);
};

• The page joins as a NET listener: it doesn't need multiplayer or a player rig, isn't a person in the room, and receives only the listed channels. It never sends anything.
• Messages reach the pages open at that moment; a page opened later gets the next one (send at regular intervals, or the last value is missing until then).
• net-feed:status (retained) says connected / disconnected; the feed reconnects on its own.
• Anyone who knows the server and the room can send. Don't drive anything sensitive with it until NET has client keys.

#Showing a value: i-gauge

A round gauge (an arc that fills from min to max, a needle, the number with its unit, and a label) that follows a topic:

<a-entity position="0 1.5 -2" i-gauge="topic: bio:heart-rate; label: Heart rate; min: 40; max: 160; decimals: 0; unit: bpm"></a-entity>

It shows the topic's retained value at once, then every new message. The payload can be a number, a numeric string, or an object with a value field ({ value: 0.7 }). Until the first message it shows --; while <topic>:signal is lost it turns grey and shows -- too, so a source can say it has lost its sensor with DiscoVR.bus.set("bio:heart-rate:signal", "lost") (and "ok" afterwards).

Without a topic it shows a fixed value instead (i-gauge="value: 72; max: 100; unit: %; decimals: 0"), which a rule can still change: i-bus="listen: load; do: set; attribute: i-gauge.value; value: $payload".

Other properties: radius 0.3 (meters), thickness 0.05, sweep 240 (degrees of arc), needle true, smoothing 0.4 (seconds to glide to a new value, 0 = jump), and the colors colorLow / colorHigh (the fill fades from one to the other along the range), trackColor, lostColor, textColor. The unit follows the number after a space (72 bpm), except a unit starting with % or ° (72%, 21.5°C). Example: public/examples/gauge/.

#Debugging

With debug="true" on the <discovr> tag, emitting a topic nobody listens to prints a warning - with a "did you mean ...?" hint when a similar topic exists. (A lone * monitor does not count as listening, so a logger can't hide a typo.) To watch all traffic:

DiscoVR.bus.on("*", function (payload, message) {
    if (!message.replayed) console.log(message.topic, payload);
}, { replay: false });

A complete example is in examples/bus/.