Articles
Video Calling and Group Effects
Debugging Group Effects

Debugging Group Effects

The multipeer capability allows an effect running in a video call to communicate with other instances of the same effect in the call. These kinds of effects are known as group effects in Spark AR Studio.

This is achieved via the broadcasting and receiving of JSON formatted messages between the instances.

Messages are broadcast to all participants except the effect instance that the message was broadcast from - a participant can’t broadcast a message to themselves.

These messages can be sent using one of the following channels:

  • Realtime Channel (Async). The default channel used, which provides a higher bandwidth for messages. Messages are broadcast to participants in real-time, so a synchronized message order isn't guaranteed.
  • Sync Channel. An alternative channel with limited bandwidth. Messages are synchronized across all participants, meaning that the message order is guaranteed to be identical for each participant.

The Sync Channel has a message rate limit of 75 messages every 30 seconds. Any additional messages beyond this limit are dropped.

Spark AR Studio provides a way to debug and test group effects by simulating additional participants.

This can be done using one of the following methods:

  • Simulating message relays with the Multipeer Debugging Tool in Spark AR Studio.
  • Simulating message relays with the Multipeer Debugging Tool in Visual Studio Code with the Spark AR extension.
  • Simulating additional participants using Spark AR Studio and Spark AR Player for Desktop.

Preparation

Download Spark AR Studio and Spark AR Player for Desktop from the Downloads page and create a new project.

Add a new JavaScript asset to the project, then open it in a code editor and paste in the following code:

const Scene = require('Scene');
const Multipeer = require('Multipeer');

// Retrieve the 'MyTopic' message channel
const topicChannel = Multipeer.getMessageChannel("MyTopic");
                  
// Send a message to 'MyTopic' using the default Realtime Channel (Async)
topicChannel.sendMessage({ 
    "message": "Hello  MyTopic!",
    "someValue": 10                  
}, true);


// Send a message to 'MyTopic' using the Sync Channel
topicChannel.sendMessage({ 
  "message": "Hello  again!",
  "someValue": 20                  
}, false);
                

Viewing received messages

Open the Multipeer Debugging Tool from the Spark AR Studio menu bar.

This will bring up the Multipeer Debugging panel below the viewport.

Messages sent and received via the Multipeer API are logged in the Multipeer Debugging panel.

In the image below we see the message sent to the MyTopic channel with the previous example code:

The Topic field lists the channel the message was sent to, while Message displays the JSON formatted object sent to the channel.

Direction specifies whether the message was sent from this instance of the effect (Outgoing), or if it was received from an external instance (Incoming).

In Visual Studio Code, with the Spark AR extension active, received messages will similarly be displayed under the Spark AR tab in the terminal window.

Simulating sending messages

The debugging tool can also simulate the sending of messages via the Compose Messages option.

The From dropdown specifies which instance of the effect the message will be sent from. By default only Local will be available, which represents the instance of the effect running in Spark AR Studio.

The Topic field sets which channel the message should be sent to.

The Message field accepts any JSON formatted object as a valid entry, for example:

{"message": "Sent via Compose Messages option.", "someValue": 20}
              

Clicking Send displays the message in the Multipeer Debugging panel's Messages History section and broadcasts it to all other instances of the effect:

You can listen out for these messages with an onMessage() subscription for the matching channel topic. For example, for the topicChannel message channel we set up previously:

topicChannel.onMessage().subscribe((msg) =>{
	Diagnostics.log(msg);                
});
              

With the Spark AR extension for Visual Studio Code, messages can also be sent from the multipeer debugging tool found within the Spark AR tab in the terminal window.



For any given message sent, the message sender won't receive an event through their onMessage() subscription.

For example, if participant A broadcasts a message, participants B and C will receive the message but participant A won’t, as they can't send a message to themselves.

Preview group effects with SparkAR Player for Desktop

The Spark AR Player for Desktop can be used to simulate a group effect running with multiple participants.

In Studio, select Preview in Spark AR Player for Desktop from the menu bar.

When the effect is loaded in Spark AR Player for Desktop, the Player instance's console will be accessible in the console source dropdown in Spark AR Studio:

If you make any changes to your effect in Spark AR Studio while previewing, you can save the project to see the changes automatically reflected in Spark AR Desktop player.

If forwarded console logs don't appear initially, save the project then reopen it within Spark AR Studio and Spark AR Player for Desktop.

To simulate additional participants in the call, enable the grid view in Spark AR Player and use the dropdown to set the number of participants.

These new participants will also be listed in the console dropdown in Spark AR Studio:

Simulating sending a message from an external participant

Additional peers added through Spark AR Player for Desktop also appear within the From dropdown in the Multipeer Debugging panel:

This allows you to send a message from a specific instance to all other participants listening out for messages sent to a given topic channel.

Open the script added to the project during the preparation and replace its contents with the code below:

const Scene = require('Scene');
const Multipeer = require('Multipeer');
const Diagnostics = require('Diagnostics');

// Retrieve the 'MyTopic' message channel
const topicChannel = Multipeer.getMessageChannel("MyTopic");

// Send a message on the 'MyTopic' channel
topicChannel.sendMessage({
    "message": "Hello  MyTopic channel!",
    "someValue": 10
});

// Listen to messages on the ‘MyTopic’ channel and print them
topicChannel.onMessage.subscribe((msg) => {

  // Print the entire JSON object received
  Diagnostics.log(msg);

  // Print specific contents of the JSON object received
  Diagnostics.log(`Message received: ${msg.message}`);
  Diagnostics.log(`Value received: ${msg.someValue}`);
});
              

In the Multipeer Debugging panel, select a participant other than Local in the From dropdown and enter MyTopic in the Topic field.

In the Message field, paste the following JSON and then click Send:

{"message": "Sent via Compose Messages option.", "someValue": 20}
              

The updated script from the previous step will log the composed message to the console:

The console source that matches the participant that the message was broadcast from won’t display the logged message.

Was this article helpful?