Skip to main content
Version: 5.x

Connected Lenses Example

The Connected Lenses Module allows a Lens to invite other people into the same Multiplayer Session where data can be shared. Learn more about the module in its Overview guide.

Creating the Connected Lens Module

First, we’ll add a ConnectedLensModule as a resource in your Lens. In the Asset Browser panel, press +, and choose ConnectedLensModule. This module allows you to invite others, as well as respond to different events.

Then, we need to create a Script to utilize the ConnectedLensModule. In this script, we will pass in our ConnectedLensModule

// @input Asset.ConnectedLensModule connectedLensModule

Interacting with the ConnectedLensModule

Next, we need to create ConnectedLensSessionOptions which will provide the ConnectedLensModule with information on how we want things to be handled.

For now we’ll just pass in some function names that we will define later. Feel free to comment out the different options so that your Lens does not error before we implement them.

// Create the option
const options = ConnectedLensSessionOptions.create();

// Add stubs for functions which will respond to different events
options.onConnected = onConnected;
options.onSessionCreated = onSessionCreated;
options.onUserJoinedSession = onUserJoinedSession;
options.onUserLeftSession = onUserLeftSession;

Starting the Connected Lens experience

When a Lens contains the ConnectedLensModule, a button will appear when the Lens opens to allow the user to enter into a Connected Lens session. When the user presses the button, we can ask the Connected Lens Module to create a session.

script.createEvent('ConnectedLensEnteredEvent').bind(function () {
script.connectedLensModule.createSession(options);
});

As you can imagine, there are two ways a user can enter into a Multiplayer Session: they can be the first Lens user (host), or be the invited guests (receiver).

If they are the host, once the user enters a Connected Lens, the first onSessionCreated will provide a “solo” session. That is: it’s their own session with no one is in it, since no one has been invited to it.

In order to make it multiplayer, we’ll create a function that tells the ConnectedLensModule to create a session that can be shared with others.

Inviting others to the same session

As mentioned in the overview guide, there are two ways users can be invited into an experience:

  1. Shared via Friends List (ConnectedLensModule.SessionShareType.Invitation)
  2. Shared via Snapcode (ConnectedLensModule.SessionShareType.Snapcode)

When sharing with the Invitation option, the Lens will open up the friendslist to allow others to be invited.

When sharing with the Snapcode option, in the callback you will receive a texture which you can display on any Image component. When others scan the Snapcode, they will be able to join the sesion.

function shareSession() {
// Decide whether we want to invite others using Friends list `Invitation`, or via Snapcode `Snapcode`
const invitationType = ConnectedLensModule.SessionShareType.Invitation;

function onSessionShared(session, snapcodeTexture) {
// If we used Snapcode Invitation, then we need to display the Snapcode somewhere
if (invitationType === ConnectedLensModule.SessionShareType.Snapcode) {
if (script.snapcodeImage) {
script.snapcodeImage.mainPass.baseTex = snapcodeTexture;
} else {
print(
'Please provide a Component.Image where Snapcode Texture can be displayed.'
);
}
}

print('Session Shared');
}

// Request to Share
script.connectedLensModule.shareSession(invitationType, onSessionShared);
}

On Session Created

But how do we know whether the user is the Host or a receiver? The good news is that the onSessionCreated callback will provide information about the session type! Let’s work on the onSessionCreated function we named earlier.

function onSessionCreated(session, sessionCreationType) {
// If I already know how I entered this game, we don't need to set it again
// Otherwise we will end up in a loop when we connect to the multiplayer session.
if (script.soloSession !== undefined) return;

print('==== On Session Created');

if (
sessionCreationType ==
ConnectedLensSessionOptions.SessionCreationType.MultiplayerReceiver
) {
print('Receiver');

// If I am a receiver, I start with a Multiplayer session
script.soloSession = false;
} else if (
sessionCreationType == ConnectedLensSessionOptions.SessionCreationType.New
) {
print('Host');
script.isHost = true;

// If I created a new session (fresh Lens open), then by default I'm in a Solo session.
script.soloSession = true;
}
}

Notice that there are several variables we create in this function.

As mentioned above, the first session provided to the host will be a solo session, thus if the session type is new we will mark a soloSession variable as true. In addition, we’ll store a variable that we are currently tracking the host via the isHost variable.

However, if the current participant was invited into a session, the first session is already multiplayer (since we at least have the host). Thus we mark soloSession as false.

We store our variables in the script object since we want them to exist outside of the onSessionCreated function. That is: we want to know about this information, even after onSessionCreated has finished.

Lastly, when the host invites someone else, they are creating a brand new multiplayer session that they are bringing themselves, and others to. Thus, the onSessionCreated callback will be called again. So we add a check at the top to not reset the soloSession variable, less we want to have an infinite loop.

Triggering different flow on connected

When a session is created, our ConnectedLensModule will automatically try to connect to them. This is where the variables we stored previously come in!

So, to make it easy for us to interact with the sessions, we can create different type of callbacks:

  • onHostConnectedToSolo which will be called the first time we enter a Connected Lens experience
  • onHostConnectedToMultiplayer which will be called once the Lens has been shared and a MultiplayerSession is created
  • onReceiverConnectedToMultiplayer which will be called for those joining via Snapcode or Invitatino.
function onConnected(session) {
print('==== On Connected');

if (script.soloSession) {
onHostConnectedToSolo(session);

// Now that we are sharing session, we will get another
// onSessionCreated. This time it will be Multiplayer.
script.soloSession = false;

return;
}

// If we are in a multiplayer session:
// Create a Realtime Store if I'm the host
// and store the session for later usage.

if (script.isHost) {
onHostConnectedToMultiplayer(session);
} else {
onReceiverConnectedToMultiplayer(session);
}

script.session = session;
}

Defining what happens when we connect

Next we can define the different flows that will be called.

For example, when we enter a solo session, we might want to invite others into it. We can call the shareSession we created earlier.

Take a look at the Connected Template to see an example of this in action, including UI examples.

function onHostConnectedToSolo(session) {
print('Host Connected Solo Session');

shareSession();
}

Then, once the session is shared, we might want to create a store where datas can be passed between participants:

function onHostConnectedToMultiplayer(session) {
print('Host Connected to Multiplayer Session');

createMultiplayerStore(session);
}

function onReceiverConnectedToMultiplayer(session) {
print('Receiver Connected to Multiplayer Session');

createMultiplayerStore(session);
}

There are different ways to create a data store which can be read by multiple participants.

Take a look at the following guides to see your options

Was this page helpful?
Yes
No

AI-Powered Search