Skip to content

Latest commit

 

History

History
545 lines (445 loc) · 35.2 KB

multiplayer.md

File metadata and controls

545 lines (445 loc) · 35.2 KB

Multiplayer with PlayFab Lobby and Party

This page is for Godot developers learning how NetRumble uses Lobby, Party and XBOX activity. You can skip maintainer notes marked as editing instructions unless you are changing that code path.

PlayFab Lobby discovers sessions and carries the Party descriptor. PlayFab Party authenticates peers and carries Godot gameplay traffic plus its separate voice/text channel. XBOX multiplayer activity makes that Lobby session discoverable through friends and invites. The retained Matchmaking implementation supports PlayFab tickets, automatic full-group Private Start and rematches; Matchmaking documents that lifecycle. Its main-menu entry is not exposed in the current build, but its backing code and screens remain.

See also: Architecture · Platform Services · Configuration · Matchmaking foundations · Walkthroughs. The README matrix defines environment coverage.


Connection flows

Services owns PartyService and ChatService. NetManager obtains them through Services.party() / Services.chat(), resolves multiplayer/communication privileges, then attaches the returned PlayFabPartyPeer to Godot's MultiplayerAPI.

Before any of these operations, Services must have an identified account and successfully initialized/loaded Game Saves. That gate applies to direct session calls, existing-user paths, Practice and any fallback after a failed host/join, not only menu navigation. Authentication alone or a lower-level unchecked privilege verdict cannot enable gameplay.

Host

  1. NetManager resolves the current multiplayer privilege through _multiplayer_privilege_denial(). See Privileges.
  2. The sample wrapper PartyService.host() initializes Party and PlayFab Multiplayer, completes active-session cleanup, and generates a five-character code.
  3. ChatService.ensure_control() calls PlayFab.party.chat.create_local_chat_control_async() before the network call, when communications are allowed.
  4. PlayFab.party.create_and_join_network_async(user, config) creates the network; the code is its invitation id. The wrapper waits for the descriptor, then calls PlayFab.multiplayer.create_lobby_async(): string_key1 is the code, string_key2 the game mode, string_key3 the protocol version, and party_descriptor a member-visible property.
  5. NetManager attaches the peer; PlatformSession advertises the Lobby connection string through XBOX activity so Join Friend can find it.
  6. The host waits in the lobby. When all members are ready, the sample starts the match automatically (a solo lobby is guarded against immediate start).

Join by lobby code

  1. NetManager resolves the current multiplayer privilege through _multiplayer_privilege_denial().
  2. The sample wrapper PartyService.join() normalizes the code. _find_lobby() makes one PlayFab.multiplayer.find_lobbies_async() lookup for string_key1. Search is eventually consistent and rate-limited; a miss ("No match found for code …") returns to the still-editable code entry so the player can correct it or retry. No automatic backoff loop runs. A search that fails is not a miss: its HRESULT goes through the same player-facing table as a join refusal (rate limit, expired sign-in, service error), falling back to "Could not look up that join code."
  3. If the selected result's member_count has reached its max_member_count, the join stops with "That match is full." before any Lobby or Party call. PlayFab documents no lobby-full error, so matching search counts are the only signal that can say so. They are a snapshot, not a reservation: when Lobby join reports "not joinable", the title makes one fresh search for the exact connection string. Only a full result changes the message to "That match is full"; a locked, ended, uncounted or missing destination keeps the mapped refusal. A capacity of 0 is treated as unknown, never as full.
  4. PlayFab.multiplayer.join_lobby_async() attaches the Lobby. The wrapper checks its protocol version before reading party_descriptor and joining Party.
  5. After ensuring a local chat control, PlayFab.party.join_network_async() uses that descriptor and the same code as invitation id. NetManager attaches the peer and exchanges the roster.
  6. The client reaches the lobby. A code-join attempt has a 45-second overall timeout (NRConst.JOIN_CODE_TIMEOUT_SECONDS); descriptor waits are independently bounded at 20 seconds. Cancel/timeout invalidates pending work so a late SDK result cannot seat a canceled join.

