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:
- Shared via Friends List (
ConnectedLensModule.SessionShareType.Invitation
) - 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 experienceonHostConnectedToMultiplayer
which will be called once the Lens has been shared and aMultiplayerSession
is createdonReceiverConnectedToMultiplayer
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