Skip to main content

Leaving and Rejoining Sessions

How Sync Kit leaves a Connected Lenses session when SPECS suspends a Lens or the Lens leaves, and what it restores when it joins again.

  • Snapchat: not supported
  • SPECS: fully supported
  • Camera Kit Web: not supported
  • Camera Kit Mobile: not supported
1 platform note

Platform details

When Sync Kit leaves a session

Sync Kit leaves its Connected Lenses session in two cases, and joins again afterwards:

  • SPECS suspends the Lens, for example when the user opens the Home screen or another Lens. Sync Kit leaves before the Lens freezes, so other users don't see a frozen user who still owns content. When the Lens comes back, Sync Kit joins again on its own. Every Sync Kit Lens leaves on a suspension; there is no setting to turn it off.
  • The Lens calls SessionController.getInstance().leaveSession(), for example from a Leave button. Sync Kit then shows the Start Menu, except in Off start mode.

Other users stay in the session and keep their copies of the shared content. The events and leaveSession() are listed in the Session Controller reference.

How a leave and a return unfold

When Sync Kit leaves a session, the SessionController events fire in this order:

  1. onWillBecomeInactive(reason) fires while the Lens is still in the session. reason is "suspended" or "userLeft".
  2. Sync Kit leaves the session, and onSessionLeft(reason) fires.
  3. Sync Kit clears its local session state, as described in What Sync Kit clears on a leave. After a suspension, it clears it when the Lens comes back, before the first frame renders.

When Sync Kit joins again:

  1. After a suspension, Sync Kit joins on its own. It returns to the session the Lens left if the Lens comes back within 5 minutes and the session is still running. After leaveSession(), choosing Multiplayer shows the session selector.
  2. When the join is ready, onSessionResumed() fires if Sync Kit is back in the session it left, and onReady fires if it is in another session.
  3. If the return after a suspension can't join, onConnectionFailed fires, then onSessionResumeFailed(reason). Sync Kit shows the Start Menu with a connection alert, except in Off start mode, where the Lens shows its own UI and can join again from onSessionResumeFailed.

What Sync Kit clears on a leave

When Sync Kit leaves a session, it clears its local session state:

  • SyncEntities let go of their stores.
  • The user and host lists are emptied.
  • Objects spawned by an Instantiator are destroyed, on this device only.
  • Content under SetEnabledOnReady is hidden.
  • A colocated Lens goes through relocalization again on the next join, except with a custom landmark.

Sync Kit deletes nothing on the server: the session's stores stay for the other users. State that the Lens's own scripts keep is not reset; reset it in onReady, as described in A join into another session.

Content with Owner persistence after a leave

Stores with Owner persistence go with their owner. When a user leaves, the server deletes the stores that user owned, and the other users destroy their copies. Sync Kit destroys the leaving user's own copies too: each SyncEntity, with the scene object it is on.

  • An Instantiator's Auto Instantiate prefabs that this user owns, with Auto Instantiate Ownership set to Owned or Spawner Owns Object enabled, come back on their own: Sync Kit instantiates them again on the next join, into the same session or another.
  • Nothing else with Owner persistence comes back. To bring it back, create it again in onSessionResumed, or in onReady after a join into another session.

A return to the same session

When Sync Kit returns to the session it left, onSessionResumed() fires instead of onReady:

  • SyncEntities bind to the session's stores and take their current values.
  • Objects an Instantiator spawned that are still in the session are spawned again, as when joining mid-session.
  • Stores other than this user's Owner stores remain in the session unless another user deletes them, but ownership is not preserved across a leave. A SyncEntity created with claimOwnership automatically requests ownership again on each join. For an entity that claimed ownership later, call tryClaimOwnership() in onSessionResumed if ownership is still needed. If another user owns the store, the request waits until they release it. Do not assume ownership has been regained when onSessionResumed fires; listen to SyncEntity.onOwnerUpdated and check doIOwnStore() before performing owner-only actions.

If the Lens left before its first onReady, which comes a fraction of a second after joining, the return fires onReady instead of onSessionResumed.

A join into another session

When Sync Kit joins a different session after a leave, the Lens starts as on a first join, and onReady fires:

  • SyncEntities start from their starting values, the values they had when each was first set up.
  • A SyncEntity created with claimOwnership creates its store owned.
  • An Instantiator's Auto Instantiate runs again.
  • PositionInitializer places its object in front of the user again, for the session's first joiner only by default.

Reset the Lens's own state in onReady too.

Run session setup in every session

OnStartEvent fires once per Lens run, so setup done there isn't redone in the session after a leave. A script under SetEnabledOnReady content first starts when that content is first shown, so its OnStartEvent also runs once only. Do session setup in an onReady listener instead:

  • SessionController.getInstance().onReady.add(...) runs on the first join and on each join into another session.
  • SessionController.notifyOnReady(...) does the same when called before Sync Kit is ready. Called once it is ready, it runs its callback right away and never again.
  • SyncEntity.notifyOnReady(...) and Instantiator.notifyOnReady(...) follow the same rule: a callback registered before setup finishes runs on the first setup and again in each other session, not on a return to the same session, so content created there isn't created twice.
  • SyncEntity.onSetupFinished fires on every setup, returns to the same session included.