Every join failure shows a title-owned string, never the SDK's message; the SDK's HRESULT, code and message go to the [Party] <stage> failed (…) warning instead. See PartyService.JOIN_FAILURE_MESSAGES.

Join by friend / invite

  1. Services.joinable_friends() combines the XBOX social graph with multiplayer activities. The selected activity carries a Lobby connection string, not a Party descriptor.
  2. NetManager.join_by_invite() calls the sample PartyService.join_by_connection_string(). It skips code search, not Lobby join: PlayFab.multiplayer.join_lobby_async() still validates the session/version and supplies the code/descriptor for PlayFab.party.join_network_async().
  3. For shell activations — an invite sent from the title or the XBOX shell, or a shell Join Game — the activation URI carries the host's Lobby connection string: ms-xbl-<titleId>://inviteAccept?invitedUser=…&sender=…&connectionString=… on console, ms-xbl-multiplayer://inviteAccept?… on PC. ActivityService reads it from the raw URI and percent-decodes it exactly once. It never uses String.uri_decode(), nor the addon's pre-parsed fields built with it: that turns + into a space and drops the % of a lowercase escape, and a mangled string fails Lobby join. Accepted invites, pending invites and protocol URIs all become one request. InviteRouter buffers it until account/save readiness and the acquire screen have completed; an older activation that names only the host (sender, senderXuid, joineeXuid) is resolved to a connection string from their XBOX activity. Every activation logs its URI and a parsed: summary under [Activity]. The URI line keeps each query key but shows only the value's length: the connection string is a lobby join credential and XUIDs identify players.
  4. A cold-launch request expires after five minutes. Back abandons acquisition without joining. Save-loading failure offers Retry/Back, not a route around readiness. An invite received while already playing asks before leaving the current session.

Invite diagnostic builds

[InviteTrace] follows the route after the redacted [Activity] receipt. It is transition-only logging, enabled in release builds too; it does not change sign-in, confirmation, cleanup, admission or navigation. stage=build reports the existing export stamp and protocol. A dirty stamp identifies modified source, not a new commit; keep the build's source/artifact manifest with its logs.

attempt is a process-local invite sequence, retained while an invite waits for cleanup. join_handle links it to NetManager's process-local join ID. JoinRequest records include elapsed milliseconds and numeric outcomes: 0 pending, 1 succeeded, 2 cancelled, 3 superseded, 4 failed. IDs are local counters, not account/session credentials. cleanup_observed is the last state already read by routing, or unknown: diagnostic printing never invokes cleanup or recovery to obtain a fresher value.

Last stage What to investigate
No [Activity] receipt Registered package identity, activation subscription and shell delivery
pending_accept_start without pending_accept_succeeded Pending-invite acceptance; distinguish explicit failure from an unfinished call
received, then wait_account, wait_acquisition, wait_frontend or wait_cleanup The named prerequisite, not URI parsing
privilege_denied or replacement_declined Intentional refusal; the existing UI supplies the reason
host_lookup / destination_unavailable Host-only activation lookup, or ended/unavailable activity
lobby_party_connect without a result Lobby/Party connection work; correlate existing [Party] warnings
awaiting_admission without host_admitted Host admission/identity handshake
join_succeeded then session_not_live Session ended before navigation
lobby_navigation then lobby_selected Lobby selected on the screen stack; still verify visible roster and gameplay on hardware

New trace lines contain only stages, booleans, local counters, timing, fixed screen/state labels and credential lengths. They do not print raw URIs, connection strings or their hashes, XUIDs, gamertags, entity IDs, SDK payloads, or free-form failure messages. Keep existing [Party] warnings and the visible error alongside the trace when reporting a failure; review pre-existing logs for personal data before sharing.

Capture from process startup, not just the moment of acceptance. On PC, copy user://logs/godot.log (normally %APPDATA%\Godot\app_userdata\NetRumble\logs\godot.log) before another launch rotates it. On Xbox, capture the title's debug output using the authorized devkit debugger/GDK tooling, including startup for a cold launch; do not assume the PC filesystem path exists on console. Keep both host and recipient logs, build stamps, platform, sandbox, starting screen, invitation source and visible outcome together. See the diagnostic retest matrix.

