Player Sessions and Identity

Scene handoff and authority

CouchCoopBootstrap preserves MultiplayerCoordinator, joined PlayerSession instances, character-selection IDs and the input services across scene transitions when its lifetime is PersistAcrossScenes. Those services retain the actual session InputUsers and actions. PersistentScenePrototype remembers the origin lobby and loads a selected gameplay scene; returning reconstructs scene presenters. Ready is scene-local and resets; character selection persists until explicit Leave.

The Setup Wizard selects a gameplay scene and configures the persistent transition. Configure gameplay representations and input separately on that scene’s components; the Wizard does not choose a resolution mode, author spawn points, or configure input adapters. Its optional Cameras step works with an existing Gameplay Player Setup. Selection previews instantiate presentation content separately from gameplay.

GameplayPlayerContext references the authoritative session. The bootstrap-owned GameplayPlayerContexts collection is a read-only projection, not another session store. It retains no scene gameplay objects.

Public access

After initializing your bootstrap, access bootstrap.GameplayPlayers. Code without an injected bootstrap can use CouchCoopBootstrap.Active explicitly:

using LevelArgento.CouchCoopBuilder;

CouchCoopBootstrap bootstrap = CouchCoopBootstrap.Active;
if (bootstrap != null && bootstrap.IsInitialized &&
    bootstrap.GameplayPlayers.TryGetPlayer(0, out GameplayPlayerContext player))
{
    int index = player.PlayerIndex;                  // Zero-based, 0 through 7.
    System.Guid sessionId = player.SessionId;       // Stable until Leave.
    string selectedId = player.SelectedCharacterId;
    CharacterDefinition character = player.CharacterDefinition;
    if (player.TryGetInputUser(out var user))
    {
        // Consume existing ownership; do not pair a new user here.
        foreach (var device in user.pairedDevices) { /* Your integration. */ }
    }
}

P1–P8 are one-based UI labels for zero-based PlayerIndex values 0–7. InputSlot identifies the input role/source; it is not a persistent controller or binding-profile identity. Saved input overrides belong to Input Binding Profiles, never a reusable PlayerIndex.

Lookup accepts either PlayerIndex or session Guid. Players is ordered by ascending PlayerIndex and may contain gaps after Leave: list position is not necessarily PlayerIndex. A returning controller after intentional Leave receives a new session at the lowest available index under the existing policy. Surviving contexts, IDs and indexes do not move. Cache a context for the lifetime of that session, not for an assumed permanent controller player number.

InputUser is the existing user, never a new pairing. PairedDevices reports current pairing; Keyboard A and B have distinct users but intentionally share the keyboard device. Read IsJoined and IsInputAvailable separately: a disconnected controller can reserve a joined session while input is unavailable. An ended session exposes an invalid default InputUser. Re-read pairing/availability when needed; do not retain a snapshot as proof of connection or use inactivity as disconnection evidence.

CharacterDefinition resolves the selected ID against the current configured catalog only if that ID has one match. It does not require GameplayPrefab. CharacterStatus distinguishes no selection, resolved metadata and unresolved metadata. TryGetCharacterDefinition(out definition, out failureMessage) explains missing catalogs, missing IDs and ambiguity. Missing metadata does not invalidate session/input ownership or block custom resolution. API-only mode produces no configuration errors for absent objects or character metadata.

Built-in lobby selection requires a fully valid catalog, including Gameplay Prefabs. Context metadata lookup is independent of that lobby rule. The built-in Spawn Selected Character strategy requires the selected definition to have GameplayPrefab; Existing Objects, Custom Provider and API Only do not check that requirement.

Selected Character IDs and session ownership persist across lobby/gameplay scene changes. Ready belongs to the current lobby UI. Intentional Leave ends a session; physical Device Lost keeps its reservation. Advanced recovery and reversible Drop Out rules are explained in Session Lifecycle.