Handle a leave in a Lens

The Sync Kit package includes this script as Examples/LeaveSessionExample.ts: a Leave button and a handler for each event. Assign a UI Kit button to Leave Button in the Inspector.

import { BaseButton } from 'UIKit.lspkg/Scripts/Components/Button/BaseButton';
import { LeaveReason, SessionController } from 'SyncKit.lspkg/Core/SessionController';
import { SyncEntity } from 'SyncKit.lspkg/Core/SyncEntity';

/**
* Leaving and rejoining a session: a Leave button, and what a Lens does on each lifecycle event. The SyncEntity stands
* for shared content this user claims, such as a panel they control.
*/
@component
export class LeaveSessionExample extends BaseScriptComponent {
// Created to request ownership on every join, including after a leave.
private syncEntity: SyncEntity = new SyncEntity(this, null, true);

@input()
leaveButton: BaseButton;

onAwake(): void {
const sessionController = SessionController.getInstance();

// Leaves from inside the Lens: Sync Kit clears its session state and shows the Start Menu, except in Off start mode.
if (this.leaveButton) {
this.leaveButton.onTriggerUp.add(() => sessionController.leaveSession());
}

// addWhileAlive: SessionController outlives this script, which a leave may destroy; its listeners go with it.
sessionController.onWillBecomeInactive.addWhileAlive(this, (reason) => this.onWillBecomeInactive(reason));
sessionController.onSessionLeft.addWhileAlive(this, (reason) => this.onSessionLeft(reason));
sessionController.onSessionResumed.addWhileAlive(this, () => this.onSessionResumed());
sessionController.onSessionResumeFailed.addWhileAlive(this, (reason) => this.onSessionResumeFailed(reason));

// Runs on the first join, and again on a join into another session after a leave.
sessionController.onReady.addWhileAlive(this, () => this.onReady());

// A return does not guarantee ownership: check doIOwnStore() when onOwnerUpdated fires.
this.syncEntity.onOwnerUpdated.addWhileAlive(this, () =>
print(`Owner of the panel: ${this.syncEntity.doIOwnStore()}`)
);
}

private onWillBecomeInactive(reason: LeaveReason): void {
// Use this callback for local cleanup only. Sending storage updates or events to other users here is not supported.
print(`About to leave the session (${reason})`);
}

private onSessionLeft(reason: LeaveReason): void {
// Out of the session. "suspended": Sync Kit joins again when the Lens comes back. "userLeft": the Start Menu comes
// back next, except in Off start mode.
print(`Left the session (${reason})`);
}

private onReady(): void {
// A new session, or the first one: start the Lens's own state from scratch. After a leave, this is also where to
// create again any Owner-persistence content this user had: the leave destroyed it.
print('Ready in a session');
}

private onSessionResumed(): void {
if (SessionController.getInstance().isSingleplayer()) {
// Single player: the suspension kept the session and everything in it; there is nothing to create again.
print('Back in the single player session');
return;
}
// Back in the session left, with its synced values. Content with Owner persistence that this user owned was
// destroyed with the leave: create it again here to bring it back.
print('Back in the session');
}

private onSessionResumeFailed(reason: string): void {
// The session the Lens left has ended, or the Lens was away too long. Sync Kit shows the Start Menu, except in Off
// start mode, where the Lens shows its own UI.
print(`Could not return to the session: ${reason}`);
}
}
  • The script listens with addWhileAlive(this, ...), so its listeners are removed when the script is destroyed. A leave destroys this user's Owner content, and SessionController outlives it.
  • onReady and onSessionResumed are where a Lens creates its Owner content again.
  • onSessionResumed checks isSingleplayer() first: a single player session keeps everything through a suspension, as described in Single player sessions and suspensions.

Single player sessions and suspensions

With Single Player Type set to Mocked Online in the Start Menu, a suspension doesn't leave the single player session: there are no other users. Sync Kit fires onWillBecomeInactive("suspended"), then onSessionResumed() when the Lens comes back, with everything kept and no onSessionLeft. Nothing was destroyed, so a Lens that creates its Owner content again in onSessionResumed skips that in a single player session: check SessionController.getInstance().isSingleplayer().

leaveSession() ends a single player session. Choosing Singleplayer or Multiplayer afterwards starts again and fires onReady.

Limits

  • Remote updates during a leave: sending updates to other users from onWillBecomeInactive is not supported. This includes storage property updates and events. Send shared-state updates while the session is active, before leaving. Use onWillBecomeInactive for local cleanup only.
  • Return window: after a suspension, Sync Kit returns to the session the Lens left only within 5 minutes, and only while the session is still running. Otherwise onSessionResumeFailed fires.