The same opaque connection-string path has three explicit Matchmaking destinations. Ordinary hosted lobbies keep the behavior above; an unlocked matchmaking staging Lobby is admitted only while Gathering; and an arranged Lobby is admitted only during a valid rematch_gathering round. Searching/bootstrap/gameplay/locked/incompatible candidates are left before Party authentication. A rematch replacement joins the retained arranged Lobby/network with the shared NetRumble invitation id and creates neither a ticket nor a new arrangement.

Join Friend and shell invites require a registered XBOX session. Missing XBOX friends or activity is explained in the UI. An ended/full/in-progress/incompatible session can still refuse a valid-looking activation. See the invite walkthrough.

Full sessions are left out of Join Friend (ActivityService.joinable_activities() drops an activity whose current_players has reached max_players), which is why its empty state speaks of joinable matches. Hosted-match activities also carry the join code beside the opaque Lobby connection string in a versioned title-defined value (nr1:<code>:<connection string>), provided the complete value is under Xbox's 512-character limit. The invite path searches by that code but uses counts only when the returned connection string exactly matches the invitation; it always joins the connection string supplied by the activity. Older activities without the envelope still join as before, but cannot provide full-lobby diagnostics. The fresh lookup after a "not joinable" result covers a lobby that filled between the activity/search snapshot and Lobby admission.

Both join paths reach the host through _on_peer_connected(), so both are refused the same way if the match has already started — see Closing a match to newcomers. The refusal arrives as an ordinary disconnect carrying JOIN_REJECTED_IN_PROGRESS, which the pending join reports directly rather than opening an empty lobby.

Leave and loss

NetManager first clears _peer and synchronously detaches Godot's multiplayer peer, without calling peer.close(). PartyService alone releases the native session: clear the host's advertised descriptor, leave Lobby/Party and detach listeners. The local chat control is deliberately left alone — it belongs to the signed-in player rather than to the match, so it is retained and reused by the next one; see Chat. Its serialized leave() lets overlapping exits/rejoins await the same teardown rather than leave the native network twice. PlatformSession retires XBOX activity/presence. The in-match chat display is invalidated immediately, without waiting for remote cleanup. Host loss ends clients' sessions and returns them to the main menu; a completed match returns to the lobby. Suspend abandons local state synchronously rather than awaiting these calls. See lifecycle and terminal loss.

Host departure is observed through both Party's peer-left notification and Godot's transport notification. Hosted-lobby state changes also recheck the pinned host's ownership and connection status, even when no further gameplay message arrives. These routes stay active during loading, the countdown and behind popups; teardown is deferred until the native notice returns.

An already-admitted ordinary hosted/code/invite session may continue when only that client's local Lobby notification connection is lost while its Party transport, session identity and pinned host remain unchanged. This is continuity of an established session, not fresh Lobby proof: a join still awaiting admission is refused, known host loss/change still ends the match, and scoped Matchmaking staging/arranged Lobby loss remains terminal.

Scoped matchmaking calls have a separate lifetime from their screens. Each native create/join/prepare/transport/lock/post call has an absolute shared-clock deadline and an operation handle. A timed-out caller can stop waiting while the late native result remains owned; that result may only release its captured Lobby/network. A failed scoped Lobby or Party leave returns its service error but remains cleanup-pending until confirmed multiplayer recovery; a failed recovery keeps online entry closed until restart. An unexpected scoped Lobby disconnect or owner change reports context_lost, independently from Party network_lost. If #14's terminal cleanup confirms a PlayFab Multiplayer shutdown/reset, the service advances its recovery epoch and invalidates old ticket work before new online entry is allowed.

Cleanup-pending and cleanup-running are separate facts. A retained failed leave still blocks new online work while idle, but an available lifecycle owner starts the existing recovery immediately; Quit waits for cleanup that is actually executing rather than spending its budget on an inert obligation.

