Messages

Description

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: To call a function in another script, you should use one of the following rather than sending a message:

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar Scripts • Server Entity Scripts • Assignment Client Scripts

Methods

Name Return Value Summary
sendData None Sends a data message on a channel.
sendLocalMessage None Sends a text message locally on a channel. This is the same as calling sendMessage with localOnly == true.
sendMessage None Sends a text message on a channel.
subscribe None Subscribes the scripting environment — Interface, the entity script server, or assignment client instance — to receive messages on a specific channel. This means, for example, that if there are two Interface scripts that subscribe to different channels, both scripts will receive messages on both channels.
unsubscribe None Unsubscribes the scripting environment from receiving messages on a specific channel.

Signals

Name Summary
dataReceived Triggered when a data message is received.
messageReceived Triggered when a text message is received.

Method Details

(static) sendData( channel, data, localOnlyopt )

Sends a data message on a channel.

Parameters

Name Type Attributes Default Value 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);
(static) sendLocalMessage( channel, message )

Sends a text message locally on a channel. This is the same as calling sendMessage with localOnly == true.

Parameters

Name Type Description
channel string The channel to send the message on.
message string The message to send.
(static) sendMessage( channel, message, localOnlyopt )

Sends a text message on a channel.

Parameters

Name Type Attributes Default Value 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);
(static) subscribe( channel )

Subscribes the scripting environment — Interface, the entity script server, or assignment client instance — to receive messages on a specific channel. This means, for example, that 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.
(static) unsubscribe( channel )

Unsubscribes the scripting environment from receiving messages on a specific channel.

Parameters

Name Type Description
channel string The channel to unsubscribe from.

Signal Details

dataReceived( channel, data, senderID, localOnly )
Returns: Signal

Triggered when a data message is received.

Parameters

Name Type Description
channel string The channel that the message was sent on. This can be used 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 instance if sent by an assignment client script.
localOnly boolean true if the message was sent with localOnly == true.
messageReceived( channel, message, senderID, localOnly )
Returns: Signal

Triggered when a text message is received.

Parameters

Name Type Description
channel string The channel that the message was sent on. This can be used 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.