Untitled

📰Getting Started | ⭐**Updates |** 📝 Guides | 🔢 API | ❓FAQ

Guides Overview

The Messages API provides global message dispatching for your experience's scripting. Messages can be dispatched via dispatch and listened to with on and off.

const messages = require('messages');

Basic Usage

// One element subscribes to a message.
var treasure =this.find('..(@name=Treasure)');

function showTreasure(visible) {
  treasure.visible = visible;
}

messages.on('show-treasure', showTreasure);

...

// And some other element sends a message.
var messages = require('messages');

messages.dispatch('show-treasure', true);

⚠️ Warning: Make sure that you unsubscribe to messages or you could trigger a memory leak!

Example of subscribing and unsubscribing:

const TRIGGER_MSG = "{[Trigger Message:string]}";
const RESET_MSG = "{[Reset Message:string]}";
var magic;

function enter() {
  // If there is a trigger message
if (TRIGGER_MSG) {
    // listen for the trigger message to increase magic.
    messages.on(TRIGGER_MSG, increaseMagic);
  }

if (RESET_MSG) {
    // listen for the trigger message to reset magic.
    messages.on(RESET_MSG, reset);
  }
}

function increaseMagic(){
    magic += 1;
}
function reset(){
    magic = 0;
}
/**
 * Called before the script is removed or rebuilt.
*/
function exit() {

if (TRIGGER_MSG) {
    // unsubscribe from increase magic message.
    messages.off(TRIGGER_MSG, increaseMagic);
  }

if (RESET_MSG) {
    // unsubscribe from reset magic message.
    messages.off(RESET_MSG, reset);
  }

}

You can also pass objects with messages.

Here is an example of creating an object and dispatching it:

//api
const messages = require('messages');

const TRIGGER_MSG = '{[Triggered message:string=msgAnimal]}';

var myAnimal = {
  Name:'',
  Age:0,
}

function enter() {
  
  myAnimal.Type= "Deer";
  myAnimal.Age= 2;
  
  messageSent();
}

function messageSent() {
  messages.dispatch(TRIGGER_MSG, myAnimal);
}

function exit() {
}

module.exports = {
  enter: enter,
  exit: exit
};

Here is an example of receiving that object:

//Example of how to receive an object and use the data

const messages = require('messages');

const LISTEN_MSG = '{[Listen for message:string=msgAnimal]}';

function enter() {
  messages.on(LISTEN_MSG, dataTest); 
}

function dataTest(sentObject){
 
  if(sentObject){
    log.info("My object is type:" + sentObject.Type); 
  }
}

function exit() {
  messages.off(LISTEN_MSG, dataTest);
}

module.exports = {
  enter: enter,
  exit: exit
};

Sending / Receiving Messages Within Experiences Only

By default, using messages as above can be sent and received globally by all active elements in the scene.

Say you are making use of Experience Embedding. You want to combine multiple experiences, each holding a character you can talk to.

But each character experience has identical messages for talking to the character. If you use the messaging API untouched, when you talk to one character, you’ll talk to all of them at the same time! By default, messages are sent globally.

However, by using a set of alternate functions, you can make it so that elements within an experience will only communicate amongst themselves:

const messages = require('messages');

/* subscribe to a message, but only invoke the callback if another script calls
 * dispatchExperience with the same message and a reference to some element in the experience
 */ 
messages.onExperience(referenceToAnyElementInExperience, "message", callback);
messages.offExperience(referenceToAnyElementInExperience, "message", callback);

/* dispatch a message, but attach identifying information that will cause this
 * message to only be picked up by scripts that used on/offExperience with a reference
 * to some element in this experience
 */ 
messages.dispatchExperience(referenceToAnyElementInExperience, "message");
messages.dispatchExperience(referenceToAnyElementInExperience, "message", payload);

This configures the message under-the-hood to only send the message to elements in that experience, using some special identifying information about the experience.

Sending / Receiving Messages Within Elements Only

You can even set it up so that specific elements only communicate with themselves, which is helpful if you want a script to communicate with another script on the same element, but only that one.

/* subscribe to a message, but only invoke the callback if another script calls
 * dispatchExperience with the same message and a reference to a specific element
 */ 
messages.onElement(referenceToASpecificElement, "message", callback);
messages.offElement(referenceToASpecificElement, "message", callback);

/* dispatch a message, but attach identifying information that will cause this
 * message to only be picked up by scripts that used on/offElement with a reference
 * to the same element
 */ 
messages.dispatchElement(referenceToASpecificElement, "message");
messages.dispatchElement(referenceToASpecificElement, "message", payload);

This one is a bit trickier to use because you need to provide the exact same element reference for on/offElement and dispatchElement. Elements other than themselves are not able to easily get references to other elements. Right now, this can only really be used effectively by different scripts on the same element.

Module Methods

Global

on(event, callback)

Subscribes to an event.

off(event, callback)

dispatch(event, [payload])

Notifies all subscribers of an event.

Experience

onExperience(element, event, callback)

Subscribes to an event that will only be received if you call dispatchExperience with a reference to an element in the same experience.

offExperience(element, event, callback)

Unsubscribes from an event.

dispatchExperience(element, event, [payload])

Notifies all subscribers of an event, if they are part of the same experience as the element reference provided in the first parameter.

Element

onElement(element, event, callback)

Subscribes to an event that will only be received if you call dispatchElement with a reference to the same element.

offElement(element, event, callback)

Unsubscribes from an event.

dispatchElement(element, event, [payload])

Notifies all subscribers of an event if it is the same element as the one provided in the first parameter.

Next: Multiplayer

Sidebar Table of Contents

Untitled