Arming matchmaking handoff changes only how loss of the captured old Party transport is routed. An unexpected staging context_lost remains terminal before or after arming, as does any arranged Lobby loss. Expected staging Lobby teardown is an owned leave_lobby() retirement, which disconnects the state callback before native leave and emits no context_lost.

Known blocker: microsoft/XBOX-Godot-Sample#169 The pinned addon's PlayFab.party.chat.destroy_local_chat_control_async() await did not resolve in the observed live run. Session leave retains the chat control across matches, so leave/rejoin does not wait on that call. The addon defect itself is unfixed: the call still runs at title exit, where main.gd::_quit_now() holds it inside the shutdown drain so it can delay an exit but not hang one. Quitting immediately after a voice match has not been retested since that change, and no native edit, fire-and-forget destruction or forced-exit workaround is included.


PlayFabPartyPeer

PlayFabPartyPeer derives from MultiplayerPeerExtension, making it a drop-in Godot MultiplayerPeer. Every @rpc in net_manager.gd is ordinary Godot RPC. Only the peer construction is PlayFab-specific, and it lives entirely in scripts/services/party_service.gd.

Build from Sample addon revision 2accce554e0988e5076ac76d22f024307f6744c6 pinned by this repository and record that revision with the rebuilt package validation results.


PartyService details that are easy to get wrong

Two details in PartyService are easy to get wrong and produce errors that are not obviously related to the mistake:

The join code is the Party invitation id

PartyNetwork::AuthenticateLocalUser rejects any client whose invitation identifier differs from the host's. Leaving PlayFabPartyConfig.invitation_id empty makes the addon generate an opaque value that cannot be forwarded to joining clients.

The five-character join code is mutually known: the client types it, so it is minted before the network is created and passed on both sides. Getting this wrong produces:

AuthenticateLocalUser: invalid argument specified

Matchmaking cancellation and detailed failures

Ticket status, cancellation completion and detailed service cause are separate. The title keeps an abandoned ticket owned until native terminal truth and the cancel operation have both settled, or a confirmed Multiplayer reset invalidates that runtime. A Matched ticket is never relabelled Cancelled and never starts a match after the player has bound a leave/cancel intent.

The supported addon publishes one terminal ticket event and preserves the cached snapshot after native retirement. If Matched wins a cancel race, the completion returns that matched snapshot; the title preserves the player's stop intent, releases the observer and needs no routine service reset. Confirmed runtime recovery remains a bounded safety net for native work that is explicitly unanswered or fails.

Terminal failure forwards its native HRESULT, so the title can identify the queue's ticket-size rejection. Generic early E_FAIL wrappers remain generic Matchmaking failures and are not relabelled from message text. A full group normally starts privately before ticket creation; an unexpected maximum-sized ticket failure remains a failure, not a late route-selection signal.

For the first matchmade start, the arranged Lobby stays private and unlocked while matched callers arrive and join the fresh Party network. The owner starts with the current 2-4 present members only after every present member is connected, admitted, compatible and finished with staging cleanup. A present member still connecting blocks selection; a known incompatible present member ends the initial attempt. No timer waits for an unknown assigned total.

A full ready group of four takes a different path before ticket creation. The title locks its current staging Lobby and changes only its access, kind and private owner control. The same Lobby, Party network, descriptor, peer and owner become the private play session; there is no arrangement, new transport or room code. All four remain required through the first countdown and loading.

Once the owner selects a matchmade start set, admission closes, the native Lobby is locked and that exact set is rechecked through loading. Later arrivals cannot join that round and may need to search again. Private Start similarly keeps its captured four fixed through first RUNNING.

Results return either origin to the same capacity-four play session for hosted ready-up rounds rather than automatically starting another search. Those rounds use two to four current humans, are invite-only while open, and accept compatible replacements through the retained Lobby and Party network. A private replacement carries the private session id before Party entry; a matchmade replacement carries the match id.

find_lobbies_async resolves to PlayFabLobbySearchResult

