five-on-it / apps/api/src/lobby-routes
apps/api/src/lobby-routes
The lobbies' routes (GAME_DESIGN §13, TECHNICAL_SPECS §9.6): a lobby opened for a mission of a game, read, joined, left; its members ready, on a team, voting on the next mission; its host starting it early and kicking; a friend invited; Quick play by playlist. The state is the LobbyHub's (lobbies.ts), Quick play the Matchmaker's (matchmaking.ts); the bodies and answers are @foi/protocol's lobby shapes. Every change reaches the members through their feed (lobby, and run with each member's join URL when the run's room is theirs to join), as a party's room does.
An account sits in one open run at most (runs.ts): opening, joining or Quick play is refused (409, naming the run) while the caller is still seated in one; the members of the party they lead who are stay in their run, invited to the lobby instead. A lobby of a game shared by link is private, whatever was asked: only those given its link find it, and a reader not in a lobby sees names and counts, never accounts nor its run. The lists (GET /lobbies, GET /missions) ask for a session (a guest has one).
| Route | Who | What |
|---|---|---|
POST /lobbies {game, mission, visibility, playlist?} | player | Opens a lobby for a multiplayer mission (a published game's, or a curated one's), led by the caller, their party with them: the lobby; opened from a playlist, it remembers it (the mission must be in it). |
GET /lobbies?game=&mission=&mode= | signed in | The public lobbies (LobbySummary: the mission, its level, the players and the most, its state, its teams). |
GET /lobbies/mine | player | The caller's lobby (its id, or null) and the lobbies friends invited them to. |
GET /lobbies/:id | player | A lobby as the caller sees it (LobbyView); anyone with its id may read it (a private lobby's link). |
POST /lobbies/:id/join, /leave | player | Join (with one's party, when leading it), leave. |
POST /lobbies/:id/ready {ready}, /team {team} | its members | Ready or not; move to another team, with one's party. |
POST /lobbies/:id/start {ai?}, /kick {account} | its host | Start the countdown early (every team at its minimum; with ai, after 20 s under it, the empty seats AI players); remove a member for good. |
POST /lobbies/:id/vote {offer} | its members | A vote on the next mission: same, game, level or replay. |
POST /lobbies/:id/invite {account} | its members | Invite a friend: their feed and their invitations. |
POST /lobbies/quick {playlist, ai?} | player | Quick play: placed (with one's party) in a public lobby of the playlist, a seat of a run of it under way (the answer's join), or a new lobby; with ai, Play now with AI: a lobby of one's own started at once, AI players in the empty seats. |