Messages - Vircadia API Docs

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

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.vircadia.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.vircadia.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

false

If false then the message is sent to all Interface, client entity, server entity, and assignment client scripts in the domain.

Example

Send and receive a message.

// Receiving script.
var channelName = "com.vircadia.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.vircadia.example.messages-example";
var message = "Hello";
Messages.sendMessage(channelName, message);

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`.