find_lobbies_async does not resolve to an array. The summaries are on the result's lobbies member. Treating result.data as an Array silently yields zero matches with no error.


Voice chat

The lobby is voice-only and has no text history. Microphone icons report availability/mute state, not proof of audible communication. Voice lives in scripts/services/chat_service.gd, separate from the transport: PartyService enables enable_voice_chat on the network config and owns when a chat control may exist, while ChatService owns everything the control then does. See Privileges.

Maintainer note: two things are worth knowing before editing the voice path:

  • The local chat control must exist before the network join. create_local_chat_control_async is decoupled from create_and_join_network_async / join_network_async, and a network join never creates one. ChatService.ensure_control() is therefore called from both the host and join paths before the network call. Creation is serialized with ordinary destruction and canceled-control cleanup: a replacement cannot be created until the active control's destruction completes.
  • Talking indicators must be polled. NetManager samples Party voice activity every 100 ms and repaints the lobby and gameplay squawkers only when an indicator changes. ChatService uses the owning user's local indicator and each remote entity's incoming indicator; title/platform mutes take precedence. Speech repaint does not re-evaluate privacy or write chat permissions. An icon still cannot prove audible communication: hear a distinct phrase in both directions on two audio endpoints.

The local microphone starts muted so enabling voice never opens a live mic unasked. In the lobby, T (or gamepad Y) toggles it. Self-mute is implemented by dropping SEND_AUDIO from the chat permissions of every remote entity. During gameplay, V / D-pad Up toggles the microphone directly without opening a menu; T / gamepad Y remains typed-text entry. The voice shortcut does not run while the text entry is open or gameplay is covered by another screen, and cannot override Xbox communication restrictions.

The local muted icon reports the title's self-mute choice, not a missing headset or a device initialization error. If speech still fails after unmuting, inspect Party's get_audio_input_state(), get_audio_output_state(), get_local_chat_indicator() and the per-peer get_chat_permissions() on both endpoints, along with native audio-setup warnings. Successful control creation does not guarantee initialized capture or playback. See addon packaging for how the title selects system-default devices on PC and platform-user-default devices on console despite using the same addon DLL.


Chat

During a match, open_voice_chat (T / gamepad Y) opens the existing typed-text entry, including the console system keyboard. The gameplay HUD has four recent messages, not a chat window with scrollback. In the lobby, the same action still toggles the microphone.

NRChatEntry → NetManager.send_chat_message → Services.verify_chat_text
            → ChatService.send_chat_text → PlayFab.party.chat.send_text_async
            → one local echo after successful SDK submission

PlayFab.party.chat.text_message_received(entity_key, message)
  → ChatService.text_received: text policy, length and lifecycle validation
  → NetManager.chat_message_received: authenticated Party sender → current roster peer
  → gameplay screen → NRChatLog: sender label + plain text

Outgoing moderation uses XBOX string verification when an XBOX user/service is available. last_chat_error explains unavailable chat, no eligible recipients, moderation refusal, changed sessions or failed Party submission. Failed sends keep the entry text and show the error; they do not add a successful local row.

CHAT_PERMISSION_RECEIVE_TEXT is granted independently of voice permissions. A muted microphone or voice-only player/platform mute does not deny typed text. XBOX text policy must resolve before new text is admitted; missing, failed or denied text verdicts exclude send targets and suppress received messages. Missing/failed query results are not cached as permanent denials; a later evaluation can obtain a real verdict. The voice-query fallback is unchanged. Account-cache invalidation clears retained text while policy is re-evaluated. Roster removal immediately removes that peer from eligible recipients, even if its Party chat control remains. An empty target list fails explicitly because the addon treats an empty array as broadcast.

Only message.text from a valid typed-text event is shown: never original_text, translations, transcriptions or sender-supplied markup/identity metadata. The sender is matched to the current roster through PartyService.entity_key_for(peer_id), not PlatformSession's replicated identity fallback. Labels use PlayerState.display_label() and its verified-name path. Unknown, stale or restricted senders are not displayed.

