Session Controller

SessionController is the scripting API for the live session. Where Multiplayer Manager is the component you configure in the Inspector, Session Controller is what you call from code to ask who is in the match, who the host is, what the server time is, and to react as players join and leave.

It is a singleton. Get it with SessionController.getInstance(), or from the Multiplayer Manager with getSessionController().

Local user

Name (signature)	Description
getLocalUserId(): string | null	Persistent user id for the local player.
getLocalConnectionId(): string | null	Connection id for this session only. Changes between sessions.
getLocalUserName(): string | null	Display name for the local player.
getLocalUserInfo(): ConnectedLensModule.UserInfo | null	Full user info for the local player.
isLocalUser(userInfo): boolean	Whether the given user is the local player.

Use the user id when you need identity that survives a reconnect, such as a persistent score. Use the connection id when you mean "this participant in this session." They are not interchangeable, and a single user id can appear more than once, which is why getUsersByUserId() returns an array.

Host

Name (signature)	Description
isHost(): boolean | null	Whether the local player is the host.
getHostUserId(): string | null	Persistent user id of the host.
getHostConnectionId(): string | null	Connection id of the host.
getHostUserName(): string | null	Display name of the host.
getHostUserInfo(): ConnectedLensModule.UserInfo | null	Full user info for the host.
isHostUser(userInfo): boolean	Whether the given user is the host.

The host can change mid-session when the current host leaves. Listen to onHostUpdated rather than caching the result of isHost().

Users

Name (signature)	Description
getUsers(): ConnectedLensModule.UserInfo[]	Every user currently in the session.
getUserById(userId: string): ConnectedLensModule.UserInfo | null	Look up a user by persistent user id.
getUserByConnectionId(connectionId: string): ConnectedLensModule.UserInfo | null	Look up a user by connection id.
getUsersByUserId(userId: string): ConnectedLensModule.UserInfo[]	Every participant sharing one user id.

Session state

Name (signature)	Description
getSession(): MultiplayerSession | null	The underlying session object.
getState(): State	Current session state.
getSessionCreationType(): ConnectedLensSessionOptions.SessionCreationType	How this session was created.
isSingleplayer(): boolean	Whether the Lens is running without a real session.
getIsSessionShared(): boolean	Whether the session has been shared with others.
shareInvite()	Opens the invite flow so the local player can bring friends in.
getIsReady(): boolean	Whether the controller has finished initializing.
waitForReady(): Promise<void>	Resolves once the controller is ready.
leaveSession()	Leaves the current session.
getIsConnectionFirstJoiner(): boolean	Whether this connection was the first to join.
getIsUserFirstJoiner(): boolean	Whether this user was the first to join.

Server time

Name (signature)	Description
getServerTimestamp(): number | null	Current server timestamp.
getServerTimeInSeconds(): number | null	Current server time in seconds.

Use server time, not local device time, for anything every client must agree on: round countdowns, match duration, and finish times. Device clocks drift.

Realtime stores

Name (signature)	Description
getSessionStore(): GeneralDataStore | null	The session-wide store, shared by every participant.
createStore(storeOptions: RealtimeStoreCreateOptions): Promise<GeneralDataStore>	Creates a new realtime store.
getTrackedStores(): StoreInfo[]	Every store the controller is tracking.
getStoreInfoById(networkId: string): StoreInfo | null	Look up a tracked store by network id.

Most gameplay code should not touch stores directly. Prefer Sync Entity and Storage Property, which manage a store for you and give you change events.

Events

Name	Called with	Description
onReady	none	The controller finished initializing.
onSessionCreated	session, creationType	A session was created.
onSessionShared	session	The session was shared.
onConnected	session, connectionInfo	The local player connected.
onDisconnected	session, disconnectInfo	The local player disconnected.
onUserJoinedSession	session, userInfo	A player joined.
onUserLeftSession	session, userInfo	A player left.
onHostUpdated	session, removalInfo	The host changed.
onMessageReceived	session, userId, message, senderInfo	A network message arrived.
onError	session, error	A session error occurred.
onConnectionFailed	error	Connecting failed.
onRealtimeStoreCreated	session, store, persistence, ownerInfo, ownership	A realtime store was created.
onRealtimeStoreUpdated	session, store, key, updateInfo	A realtime store value changed.
onRealtimeStoreDeleted	session, store, deleteInfo	A realtime store was deleted.
onRealtimeStoreKeyRemoved	session, store, removalInfo	A key was removed from a store.
onRealtimeStoreOwnershipUpdated	session, store, ownerInfo, ownershipUpdateInfo	Store ownership changed.

Usage

import { SessionController } from 'ConnectedFramework.lspkg/Core/SessionController';

@component
export class RosterDisplay extends BaseScriptComponent {
  onAwake() {
    const session = SessionController.getInstance();

    session.onReady.add(() => {
      print(`Players in session: ${session.getUsers().length}`);
    });

    session.onUserJoinedSession.add((_session, userInfo) => {
      print(`${userInfo.displayName} joined`);
    });

    session.onUserLeftSession.add((_session, userInfo) => {
      print(`${userInfo.displayName} left`);
    });

    session.onHostUpdated.add(() => {
      if (session.isHost()) {
        print('This client is now the host');
      }
    });
  }
}

Advanced

Name (signature)	Description
addSessionOptionsModifier(modifier: SessionOptionsModifier): SessionOptionsModifier	Registers a modifier applied when session options are built.
removeSessionOptionsModifier(modifier: SessionOptionsModifier): void	Removes a previously registered modifier.
createSessionOptions()	Builds the session options, with every registered modifier applied.

Related

• Multiplayer Manager
• Sync Entity
• Connected Framework overview