@hadoku/game-server 0.0.0-stage → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/LICENSE +21 -0
  2. package/dist/base-path.d.ts +29 -0
  3. package/dist/base-path.js +30 -0
  4. package/dist/busy.d.ts +40 -0
  5. package/dist/busy.js +23 -0
  6. package/dist/capacity.d.ts +9 -0
  7. package/dist/capacity.js +6 -0
  8. package/dist/config.d.ts +247 -0
  9. package/dist/config.js +271 -0
  10. package/dist/edge-auth.d.ts +43 -0
  11. package/dist/edge-auth.js +47 -0
  12. package/dist/erase/anonymise.d.ts +7 -0
  13. package/dist/erase/anonymise.js +7 -0
  14. package/dist/erase/index.d.ts +18 -0
  15. package/dist/erase/index.js +20 -0
  16. package/dist/erase/legacy-ids.d.ts +7 -0
  17. package/dist/erase/legacy-ids.js +24 -0
  18. package/dist/erase/recordings.d.ts +26 -0
  19. package/dist/erase/recordings.js +128 -0
  20. package/dist/erase/rooms.d.ts +63 -0
  21. package/dist/erase/rooms.js +67 -0
  22. package/dist/gate.d.ts +27 -0
  23. package/dist/gate.js +15 -0
  24. package/dist/http/client-events.d.ts +25 -0
  25. package/dist/http/client-events.js +15 -0
  26. package/dist/http/page.d.ts +26 -0
  27. package/dist/http/page.js +35 -0
  28. package/dist/http/prepared.d.ts +14 -0
  29. package/dist/http/prepared.js +16 -0
  30. package/dist/http/request.d.ts +59 -0
  31. package/dist/http/request.js +37 -0
  32. package/dist/http/room-core.d.ts +160 -0
  33. package/dist/http/room-core.js +278 -0
  34. package/dist/http/trim.d.ts +23 -0
  35. package/dist/http/trim.js +76 -0
  36. package/dist/http/usage.d.ts +22 -0
  37. package/dist/http/usage.js +16 -0
  38. package/dist/kernel.d.ts +4 -0
  39. package/dist/kernel.js +26 -0
  40. package/dist/log.d.ts +9 -0
  41. package/dist/log.js +9 -0
  42. package/dist/people.d.ts +105 -0
  43. package/dist/people.js +145 -0
  44. package/dist/play/clock.d.ts +39 -0
  45. package/dist/play/clock.js +81 -0
  46. package/dist/play/diagnostics.d.ts +21 -0
  47. package/dist/play/diagnostics.js +35 -0
  48. package/dist/play/engine-runtime.d.ts +200 -0
  49. package/dist/play/engine-runtime.js +309 -0
  50. package/dist/play/game-adapter.d.ts +158 -0
  51. package/dist/play/game-adapter.js +1 -0
  52. package/dist/play/host.d.ts +482 -0
  53. package/dist/play/host.js +950 -0
  54. package/dist/play/jvm-transport.d.ts +25 -0
  55. package/dist/play/jvm-transport.js +1 -0
  56. package/dist/play/local-jvm.d.ts +325 -0
  57. package/dist/play/local-jvm.js +829 -0
  58. package/dist/play/match/hosted.d.ts +92 -0
  59. package/dist/play/match/hosted.js +151 -0
  60. package/dist/play/match/outcome.d.ts +26 -0
  61. package/dist/play/match/outcome.js +21 -0
  62. package/dist/play/match/shell.d.ts +378 -0
  63. package/dist/play/match/shell.js +613 -0
  64. package/dist/play/recording/retention.d.ts +36 -0
  65. package/dist/play/recording/retention.js +89 -0
  66. package/dist/play/recording/writer.d.ts +185 -0
  67. package/dist/play/recording/writer.js +90 -0
  68. package/dist/play/relay-socket.d.ts +128 -0
  69. package/dist/play/relay-socket.js +194 -0
  70. package/dist/play/runtimes/in-process.d.ts +47 -0
  71. package/dist/play/runtimes/in-process.js +43 -0
  72. package/dist/play/runtimes/relay-match.d.ts +166 -0
  73. package/dist/play/runtimes/relay-match.js +240 -0
  74. package/dist/play/runtimes/relay.d.ts +128 -0
  75. package/dist/play/runtimes/relay.js +183 -0
  76. package/dist/play/runtimes/streamed.d.ts +116 -0
  77. package/dist/play/runtimes/streamed.js +148 -0
  78. package/dist/play/start-queue.d.ts +65 -0
  79. package/dist/play/start-queue.js +187 -0
  80. package/dist/room/avatar.d.ts +1 -0
  81. package/dist/room/avatar.js +28 -0
  82. package/dist/room/caller.d.ts +21 -0
  83. package/dist/room/caller.js +1 -0
  84. package/dist/room/constants.d.ts +27 -0
  85. package/dist/room/constants.js +27 -0
  86. package/dist/room/events.d.ts +59 -0
  87. package/dist/room/events.js +174 -0
  88. package/dist/room/identity.d.ts +89 -0
  89. package/dist/room/identity.js +98 -0
  90. package/dist/room/lobby.d.ts +426 -0
  91. package/dist/room/lobby.js +880 -0
  92. package/dist/room/membership.d.ts +64 -0
  93. package/dist/room/membership.js +76 -0
  94. package/dist/room/provisioning.d.ts +22 -0
  95. package/dist/room/provisioning.js +46 -0
  96. package/dist/room/record.d.ts +63 -0
  97. package/dist/room/record.js +39 -0
  98. package/dist/room/room-list.d.ts +67 -0
  99. package/dist/room/room-list.js +66 -0
  100. package/dist/room/seats.d.ts +39 -0
  101. package/dist/room/seats.js +58 -0
  102. package/dist/room/session.d.ts +91 -0
  103. package/dist/room/session.js +156 -0
  104. package/dist/room/socket-auth.d.ts +2 -0
  105. package/dist/room/socket-auth.js +10 -0
  106. package/dist/room/watching.d.ts +35 -0
  107. package/dist/room/watching.js +72 -0
  108. package/dist/room/watchparty-link.d.ts +1 -0
  109. package/dist/room/watchparty-link.js +17 -0
  110. package/dist/stream/alloc.d.ts +115 -0
  111. package/dist/stream/alloc.js +368 -0
  112. package/dist/stream/index.d.ts +66 -0
  113. package/dist/stream/index.js +293 -0
  114. package/dist/telemetry.d.ts +46 -0
  115. package/dist/telemetry.js +25 -0
  116. package/dist/testPort.d.ts +1 -0
  117. package/dist/testPort.js +28 -0
  118. package/package.json +35 -4
  119. package/README.md +0 -3
