Messages

Available in: Interface Scripts Client Entity Scripts Server Entity Scripts Assignment Client Scripts

The Messages API enables text and data to be sent between scripts over named "channels". A channel can have an arbitrary name to help separate messaging between different sets of scripts.

Note: If you want to call a function in another script, you should use one of the following rather than sending a message:

Methods

Signals

Methods

sendData(channel, data, localOnlyopt)
Send a data message on a channel.
Parameters:
Name Type Attributes Default Description
channel string The channel to send the data on.
data object The data to send. The data is handled as a byte stream, for example as may be provided via a JavaScript Int8Array object.
localOnly boolean <optional>
false If false then the message is sent to all Interface, client entity, server entity, and assignment client scripts in the domain.
If true then: if sent from an Interface or client entity script it is received by all Interface and client entity scripts; if sent from a server entity script it is received by all entity server scripts; and if sent from an assignment client script it is received only by that same assignment client script.
Example

Send and receive data.

// Receiving script.
var channelName = "com.highfidelity.example.messages-example";

function onDataReceived(channel, data, sender, localOnly) {
  var int8data = new Int8Array(data);
  var dataAsString = "";
  for (var i = 0; i < int8data.length; i++) {
      if (i > 0) {
          dataAsString += ", ";
      }
      dataAsString += int8data[i];
  }
  print("Data received:");
  print("- channel: " + channel);
  print("- data: " + dataAsString);
  print("- sender: " + sender);
  print("- localOnly: " + localOnly);
}

Messages.subscribe(channelName);
Messages.dataReceived.connect(onDataReceived);

Script.scriptEnding.connect(function () {
  Messages.dataReceived.disconnect(onDataReceived);
  Messages.unsubscribe(channelName);
});


// Sending script.
var channelName = "com.highfidelity.example.messages-example";
var int8data = new Int8Array([1, 1, 2, 3, 5, 8, 13]);
Messages.sendData(channelName, int8data.buffer);
sendLocalMessage(channel, message)
Send a text message locally on a channel. This is the same as calling sendMessage with localOnly set to true.
Parameters:
Name Type Description
channel string The channel to send the message on.
message string The message to send.
sendMessage(channel, message, localOnlyopt)
Send a text message on a channel.
Parameters:
Name Type Attributes Default Description
channel string The channel to send the message on.
message string The message to send.
localOnly boolean <optional>
false If false then the message is sent to all Interface, client entity, server entity, and assignment client scripts in the domain.
If true then: if sent from an Interface or client entity script it is received by all Interface and client entity scripts; if sent from a server entity script it is received by all entity server scripts; and if sent from an assignment client script it is received only by that same assignment client script.
Example

Send and receive a message.

// Receiving script.
var channelName = "com.highfidelity.example.messages-example";

function onMessageReceived(channel, message, sender, localOnly) {
  print("Message received:");
  print("- channel: " + channel);
  print("- message: " + message);
  print("- sender: " + sender);
  print("- localOnly: " + localOnly);
}

Messages.subscribe(channelName);
Messages.messageReceived.connect(onMessageReceived);

Script.scriptEnding.connect(function () {
  Messages.messageReceived.disconnect(onMessageReceived);
  Messages.unsubscribe(channelName);
});


// Sending script.
var channelName = "com.highfidelity.example.messages-example";
var message = "Hello";
Messages.sendMessage(channelName, message);
subscribe(channel)
Subscribe the scripting environment — Interface, the entity script server, or assignment client instance — to receive messages on a specific channel. Note that, for example, if there are two Interface scripts that subscribe to different channels, both scripts will receive messages on both channels.
Parameters:
Name Type Description
channel string The channel to subscribe to.
unsubscribe(channel)
Unsubscribe the scripting environment from receiving messages on a specific channel.
Parameters:
Name Type Description
channel string The channel to unsubscribe from.

Signals

dataReceived(channel, data, senderID, localOnly) → {Signal}
Triggered when a data message is received.
Parameters:
Name Type Description
channel string The channel that the message was sent on. You can use this to filter out messages not relevant to your script.
data object The data received. The data is handled as a byte stream, for example as may be used by a JavaScript Int8Array object.
senderID Uuid The UUID of the sender: the user's session UUID if sent by an Interface or client entity script, the UUID of the entity script server if sent by a server entity script, or the UUID of the assignment client script, the UUID of the entity script server if sent by a server entity script, or the UUID of the assignment client instance if sent by an assignment client script.
localOnly boolean true if the message was sent with localOnly = true.
Returns:
Type: Signal
messageReceived(channel, message, senderID, localOnly) → {Signal}
Triggered when the a text message is received.
Parameters:
Name Type Description
channel string The channel that the message was sent on. You can use this to filter out messages not relevant to your script.
message string The message received.
senderID Uuid The UUID of the sender: the user's session UUID if sent by an Interface or client entity script, the UUID of the entity script server if sent by a server entity script, or the UUID of the assignment client instance if sent by an assignment client script.
localOnly boolean true if the message was sent with localOnly = true.
Returns:
Type: Signal