The entry and service boundaries enforce 100 characters. NRChatLog retains at most four messages in order, dropping the oldest on a fifth. Each is rendered by an ordinary Label (no BBCode), with wrapping and a bounded row height. The panel is passive and does not take gameplay focus. Match exit, identity invalidation, session loss and suspend clear it; newly restricted/departed senders' rows are removed. The next match starts empty, with no lobby backlog, disk/cloud persistence or replay after permission restoration. begin_match_chat() / end_match_chat() only manage this transient UI context, not transport. If communications privilege is revoked mid-session, the chat control is destroyed. Restoring that privilege requires leaving/rejoining to recreate the control; there is no live network reconfiguration.

One local echo means Party accepted the submission, not that another player received or read it. Chat has no gameplay RPCs and changes no wire protocol. Speech-to-text, text-to-speech, transcription and translation are not demonstrated; their flags remain off. Receiving typed text requires ReceiveText permission, not enabling transcription.

See communication walkthroughs and chat acceptance.

Admission: how a match closes and how a join succeeds

Closing a match to newcomers

PLAYERS_JOINING covers both the lobby and scene loading, so NetManager._accepting_joins separately tracks admission. Two mechanisms enforce it, and both are needed:

The lobby's membership lock stops a latecomer being admitted to the session. LobbyScreen._try_auto_start() awaits NetManager.close_joins() before it broadcasts STARTING, which calls PartyService.set_lobby_locked(true) → PlayFabLobby.set_membership_lock_async(). The lobby is locked, not deleted: it keeps its join code, its connection string — the one every published activity and sent invite carries — its existing members and the Party descriptor the running match is reachable through. A locked lobby refuses new members; it does not necessarily vanish from discovery, which is why the host's door below is not redundant. Locking fails closed: an unconfirmed lock does not start the match, and the lobby offers Try Again or Stay In Lobby rather than starting one it is still advertising.

The host's door covers a join already in flight when the lock landed. _on_peer_connected() checks _accepting_joins, and _submit_player_identity() checks again after the asynchronous handshake. _reject_join supplies a readable reason. The roster, readiness and loading barrier can then assume members were admitted before start.

The host reopens the match from LobbyScreen._ready() when it returns to the waiting lobby — not when the match ends. Players read the results screen at their own pace, and a lobby that reopened at the final whistle would take newcomers while everyone else was still looking at final scores. _apply_match_reset() also un-readies every human player, and readying up is a lobby shortcut, so the next round cannot begin until every current player is back and ready. An unlock that fails leaves the match closed with Try Again or Leave Match.

Every one of those transactions is bound to a session identity. NetManager.session_id() returns a number that no later session reuses; the lobby captures it before each service call and each recovery dialog and re-checks it afterwards, because has_session() answers "is there a session" and by then the useful question is "is this still that session". Retry after the lock failed re-validates that the match is still startable. If the last other player left or un-readied while the dialog was up, it reopens the lobby; retry is offered only while the start conditions still hold.

XBOX activity follows admission on every member, host and guest alike: _receive_join_admission mirrors the host's gate onto each client, and PlatformSession retires or republishes its own activity from it. A closed match therefore stops being offered in the guide and on friends' profile cards, rather than offering a Join that ends in a refusal.

Advertising is confirmed, not assumed

PlatformSession keeps three things apart: the state this session wants advertised (_activity_published), what the service is known to hold (_activity_remote), and the fact that a write can leave the answer genuinely unknown. ActivityService.set_activity() and delete_activity() return one of CONFIRMED, FAILED, UNAVAILABLE or INVALID, because a call that was never sent and one the service accepted are not the same result and a bool cannot tell them apart.

Only CONFIRMED changes what the title believes is out there. A refused write leaves the state unknown rather than assumed-clear, which is what makes a failed publish followed by a close still send a delete — recording the failed publish as "nothing published" is exactly how a started match stayed advertised.