@@ -0,0 +1,426 @@
1
+ /**
2
+ * The lobby core: which rooms exist, who is in them, who leads them and holds which seat, kept on
3
+ * disk, for any game type. A game type plugs in through `RoomTypeHooks` (its own part of the record,
4
+ * its seat rules, its view, what leaving or a Ready costs it); this file never names a game's field.
5
+ * Magic's lobby (`games/magic/server/src/room/lobby.ts`) is this core with Magic's hooks, and a game
6
+ * with nothing of its own to keep (bomberman) plays on `plainRoomType`.
7
+ *
8
+ * ## Persistence: write-through, through `@wolffm/rooms-server/store`
9
+ *
10
+ * A deploy restarts the server several times a day, so every mutation writes that room's snapshot
11
+ * synchronously (`FileRoomStore`'s atomic temp-file-and-rename) before the call returns: no debounce
12
+ * window for a deploy to fall into, no flush-on-SIGTERM to get right. Rooms are stored in the store's
13
+ * own snapshot format (`STORE_VERSION`) and read back through `decodeSnapshot`, so an unreadable or
14
+ * future-format record is QUARANTINED (moved aside intact), never half-applied or silently dropped.
15
+ *
16
+ * The snapshot's `members` are the room's members; each member's `app` blob carries their Ready and
17
+ * their per-room state. The room-level `app` blob (`StoredRoomApp`) carries name, creator, leader,
18
+ * game type, the game seats, the game's own part (`RoomTypeHooks.encode`), and the password's salt
19
+ * and scrypt hash.
20
+ *
21
+ * ## The password is privacy between friends, not authentication
22
+ *
23
+ * Everything here is behind the member gate at the edge. A room password keeps a sibling out of your
24
+ * game; it is not a security boundary. It is still handled with care, because a person may reuse a
25
+ * password they use elsewhere: scrypt with a per-room salt, never logged (nor its hash or salt), kept
26
+ * in a private map rather than on the record so dumping a record cannot print it, and compared with
27
+ * `timingSafeEqual` (`provisioning.ts`).
28
+ *
29
+ * ## Only durable callers may create or join
30
+ *
31
+ * An ephemeral participant id is a per-request random value: it could never be matched on a second
32
+ * request, and the store drops non-durable members from every snapshot. So `create`/`join` refuse an
33
+ * ephemeral caller (the HTTP layer answers 403) rather than seat a member who vanishes on restart.
34
+ */
35
+ import { FileRoomStore, type RoomCodec } from '@wolffm/rooms-server/store';
36
+ import { type Look } from '@wolffm/platform-wire/look';
37
+ import type { Caller } from './caller.js';
38
+ import { type Secret } from './provisioning.js';
39
+ import { type GameSeats, type PlatformMember, type PlatformRoomRecord } from './record.js';
40
+ import { type RoomBusyHook } from './room-list.js';
41
+ /** A member as the lobby keeps one: the platform's record plus what a view shows of them. */
42
+ export interface LobbyMember extends PlatformMember {
43
+ /** In memory only, from the member's own requests (`rename`): a saved room keeps no names (R12). Restored `UNNAMED`. */
44
+ name: string;
45
+ /** In memory only: their account's character, absent until it has been read. */
46
+ avatarId?: string;
47
+ /** In memory only: their account's picture and cosmetics, as prefs-api answered (`setLook`). */
48
+ look?: Look;
49
+ }
50
+ export type LobbyRoom<G = unknown> = PlatformRoomRecord<G, LobbyMember>;
51
+ /** What every room is created with, whatever it plays. A game type's own input adds to it. */
52
+ export interface RoomCreateInput {
53
+ name: string;
54
+ gameType: string;
55
+ /** Absent or empty: an open room. */
56
+ password?: string;
57
+ /** A seeded, admin-only room, never set by a client body: never swept (`room-list.ts`). */
58
+ testing?: boolean;
59
+ /** When the room's event starts, in ms (`events.ts`). Set by the events route, never by a client body. */
60
+ scheduledFor?: number;
61
+ }
62
+ /** A member as every room's view names them. */
63
+ export interface LobbyMemberView {
64
+ id: string;
65
+ name: string;
66
+ joinedAt: string;
67
+ ready: boolean;
68
+ avatarId?: string;
69
+ look?: Look;
70
+ }
71
+ /** A room's view as every game's room has it (`@hadoku/shared`'s `roomBaseFields`); the game type's part is spread over it. */
72
+ export interface PlatformRoomView {
73
+ id: string;
74
+ name: string;
75
+ creator: string;
76
+ leader: string;
77
+ gameType: string;
78
+ /** Whether a password is set: never the password, never any hash of it. */
79
+ locked: boolean;
80
+ members: LobbyMemberView[];
81
+ /** Who holds each game seat, by seat number; a member in none is watching. */
82
+ seats: (string | null)[];
83
+ createdAt: string;
84
+ testing: boolean;
85
+ scheduledFor: string | null;
86
+ }
87
+ /** The room-level `app` blob as the store keeps it: the platform's fields, the game seats, and the game's own part under `game`. */
88
+ export interface StoredRoomApp {
89
+ name: string;
90
+ creator: string;
91
+ leader: string;
92
+ gameType: string;
93
+ /** Absent for a room written before testing rooms existed: an ordinary one. */
94
+ testing?: boolean;
95
+ /** Absent for a room no event made. */
96
+ scheduledFor?: number;
97
+ secret: Secret | null;
98
+ seats: GameSeats;
99
+ /** The game type's part as it stores it (`RoomTypeHooks.encode`/`decode`). */
100
+ game: unknown;
101
+ }
102
+ /** Structured, and never carries a password, hash or salt. */
103
+ export type LobbyLog = (entry: Record<string, unknown>) => void;
104
+ /**
105
+ * Everything a game type tells the lobby about its rooms. Every hook is called only for a room of
106
+ * the type it was registered for, so `G` is that room's own part.
107
+ */
108
+ export interface RoomTypeHooks<G, I extends RoomCreateInput = RoomCreateInput> {
109
+ /** A new room's game seats and its game part's defaults. */
110
+ newGame(input: I, id: string): {
111
+ seats: GameSeats;
112
+ game: G;
113
+ };
114
+ /** The game part as stored. */
115
+ encode(room: LobbyRoom<G>): unknown;
116
+ /** The stored `app` as written: anything the type writes beside it (a copy an older build reads). Default: as it is. */
117
+ writes?(app: StoredRoomApp): object;
118
+ /**
119
+ * The stored `app` read back: its game seats and its game part, as stored. Throws to quarantine the room;
120
+ * the message names the field, never a value. `version` is the app blob's own (`ROOM_APP_VERSION` or older).
121
+ */
122
+ decode(app: Record<string, unknown>, version: number, ctx: {
123
+ roomId: string;
124
+ }): {
125
+ seats: GameSeats;
126
+ game: unknown;
127
+ };
128
+ /**
129
+ * The decoded game part made a record's. `dropHolds`: every member comes back with no state and not
130
+ * ready (the room is restored as a change to what it plays would leave it). `game` is given the members.
131
+ */
132
+ restore(app: StoredRoomApp, roomId: string): {
133
+ dropHolds: boolean;
134
+ game: (members: readonly LobbyMember[]) => G;
135
+ };
136
+ /** A restored room is installed (boot only). */
137
+ restored?(room: LobbyRoom<G>): void;
138
+ /** A created room is installed and saved; what the creation log line says of it. */
139
+ created?(room: LobbyRoom<G>): Record<string, unknown>;
140
+ /** Before every save. */
141
+ beforePersist?(room: LobbyRoom<G>): void;
142
+ /** The game type's part of the room's view, spread over the platform's. */
143
+ view(room: LobbyRoom<G>): object;
144
+ /** The game seats as the view and the relay see them (`PlatformRoomView.seats`). Default: `memberSeats`. */
145
+ seatsView?(room: LobbyRoom<G>): GameSeats;
146
+ /** The members who play, in seat order. Default: the members who hold a game seat. */
147
+ players?(room: LobbyRoom<G>): string[];
148
+ /**
149
+ * Seat a member who just arrived (only when nobody already in the room waits unseated). `'game-seat'`:
150
+ * the first open game seat, the platform's own. `true`/`false`: the type seated them itself, or nowhere.
151
+ */
152
+ autoSeat?(room: LobbyRoom<G>, memberId: string): boolean | 'game-seat';
153
+ /** The busy rules the room list and the sweep read (`room-list.ts`). */
154
+ busy: RoomBusyHook<LobbyRoom<G>>;
155
+ /** The matches the room's games are playing now, which a close lets go of. */
156
+ liveMatches(room: LobbyRoom<G>): string[];
157
+ /** A member is leaving and still in the room: what it costs their game (a match it forfeits). */
158
+ leaving?(room: LobbyRoom<G>, memberId: string): Pick<LeaveOk<never>, 'forfeited'> | void;
159
+ /** A Ready: `'keep'` refuses the change quietly (the room's positions are fixed). Called before it is saved. */
160
+ ready?(room: LobbyRoom<G>, memberId: string, ready: boolean): 'keep' | void;
161
+ /** After a saved change to who sits or who is ready (a tournament's field filling, say). */
162
+ seatsChanged?(room: LobbyRoom<G>): void;
163
+ /** Whether the room seats through its game seats (`sitSeat` and the rest). */
164
+ usesSeats(room: LobbyRoom<G>): boolean;
165
+ /** Whether nobody may sit, stand, seat an AI or close a seat now (the game started, say). */
166
+ seatsFixed(room: LobbyRoom<G>): boolean;
167
+ /** Whether the AI and closed seats are the event's, not anybody's to change. */
168
+ fieldFixed?(room: LobbyRoom<G>): boolean;
169
+ /** The most game seats the room grows to. */
170
+ seatCeiling(room: LobbyRoom<G>): number;
171
+ /** The game seats grown to hold `seat`. */
172
+ growSeats(room: LobbyRoom<G>, seat: number): void;
173
+ /** Open seats past the room's own size taken away from the end. */
174
+ trimSeats(room: LobbyRoom<G>): void;
175
+ /** An AI took `seat` (`on`) or left it; the seat is already marked. */
176
+ aiSeated?(room: LobbyRoom<G>, seat: number, on: boolean): void;
177
+ /** Every member id `ids` names, in the game part, before the record's ids are replaced (account erase). */
178
+ anonymise?(room: LobbyRoom<G>, ids: ReadonlySet<string>): void;
179
+ /** The room is about to be forgotten (a close or the sweep): keep what it played, settle what it owes. */
180
+ ending?(room: LobbyRoom<G>, why: 'close' | 'sweep' | 'forget'): void;
181
+ /** A relay room's match seat count: set for a type whose room IS its match (`onRelayRoomOpened`). */
182
+ relaySeats?: number;
183
+ }
184
+ /** The fewest seats a room is left with when its seats are closed: one player and one more. */
185
+ export declare const MIN_OPEN_SEATS = 2;
186
+ export type CreateResult<V> = {
187
+ ok: true;
188
+ room: V;
189
+ } | {
190
+ ok: false;
191
+ reason: 'not-durable';
192
+ };
193
+ /** `no-match` covers BOTH "no such room" and "wrong password", on purpose: the HTTP layer must not be able to tell them apart. */
194
+ export type JoinResult<V> = {
195
+ ok: true;
196
+ room: V;
197
+ alreadyMember: boolean;
198
+ } | {
199
+ ok: false;
200
+ reason: 'no-match' | 'not-durable';
201
+ };
202
+ interface LeaveOk<V> {
203
+ ok: true;
204
+ room: V;
205
+ /** A match this leave forfeited, its games for the caller to end. */
206
+ forfeited?: {
207
+ tableId: string;
208
+ matchIds: string[];
209
+ };
210
+ }
211
+ export type LeaveResult<V> = LeaveOk<V> | {
212
+ ok: false;
213
+ reason: 'no-room' | 'not-member';
214
+ };
215
+ export type CloseRoomResult = {
216
+ ok: true;
217
+ matches: string[];
218
+ } | {
219
+ ok: false;
220
+ reason: 'no-room' | 'not-leader';
221
+ };
222
+ export type SitSeatResult<V> = {
223
+ ok: true;
224
+ room: V;
225
+ } | {
226
+ ok: false;
227
+ reason: 'no-room' | 'not-member' | 'not-draft' | 'not-lobby' | 'not-open' | 'bad-seat' | 'seat-taken' | 'pod-full' | 'historical';
228
+ };
229
+ export type CloseSeatResult<V> = {
230
+ ok: true;
231
+ room: V;
232
+ } | {
233
+ ok: false;
234
+ reason: 'no-room' | 'not-member' | 'not-leader' | 'not-draft' | 'not-lobby' | 'bad-seat' | 'seat-taken' | 'too-few' | 'historical';
235
+ };
236
+ export type StandSeatResult<V> = {
237
+ ok: true;
238
+ room: V;
239
+ } | {
240
+ ok: false;
241
+ reason: 'no-room' | 'not-member' | 'not-draft' | 'not-lobby';
242
+ };
243
+ export interface AvatarChange {
244
+ roomId: string;
245
+ memberId: string;
246
+ /** The new, normalised value; null when it was cleared. */
247
+ avatarId: string | null;
248
+ }
249
+ /** The room-level app blob's version. Additive fields never bump it: each reads with a default. */
250
+ export declare const ROOM_APP_VERSION = 2;
251
+ export interface LobbyCoreOptions<I extends RoomCreateInput> {
252
+ store: FileRoomStore;
253
+ now: () => number;
254
+ log: LobbyLog;
255
+ /** The hooks for a room of `gameType`, or undefined for a type this server does not host (its rooms quarantine). */
256
+ typeOf: (gameType: string) => RoomTypeHooks<unknown, I> | undefined;
257
+ /** What a room bound to a watchparty room is made as (`bindWatchparty`). */
258
+ watchpartyRoom: I;
259
+ }
260
+ /**
261
+ * The room-level codec: the platform's fields here, the game seats and game part through the room's
262
+ * type. Its errors name the FIELD, never a value: the message reaches the quarantine reason and the
263
+ * log, and a value here could be the hash.
264
+ */
265
+ export declare function roomAppCodec(typeOf: (gameType: string) => Pick<RoomTypeHooks<unknown>, 'decode' | 'writes'> | undefined): RoomCodec<StoredRoomApp, unknown>;
266
+ /**
267
+ * The lobby core. `V` is the view a room of the hosting game reads as (the platform's fields and
268
+ * the type's part); `I` the create input. A game's lobby extends it with its own operations, which
269
+ * reach the rooms through the protected members below.
270
+ */
271
+ export declare class RoomLobby<V extends PlatformRoomView, I extends RoomCreateInput> {
272
+ #private;
273
+ protected readonly store: FileRoomStore;
274
+ protected readonly now: () => number;
275
+ protected readonly log: LobbyLog;
276
+ constructor(opts: LobbyCoreOptions<I>);
277
+ /** `room`'s own hooks. A room is only ever installed with a type that has them (`openRoomStore`, `#insert`). */
278
+ protected hooksOf(room: LobbyRoom): RoomTypeHooks<unknown, I>;
279
+ /** The room by id, of whatever type. */
280
+ protected room(roomId: string): LobbyRoom | undefined;
281
+ protected rooms(): IterableIterator<LobbyRoom>;
282
+ /** Boot only: install a room decoded from disk. */
283
+ protected install(room: LobbyRoom, secret: Secret | null): void;
284
+ protected view(room: LobbyRoom): V;
285
+ /** Save `room` and tell every `onChange` listener. Every mutation ends here. */
286
+ protected persist(room: LobbyRoom): void;
287
+ /** Tell every `onChange` listener `roomId` reads differently now, with nothing written. */
288
+ protected changed(roomId: string): void;
289
+ /**
290
+ * Be told every time a room is written, created or forgotten. Every mutation goes through one
291
+ * persist, so this is every change a read could see and nothing else: a read (`touch`, `get`,
292
+ * `list`) never fires it. Returns the unsubscribe.
293
+ */
294
+ onChange(listener: (roomId: string) => void): () => void;
295
+ /**
296
+ * Told once, at boot, how a room whose type is its own match (`RoomTypeHooks.relaySeats`) opens
297
+ * that match: called the moment such a room is created, and at once for every such room already
298
+ * open (rooms restored from disk, which no match outlived). Unset, such a room has no match behind it.
299
+ */
300
+ onRelayRoomOpened(hook: (roomId: string, seatCount: number, gameType: string) => void): void;
301
+ list(): V[];
302
+ /**
303
+ * The rooms the front page offers: `list()` minus the rooms nobody has touched for `staleMs`. A
304
+ * room with a game in progress is always offered. Same order as `list()`.
305
+ */
306
+ offered(staleMs?: number): V[];
307
+ /** Record that `memberId` has `roomId` open now. A non-member or unknown room is ignored. */
308
+ touch(roomId: string, memberId: string): void;
309
+ get(roomId: string): V | undefined;
310
+ /** Whether `memberId` is a member of `roomId`. False when there is no such room. */
311
+ isMember(roomId: string, memberId: string): boolean;
312
+ /** Per-member opaque state owned by the game's routes (the deck a seat holds). Not part of the view. undefined when unset / no room / not a member. */
313
+ playerState(roomId: string, memberId: string): unknown;
314
+ /** false when there is no such room or memberId is not a member. Persisted. */
315
+ setPlayerState(roomId: string, memberId: string, state: unknown): boolean;
316
+ /** The members who play, in seat order. */
317
+ protected playersOf(room: LobbyRoom): string[];
318
+ /** `seatsShutUntil`, for a room in hand. */
319
+ protected seatsShut(room: LobbyRoom): number | null;
320
+ /**
321
+ * When a room made for an event opens its seats (`seatsOpenAt`), while they are still shut by the
322
+ * lobby's clock: until then nobody sits, is seated on joining or on Ready, and nothing deals.
323
+ * Null once they are open, for a room no event made, and for no such room.
324
+ */
325
+ seatsShutUntil(roomId: string): number | null;
326
+ /**
327
+ * The seat this member holds in the room's game (the view's `seats`), or null: watching, not a
328
+ * member, or no such room. What a relay match seats a socket by, so the relay and every screen
329
+ * name the same seat holders.
330
+ */
331
+ gameSeatOf(roomId: string, memberId: string): number | null;
332
+ /**
333
+ * A member steps out. Removed from `members`; their state and Ready go with their row. If they
334
+ * led the room, leadership passes to whichever remaining member joined EARLIEST (R16). What it
335
+ * costs their game is the type's (`RoomTypeHooks.leaving`). A room left by its last member is not
336
+ * deleted here (the idle sweep owns deletion) but leaves `offered()` the instant it empties.
337
+ * `no-room` and `not-member` are both answered the same 404 by the HTTP layer.
338
+ */
339
+ leave(roomId: string, memberId: string): LeaveResult<V>;
340
+ create(caller: Caller, input: I): CreateResult<V>;
341
+ /**
342
+ * The room a watchparty room's game slot binds to (D21): `wp-` plus a digest of the watchparty
343
+ * room, so everyone in that room arrives at the same table without anyone passing an id around.
344
+ * Made on first use with the caller as its creator and leader, joined after that.
345
+ */
346
+ bindWatchparty(caller: Caller, watchpartyRoom: string): JoinResult<V>;
347
+ /** Idempotent for an existing member, who needs no password again. */
348
+ join(roomId: string, caller: Caller, password?: string): JoinResult<V>;
349
+ /**
350
+ * Call `caller.id` by `caller.name` in every room they are a member of. The name was copied once, at
351
+ * join, so a key renamed in the registry kept its first name in every room it had joined
352
+ * (2026-10-26). Writes only the rooms whose copy moved.
353
+ */
354
+ rename(caller: Pick<Caller, 'id' | 'name'>): void;
355
+ /** false when there is no such room or the caller is not a member. Persisted. */
356
+ setReady(roomId: string, memberId: string, ready: boolean): boolean;
357
+ /**
358
+ * The member's OWN avatar, and nobody else's: `memberId` is always a derived participant id, so a
359
+ * browser cannot name a row that is not its own. Three states in, two stored: a non-blank string
360
+ * sets it; `null`, `''`, whitespace, an over-long value and a non-string clear it (`avatarIdOf`).
361
+ * `false` only when there is no such room or member. Written only when it changed.
362
+ */
363
+ setAvatar(roomId: string, memberId: string, avatarId: string | null): boolean;
364
+ /** Each member's registry userId, for looking up how they look. Never part of a view. */
365
+ usersOf(roomId: string): {
366
+ memberId: string;
367
+ userId: string;
368
+ }[];
369
+ /**
370
+ * A member's avatar picture and cosmetics, as prefs-api answered for them. In memory only: looked
371
+ * up again after a restart. A real change is announced as an avatar change, so a running match
372
+ * re-sends its seats, and to `onChange` with nothing written. `false` only when there is no such room or member.
373
+ */
374
+ setLook(roomId: string, memberId: string, look: Look | undefined): boolean;
375
+ /** Be told when a member's avatar actually CHANGES (never on an idempotent re-assert). Returns the unsubscribe. */
376
+ onAvatarChange(listener: (change: AvatarChange) => void): () => void;
377
+ /**
378
+ * Take a game seat. `seat` absent takes the first open one (their own counts as open), growing the
379
+ * room by one past the last when none is; given, it must be open and in reach. Moves the caller from
380
+ * any seat they held.
381
+ */
382
+ sitSeat(roomId: string, memberId: string, seat?: number): SitSeatResult<V>;
383
+ /** Give up a game seat. Idempotent: not seated is not a failure. */
384
+ standSeat(roomId: string, memberId: string): StandSeatResult<V>;
385
+ /** Put the AI in an open seat (`on`), or take it out. Any member. */
386
+ aiSeat(roomId: string, memberId: string, seat: number, on: boolean): SitSeatResult<V>;
387
+ /** Close an empty seat, or open a closed one: the leader's; never fewer than `MIN_OPEN_SEATS` open. */
388
+ closeSeat(roomId: string, memberId: string, seat: number, closed: boolean): CloseSeatResult<V>;
389
+ /**
390
+ * Forget every room untouched for longer than `idleMs` (or its type's own idle window), on disk as
391
+ * well as in memory. Never a room with a live game, never one its type spares. Returns the ids dropped.
392
+ */
393
+ sweep(idleMs?: number): string[];
394
+ /** Resolves once every room forgotten so far is gone from disk too (a failed delete is logged as `room-forget-failed`). */
395
+ removed(): Promise<void>;
396
+ /**
397
+ * Account erase: every room that still names one of `ids` names `to` instead, and is saved. Answers
398
+ * how many rooms changed. The person leaves first (`leave`), so leadership has passed on.
399
+ */
400
+ anonymise(ids: ReadonlySet<string>, to: string): number;
401
+ /** Move the start of the event a room was made for, and its seats' opening with it. False when there is no such room. */
402
+ reschedule(roomId: string, at: number): boolean;
403
+ /**
404
+ * The owner ends the room for everyone: it is forgotten, as the sweep forgets one, and its type keeps
405
+ * what it played first. Answers the matches it was playing, for the caller to stop. Any admin in a
406
+ * testing room may close it: the HTTP layer has already checked admin and membership.
407
+ */
408
+ close(roomId: string, callerId: string): CloseRoomResult;
409
+ /**
410
+ * Read every room file back, through `typeOf`: once, before the lobby is used. A record that cannot
411
+ * be read is quarantined and logged by room id and reason; the reason names what was wrong, never
412
+ * the bytes, which could include a password hash. Answers how many rooms are open.
413
+ */
414
+ open(): Promise<number>;
415
+ }
416
+ /**
417
+ * The room type of a game that keeps nothing of its own in the room (bomberman): no game part, its
418
+ * players in the platform's game seats, opened with `seats` of them and growing to `max`, an AI or a
419
+ * closed seat in any open one. `relaySeats` when the room is its own relay match.
420
+ */
421
+ export declare function plainRoomType<I extends RoomCreateInput>(size: {
422
+ seats: number;
423
+ max: number;
424
+ relaySeats?: number;
425
+ }): RoomTypeHooks<Record<string, never>, I>;
426
+ export {};