Multiplayer Manager

MultiplayerManager is the entry point for the Connected Framework. Add one to your scene, give it a ConnectedLensModule asset, and it configures matchmaking and drives the Lens through its connection states.

Every other Connected Framework component depends on it. If a Sync Entity never becomes ready, the usual cause is a missing or unconfigured Multiplayer Manager.

Component Inputs

Name	Type	Description
Connected Lens	ConnectedLensModule	The Connected Lens module asset the session runs on. Required.
Singleplayer Mode	"mocked" or "manual"	Mocked Online simulates a multiplayer session while disconnected, which lets you use framework features in singleplayer. When starting a real session afterwards, existing Sync Entities need to be recreated. Defaults to Mocked Online.
Retry Attempts	int	Number of times to retry connecting. Connecting can fail from network errors, no players found, or other issues. Set to 0 to disable retries. Defaults to 3.
Disconnect Behavior	"keep_current_state" or "singleplayer"	What to do when disconnected. Keep current state leaves the state unchanged; Switch to Singleplayer returns to singleplayer. Mocked mode is restored either way if enabled. Defaults to Switch to Singleplayer.
Auto Start If Chat Drawer	boolean	If enabled, the session starts automatically when the Lens is launched from a DM or group chat, joining the users in that chat and skipping singleplayer. Never triggers inside the editor. Defaults to true.
Matchmaking
Min Players	int	Minimum players required to start the match. Lowest allowed value is 1. Defaults to 2.
Max Players	int	Maximum players allowed in the match. Highest allowed value is 64, and it must be at least 2 and greater than or equal to Min Players. Defaults to 4.
Target Players	int	Target number of players matchmaking attempts to fill. Must be between Min and Max Players. Defaults to 2.
Debug Options
Editor Start Online	boolean	Starts the multiplayer session automatically on Lens load, skipping singleplayer. Only effective inside the editor. Defaults to false.
Editor Extra Search Time	int	Set greater than 0 to simulate additional matchmaking wait time, in seconds. Editor only. Defaults to 0.
Editor Session Type	"chat_drawer" or "matchmaking"	Session type used inside the editor, where the launch context cannot be detected. Defaults to Matchmaking.
Debug Text	Text (optional)	Optional text component for on-screen connection state.
Logger Config	LoggerConfig	Log level configuration for the framework.

The matchmaking timeout is controlled by the backend, not by this component. The framework carries an estimate used only for driving UI, such as a progress bar.

Component API

Get the singleton with MultiplayerManager.getInstance(), or from the scene component with getMultiplayerManager().

Name (signature)	Description
playOnline(retryAttempts?: number): Promise<void>	Starts matchmaking and connects to a session. Defaults to the component's Retry Attempts.
getState(): MultiplayerState	Current state: initializing, singleplayer, searching_session, or multiplayer.
getSessionType(): SessionType	Whether this session came from chat_drawer or matchmaking.
getMinPlayers(): number	Configured minimum players.
getMaxPlayers(): number	Configured maximum players.
getTargetPlayers(): number	Configured target players.
getSessionController(): SessionController	The underlying Session Controller.
waitForReady(): Promise<void>	Resolves once the manager has finished configuring.

Events

Name	Called with	Description
onStateChange	newState, previousState	Fires on every state transition.
onSingleplayerStart	none	The Lens entered singleplayer.
onSearchingSessionStart	none	Matchmaking search began.
onMultiplayerStart	none	A multiplayer session is live.
onRetry	remainingAttempts, totalAttempts	A retriable failure occurred and a retry is being attempted.
onRetriesExhausted	lastError	A retriable failure used up every attempt. Terminal failures do not fire this.
onMatchmakingRejectedByClient	error	Matchmaking was rejected by the client. Retries are not attempted.
onPlayOnlineFailed	error	Connecting failed for any reason, whether retries were exhausted or the failure was terminal.

onSingleplayerStart, onSearchingSessionStart, and onMultiplayerStart are state-change events: if the state is already active when you subscribe, your callback runs immediately. That makes them safe to attach during onAwake without racing the connection.

Usage

import { MultiplayerManager } from 'ConnectedFramework.lspkg/Components/MultiplayerManager';

@component
export class PlayOnlineButton extends BaseScriptComponent {
  onAwake() {
    const manager = MultiplayerManager.getInstance();

    manager.onSearchingSessionStart.add(() => {
      print('Searching for players');
    });

    manager.onMultiplayerStart.add(() => {
      print('Match started');
    });

    manager.onPlayOnlineFailed.add((error) => {
      print(`Could not connect: ${error}`);
    });
  }

  startMatch() {
    MultiplayerManager.getInstance()
      .playOnline()
      .catch((error) => print(`playOnline failed: ${error}`));
  }
}

Testing in the editor

The Debug Options exist because the editor cannot detect a real launch context:

• Editor Start Online skips singleplayer so you land straight in a session.
• Editor Extra Search Time lets you see your matchmaking UI for long enough to check it, instead of the search resolving instantly.
• Editor Session Type decides whether the editor behaves like a chat launch or a matchmaking launch.

To test with more than one player, open a second Preview panel. Each Preview panel connects as its own participant.

Related

• Connected Framework overview
• Session Controller
• Multiplayer Game Starter Project