Photon/matchmaking/implement/premade matchmaking

[Davetsa]

Pull Request: Implement Premade Matchmaking Flow

This pull request introduces a comprehensive premade matchmaking system that allows players to form duos, send invites, and queue together through dedicated friend lobbies. The implementation includes new game types, Photon room properties, queue management infrastructure, and UI components for the premade invite flow.

Core Features: Premade Matchmaking

• New GameType.FriendLobby: Added a new game mode for 2-player premade friend lobbies that serve as the entry point for premade player interactions. Friend lobbies have a maximum of 2 players and are distinct from matchmaking and queue rooms. [1]

• Premade Invite System: Implemented SendPremadeInvite() method in PhotonRealtimeClient to send invitations from one player to another. Invites track state (pending, accepted, declined, expired) and timestamp to manage the lifecycle of premade pairing requests. [1]

• Premade Invite Room Properties: Added 9 new room property keys to track premade state:

  • PremadeModeKey ("pm"): Boolean flag indicating premade mode
  • PremadeTargetGameTypeKey ("ptg"): Target game type (Random2v2, Clan2v2)
  • PremadeLeaderUserIdKey ("plid"): The leader's user ID
  • PremadeInvitedUserIdKey ("piu"): The invited player's user ID
  • PremadeInviteStateKey ("pis"): Current invite state (none=0, pending=1, accepted=2, declined=3, expired=4)
  • PremadeInviteTimestampKey ("pits"): Timestamp of invite creation
  • PremadeUserId1Key ("pm1") and PremadeUserId2Key ("pm2"): The two paired user IDs
  • [1]

• CreateInRoomPremadeLobbyRoom(): New method to create friend lobby rooms with expected users, enabling the initial 2-player room setup for premade pairs. [1]

Queue Management Infrastructure

• JoinAttemptTracker: New utility class to track and manage join attempt history for rooms, helping prevent redundant join attempts and enabling diagnostics for join failures. [1]

• Enhanced Queue Formation Logic: SelectQueueFollowersForMatch() and related methods now include sophisticated handling for premade duos within queues, including:

  • Preservation of premade pair metadata during duo selection
  • Special handling for one-sided premade metadata (one partner present, one missing)
  • Deferral logic to wait for second duo to join before forming mixed compositions
  • Orphan follower detection and exclusion from inappropriate pairings
  • [1]

• Two-Player Block Selection: Implemented SelectQueueFollowersFromTwoPlayerBlocks() for 2v2 match formations, which:

  • Groups players into complete duo pairs and solo pairs
  • Preserves duo cohesion during formation
  • Handles incomplete premade metadata with grace periods
  • Defers formation when waiting for second duo in mixed compositions
  • [1]

• Queue Timer Enhancements: QueueTimerCoroutine() now includes:

  • Early-start readiness checking with deferral for incomplete compositions
  • Timeout-based queue formation with bot fill logic
  • Premade pair closure enforcement to prevent solo+incomplete-duo starts
  • Support for both 2-player-block modes (duos/solos) and traditional matching
  • [1]

• Room State Validation: Added ValidateQueueTwoPlayerBlockComposition() to ensure queue-formed matchmaking rooms contain valid 2-player block arrangements before game start. [1]

Premade Flow & Room Transitions

• Premade-to-Queue Handoff: StartMatchmaking() now includes intelligent premade teammate resolution:

  • Identifies and preserves verified premade partners
  • Falls back to single unambiguous teammate only when premade is not verified
  • Sets premade room properties (pm, pm1, pm2, plid) before followers join
  • [1]

• RoomChangeRequested Selective Updates: Updated to only modify LeaderIdKey for targeted followers, preventing corruption of duo linkage for non-targeted players during queue transitions. [1]

• Queue-Formed Match Formation: FormMatchFromQueue() now:

  • Computes complete duo pairs and solo pairs from queue participants
  • Generates deterministic matchmaking room names for reliable follower joins
  • Includes premade pair preservation guards in selected participants
  • Sets expected user lists with QueueDuoPairsKey to track duo groupings
  • [1]

• Game Start Validation: StartTheGameplay() now validates that all in-room human players are included in computed PlayerSlotUserIds before starting. If validation fails, sends CancelGameStart and restarts waiting loop. [1]

UI Components & Invite Handling

• InviteDecisionPanel.prefab: New popup panel for displaying and handling invite acceptance/declination decisions. [1]

• InviteSelectorRow.prefab: New UI row component for displaying individual invites in a list, with accept/decline buttons. [1]

• InRoomInviteSelectorPanel.cs: New panel script managing the display and interaction of multiple invite rows, handling UI state and callbacks. [1]

• InviteDecisionPopupHandler.cs: New handler for managing the lifecycle of invite decision popups, ensuring fail-closed behavior (decline + notification on UI failure). [1]

• Enhanced InLobbyController: Updated to:

  • Route FriendLobby queue rooms to matchmaking panel instead of friend lobby view
  • Manage invite decision popup visibility and lifecycle
  • Handle targeted invite UI events with listener checks
  • [1]

• Updated LobbyRoomListingController: Added single-flight guard for queue room join requests to prevent duplicate room creation from rapid UI interactions. [1]

• BattlePopupPanelManager Enhancements: Updated to support invite button rendering and premade flow UI state. [1]

• InRoomController Updates: Added event handlers and logic for premade-specific in-room behavior and state management. [1]

• RoomSetupManager Updates: Enhanced to handle premade room properties and invite state changes. [1]

Critical Stability Improvements

• Orphan Follower Handling: Queue selection now properly excludes orphaned followers (those with missing leaders) from solo-candidate pools in 2v2 modes, preventing transient leader-absence from splitting valid duos. [1]

• Multi-Duo Preservation: When 2+ complete duo pairs exist in a queue with extra players, selection defers formation to allow both duos to stabilize before creating matches, preventing premature solo+one-duo starts. [1]

• One-Sided Premade Metadata Handling: When premade metadata exists but one partner is absent, the present partner is marked incomplete rather than blocked, allowing valid compositions while deferring fully-settled pairs. [1]

• Non-Master Join Timeout Disable for Queue-Formed Rooms: Followers in queue-formed matchmaking rooms skip the 5-second join-timeout watcher, preventing false timeouts during multi-follower convergence. [1]

• Join Failure Auto-Requeue Guard: OnJoinRoomFailed() now sets IsJoinFailureAutoRequeueInFlight flag so duplicate queue rejoin attempts are skipped for the same failure. [1]

• Defensive Callback Subscription: Activate() now resets Photon callback handlers before re-subscribing, preventing duplicate handler registrations across lifecycle transitions. [1]

• OnStartMatchmakingEvent Debouncing: Added frame-level debounce to prevent back-to-back event publications from spawning duplicate matchmaking transitions. [1]

Summary

This implementation establishes a complete premade matchmaking flow from friend lobbies through queue formation to game start, with robust safeguards against duo splits, race conditions, and metadata corruption. The system tracks premade relationships across multiple room transitions and ensures both players in a premade pair reach the matchmaking room together and maintain their team assignment through game start.