The unfinished project

Download the unfinished project to follow along.

In the example project, you’ll find a number of assets already set up, including a canvas group, materials and imported textures.

Additionally, in the Patch Editor you’ll find a patch graph which sends a tap event to a script and another which handles the changing of the user’s background.

The script.js asset already contains some code which is used to track the current background image and to subscribe to the event sent from the Patch Editor.

// Load in the required modules
const Patches = require('Patches');
const Diagnostics = require('Diagnostics');
 
(async function () { // Enable async/await in JS [part 1]
 
 // Initialize background tracking variables
 const totalBackgroundCount = 3;
 var backgroundIndex = 0;
 
 // Get the tap event from the Patch Editor
 const screenTapPulse = await Patches.outputs.getPulse('screenTapPulse');
 
 // Subscribe to the screen tap event
 screenTapPulse.subscribe(() => {
 
 });
 
})(); // Enable async/await in JS [part 2]
      

Message sender and receiver logic

When a call participant opens a group effect it's automatically applied to all other participants on the call, though each participant will be running their own instance.

To communicate between the various instances of the effect, we’ll implement logic that allows them to both send messages to, and receive them from, the other instances.

This way, each instance is notified of any state changes and can be updated accordingly.

For the example project we'll be following the logic below, which describes what will happen every time a screen tap occurs on any of the running instances.

For each screen tap interaction, the participant that taps on the screen is classed as the message sender, while the other participants are classed as the message receivers.

Message sender

1. Determine the next background that needs to be displayed. The background selection should wrap around the array, for example: background 1 > background 2 > background 3 > background 1.
2. Change the background of the participant that tapped on the screen.
3. Broadcast a message to all other instances of the effect on a given message channel, notifying them that the background needs to be changed.

Message receiver

1. Listen out for messages sent to a given message channel.
2. Read the contents of the message received to determine the new background value.
3. Change the receiver's background to the new value.

Now that we have an idea about the logic required, we can begin to implement the functionality in a script.

Script setup

Open the script.js file in a text editor.

On line 4, import the MultipeerModule into the script with the following line of code so that you can make use of the multipeer API.

const Multipeer = require('Multipeer');
        

Creating a message channel

We need to create a message channel where messages can be sent to and retrieved from.

The multipeer API supports the use of multiple message channels but we'll only be creating one in this example.

On line 14, add the following lines of code:

// Create a message channel
const backgroundIndexChannel = Multipeer.getMessageChannel('backgroundIndexTopic');
        

The getMessageChannel() method takes a single argument, the name of the message channel to create. With the line above we’ve created the BackgroundIndexTopic message channel.

We’ll need the channel name to send and retrieve messages later on in our code.

Updating the background image index

Before we send a message to the message channel, we need to update the variable keeping track of the active background image and send its value to the Patch Editor.

We’ll do this within the tap event callback function that was already set up in the script.

Starting on line 20 copy and paste the code snippet below.

// Increment the background index to show the next background graphic
backgroundIndex++;
 
// If the index value is equal to the total number of background images,
// reset the value so that the displayed graphic loops.
if (backgroundIndex >= totalBackgroundCount) {
  backgroundIndex = 0;
}
 
// Send the new background index value to the Patch Editor, so that it can be
// used to update the background graphic displayed
Patches.inputs.setScalar('msg_background', backgroundIndex);
        

Sending messages to a message channel

To send a message to a message channel you can call the sendMessage() method exposed by MessageChannel objects.

Paste the code snippet below immediately after the previous snippet, on line 33. Make sure to add it before the callback function’s closing curly bracket (the ‘}’).

// Broadcast the new background index value to other participants on the
// previously created backgroundIndexChannel message channel
backgroundIndexChannel.sendMessage({'background': backgroundIndex }, true).catch(err => {
    
  // If there was an error sending the message, log it to the console
  Diagnostics.log(err);
});
        

The method’s first argument is a JSON formatted object containing a name and a value to send to the channel. In our case, we’re sending the backgroundIndex variable to the channel backgroundIndexChannel under the name background.

The second argument, true, refers to whether the message should be sent using the Real-Time Channel messaging backend, which has a high bandwidth for message streams but doesn’t guarantee a synchronized message order across participants.

If false had been passed, the Sync Channel backend would have been used instead, which synchronizes message order across participants but has a message rate limit of 75 messages every 30 seconds.

The catch() method and subsequent console log is there to notify us if anything goes wrong when sending the message.

FAQ

        Blocks.instantiate('mp_block', {name: "block1"}, {multipeerId: 'block1'})