the-cycle/SQUAD-EMULATION.md

Étude — Émulation PlayFab Groups/Party pour l'invite de squad

Objectif : permettre à un joueur d'inviter un ami à faire équipe (squad) sur le serveur privé. Étude du mécanisme, de l'état actuel, d'une conception d'émulation et d'un plan. Branche : game-server.

1. État actuel (ce qui existe déjà)

Roster de squad en mémoire — Services/Squad/SquadService.cs :

• Squads clés par un squadId fourni par le client (JoinOrCreate(squadId, userId, …)).
• Membre = profil (playerId, displayName), onlineState, isReady, selectedMap, isLeader.
• _userToSquad permet à TryGetCompleteSquadInfo (qui ne porte pas de squadId) de retrouver la squad du joueur.

Fonctions CloudScript squad présentes : TryGetCompleteSquadInfo, SquadMemberReadyForMatch (pousse déjà via SignalR), SquadMemberSelectedMap, SquadMemberStartingDeployFlow, GetFriendList, ClientsideFriendsImport.

Ce qui MANQUE (cœur du problème) : aucune fonction de création de squad, d'invitation, d'acceptation/refus, de join/leave/kick. Le flux actuel suppose que le client connaît déjà un squadId (party formée ailleurs) et se contente d'y rattacher les membres.

Infra de push temps-réel DISPONIBLE — Hubs/CycleHub.cs + Hubs/SignalRConnectionRegistry.cs : le client se connecte au hub avec ?uid=<playerId> ; le registry mappe uid → connectionId. Le serveur peut donc pousser un message ciblé à un joueur précis (registry.GetConnection(uid) + IHubContext<CycleHub>.Clients.Client(conn).SendAsync(<event>, payload)). C'est déjà utilisé par SquadMemberReadyForMatch et par le signal « travel to match » du matchmaking. → Le canal de livraison de l'invite existe déjà.

2. Comment The Cycle forme-t-il les squads ? (hypothèses + preuves)

Le squadId étant fourni par le client, la party est créée là où le client obtient cet id. Quatre mécanismes candidats côté PlayFab/Steam :

#	Mécanisme	Ce que ça implique côté serveur	Indice
A	PlayFab Entity Groups (/Group/CreateGroup, /Group/InviteToGroup, /Group/AcceptGroupInvitation, /Group/ListGroupMembers…)	Implémenter le sous-ensemble Groups (entités déjà émulées). squadId = group entity id.	Fort : squads persistantes chez PlayFab passent par Groups ; l'id opaque partagé colle.
B	PlayFab Lobby (Multiplayer : CreateLobby/JoinLobby/InviteToLobby via connection string)	Implémenter l'API Lobby. squadId = lobbyId.	Moyen : plutôt matchmaking S3+.
C	Lobby Steam (invite via overlay Steam) + backend qui suit	Rien à créer pour l'invite (100% Steam) ; le serveur ne fait que suivre le squadId rapporté.	Moyen : S2 = Steam-only ; explique le squadId client. Mais alors l'invite n'est pas pilotable serveur.
D	Fonctions CloudScript d'invite (non observées)	Implémenter InvitePlayerToSquad/RespondToSquadInvite/…	Faible : aucune trace.

Preuve manquante (bloquant) : les logs prod de la session à 2 ont été écrasés par nos redéploiements. Impossible aujourd'hui de voir l'appel exact d'invite. De plus, l'émulateur peut 404 silencieusement un endpoint PlayFab natif non routé (ex. /Group/CreateGroup) → un tel appel n'apparaît pas comme fonction CloudScript. Il faut donc capturer l'appel réel (voir §5, Phase 0) — d'autant que le bouton « inviter » n'apparaît pas tant que la tuile ami est vide (bug de forme GetFriendList, corrigé PR #15, à valider en jeu). Tant que la liste d'amis ne s'affiche pas, aucune invite ne peut même être tentée.

3. Conception d'émulation proposée (indépendante du mécanisme exact)

Quel que soit A/B/C/D, les briques serveur à construire sont les mêmes :

3.1 Étendre SquadService (états d'invite) :

• CreateSquad(leaderUserId) → squadId (GUID serveur si le client n'en impose pas).
• Invite(squadId, fromUserId, toUserId) → enregistre une invitation en attente {squadId, from, to, expiresAt}.
• RespondToInvite(toUserId, squadId, accept) → si accept : JoinOrCreate ; sinon purge.
• Leave / Kick(byLeader) / transfert de leadership à la sortie du leader.
• GetPendingInvites(userId) (fallback poll).

3.2 Surface d'API — deux options selon la capture (§5) :

• Si Groups (A) : router POST /Group/CreateGroup, /Group/InviteToGroup, /Group/AcceptGroupInvitation, /Group/ListGroupMembers, /Group/RemoveMembers vers SquadService (les EntityToken sont déjà émulés). C'est le plus « natif ».
• Si CloudScript (D) / custom : ajouter les fonctions [CloudScriptFunction(...)] correspondantes (noms/shapes calqués sur la capture).
• Si Steam (C) : rien pour l'invite (Steam) ; s'assurer seulement que le roster se peuple bien quand les deux clients rapportent le même squadId (déjà géré par SquadService).

3.3 Livraison temps-réel de l'invite (réutilise l'infra existante) :

• À l'invitation, pousser à l'invité : registry.GetConnection(toUserId) + hub.Clients.Client(conn).SendAsync("<SquadInviteReceived>", payload).
• Nom d'event + payload = à confirmer côté client (le client doit écouter cet event). Fallback : GetPendingSquadInvites (CloudScript) que le client poll à l'ouverture du menu social.

3.4 Persistance : le roster peut rester en mémoire (petit serveur), mais les invitations gagnent à être persistées (UserData PendingSquadInvites) pour survivre à un reload/redeploy et au cas « ami à la station » — combiné au push SignalR.

4. Limite structurelle importante (à dire clairement)

Émuler l'invite permet de former une squad et de se mettre prêt ensemble (lobby/ready-up). Mais déployer réellement ensemble dans le même raid nécessite le serveur de jeu dédié (Prospect.Server.Game), qui est bloqué au mur DTLS-PSK (cf. reste de cette branche). Les raids S2 sont hébergés côté client (solo) : sans serveur dédié, deux joueurs ne peuvent pas partager la même instance de raid. Donc :

• Invite + squad + ready-up : émulable via l'API (cette étude).
• Co-op en raid : dépend du serveur dédié (autre chantier, DTLS-PSK).

5. Plan par phases

• Phase 0 — Capture (débloque tout) : valider le fix GetFriendList en jeu (la tuile ami doit afficher le pseudo) → le bouton « inviter » réapparaît → tenter une invite et capturer les appels (ajouter un logging catch-all des requêtes non routées + corps, pour voir un éventuel /Group/… 404). Résultat : on sait A/B/C/D.
• Phase 1 — Invite : implémenter la surface identifiée + états SquadService + push SignalR ; persister les invitations.
• Phase 2 — Ready-up/déploiement groupé : compléter (déjà amorcé) ; le déploiement co-op réel reste gated par le serveur dédié.

6. Prochaine action concrète

Repro en jeu (liste d'amis corrigée) + logging catch-all → capturer l'appel d'invite. Sans cette capture, toute implémentation d'invite serait une supposition sur les noms/shapes attendus par le client (paks chiffrés → pas de RE statique).