High Fidelity API Reference

Messages

• Methods • Signals • Method Details • Signal Details •

Description

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar 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: To call a function in another script, you should use one of the following rather than sending a message:

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.