Retries are bounded: one attempt and at most three more, at 1 s, 2 s and 4 s, and only for writes the service actually refused. The budget belongs to a lifecycle episode — this session opening, closing or ending, or a genuine account or connectivity recovery — and is deliberately not restarted by roster refreshes, which arrive often enough to make a budget meaningless. On exhaustion the unresolved state is kept and a warning names the operation and the attempt count; there is no dialog, because the membership lock and the host's door are what actually keep an unwanted joiner out. Retirement is therefore not instantaneous. While the service is failing, a friend's guide can go on showing a session that has already started, and the join they attempt from it is refused by the host rather than by the advertisement.

How a join actually succeeds

A join reports success when the host sends _accept_join, not when the transport attaches. Party connects a client to the mesh before the host has looked at it, and the host may still turn it away — so a join resolved on the transport alone reported success for sessions the player was never admitted to. The refusal then arrived while the loading screen was still up, too late to change an answer already recorded, and the player landed in a lobby with no roster and no join code.

NetManager.join_by_code() and join_by_invite() return a JoinRequest immediately, before the attempt has done anything, and the caller awaits request.wait(). The handle is returned early on purpose: the screen that owns the attempt needs to name this attempt while it is still running — to bind its Cancel button to it, and to know afterwards that the answer it is reading is its own. Shared flags on the autoload could not do that. An invite accepted while a code join was still on the loading screen set the shared flag, and the code join's own waiter read it and reported the replacement's outcome as its own.

Each request carries its own outcome — SUCCEEDED, CANCELLED, SUPERSEDED or FAILED — its own reason, and the identity of the session it was admitted to. Code, friend-activity and invite joins all go through one driver, so all three get the same 45-second budget spanning both halves of joining, the same cancellation handling and the same admission handling.

Four things fall out of that:

  • Acceptance is provisional. _accept_join records the admission; it does not emit success, publish an activity or open anything. The request's own poll consumes it a moment later, after checking that the player has not canceled in the meantime. A Cancel recorded before the acceptance is consumed therefore wins — the player asked to stop, and should not be seated because the answer overtook them.
  • Supersession is silent. A replaced join shows no dialog, changes no screen and navigates nowhere; the join that replaced it owns all of that. From the player's side nothing failed.
  • Teardown happens once. The replaced join and the replacement both wait on one single-flight cleanup, so the peer is never detached twice — the second detach would land on whatever session existed by then, which is the replacement's live one.
  • Success is checked against a session identity, not a peer. Consumers call NetManager.joined_session_is_live(request), which compares the session the request was admitted to against the one that exists now. Looking merely for a peer would happily accept the next session as this one.

A session lost while a join is pending is answered by that join rather than by a second disconnect dialog. Owned UI cleanup goes with owned outcomes: join screens are removed by instance through ScreenManager.remove() rather than by pop(), so a flow resuming from an await takes down its own loading screen and not whichever one happens to be on top.

What this sample does not do (and why)

The game is host-authoritative; Party supplies transport, not its simulation rules. No host migration: losing the host ends the session. No join-in-progress: admission closes when the lobby commits to starting. Low-latency setups best suit the demonstration; fixed prediction/correction can rubber-band over higher-latency networks. These are sample gameplay limitations, not Party shortcomings.

The netcode model and where it runs out

Detailed interpolation, prediction and latency mechanics moved to the gameplay reference. Protocol remains the maintainer reference for RPC routing and snapshot formats.


Testing two players on one PC

The sample's simplified XBOX user model uses the launching account, so two simultaneous registered instances on one PC do not provide distinct XBOX players. Use two registered PCs or authorized consoles with distinct XBOX accounts, compatible builds, the same title and ready saves for multiplayer acceptance.

One PC still supports the sequential A/B account-isolation test: close the game, change the launching XBOX account, then relaunch the registered package. That is not simultaneous multiplayer. See account-save acceptance.

Party transport configuration

XBOX-linked sessions use local_udp_port = -1 for Game Core's preferred multiplayer port in initialize_async. The addon exposes playfab/party/local_udp_socket_bind_port; the project leaves it at the addon default. direct_peer_connectivity = NONE relays Party traffic through PlayFab.