Repository navigation
Expand file tree
/
Copy pathtypes.ts
More file actions
292 lines (271 loc) · 14 KB
/
Copy pathtypes.ts
File metadata and controls
292 lines (271 loc) · 14 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
/**
* Public types of @agentstack/netplay (gene `sdk.netplay.gen1`).
*
* Mental model: a room is an append-only, server-ordered log of small JSON entries.
* Every client folds the same log with the same pure reducer, so every client computes
* the same lobby, the same seats and (for lockstep / fold games) the same game state.
*/
import type { Rng } from './rng.js';
/** Seat index 0..max-1. Spectators have seat -1. */
export type Seat = number;
/**
* How inputs become state.
* - `lockstep`: tick-synchronous. `step(state, inputs[])` runs once every seated player has an input
* for the next tick. Realtime games send one input per frame; turn-based games send one per turn.
* - `fold`: asynchronous commands. `apply(state, seat, input)` runs for each command in log order.
* Good for races (each seat has its own board) and open-information board games.
* - `authority`: hidden information. Only the authority (seat 0 today, a server script later)
* runs `apply`; other clients receive `view(state, seat)` projections.
*/
export type Mode = 'lockstep' | 'fold' | 'authority';
/** What happens to a seat that stays silent past `timeouts.turnMs` (lockstep) or `presenceMs` (all modes). */
export type TimeoutPolicy = 'idle' | 'forfeit';
export interface Outcome {
/** Winning seat, or -1 for a draw / no single winner. With `winners`: the first of them (or -1 when it is empty). */
winner: Seat;
/**
* Several winners at once: a team (2 on 2), a shared co-op win, joint first place. Takes precedence over `winner`
* when set; [] = nobody won. Read it with `outcomeWinners(o)`, which also covers the single-`winner` form.
*/
winners?: Seat[];
/** Optional finishing order (seat per place) for 3+ players. */
ranks?: Seat[];
/** Short machine reason: 'ko', 'score', 'forfeit', 'timeout', 'left', … */
reason?: string;
}
/** The sender of an audience command: room member id and seat (-1 = spectator). */
export interface Audience {
readonly id: string;
readonly seat: Seat;
}
export interface SetupCtx {
/** Match seed (same on every client). For `authority` it is private to the authority. */
readonly seed: number;
/** Number of seated players. */
readonly seats: number;
/** Seeded RNG for setup only. */
readonly rng: Rng;
/** Free-form room params passed to `createSession({ params })` by the room creator. */
readonly params: Readonly<Record<string, unknown>>;
}
export interface StepCtx {
/** Lockstep tick being computed (0-based), or the command index in `fold` / `authority`. */
readonly tick: number;
/** Server timestamp (ms) of the log entry that triggered this step. Deterministic. */
readonly now: number;
readonly seed: number;
/** RNG derived from (seed, tick): deterministic, no state to store. */
readonly rng: Rng;
/** Seats that are not playing any more (left or timed out). */
readonly absent: readonly boolean[];
}
/**
* A multiplayer game definition. Only `id`, `seats`, `mode`, `setup`, `input` and one of
* `step` (lockstep) / `apply` (fold, authority) are required. Keep every function pure and
* deterministic: no Date.now, no Math.random, no I/O — use `ctx.now` and `ctx.rng`.
*/
export interface GameDef<S, I, V = S> {
/** Stable id, also used for script ids and matchmaking queues. `[a-z0-9-]`. */
readonly id: string;
/** Rules/protocol version. Clients with a different version cannot sit together. */
readonly version: number;
readonly seats: { readonly min: number; readonly max: number };
readonly mode: Mode;
/** Initial state for one match. */
setup(ctx: SetupCtx): S;
/**
* Validate an untrusted input. Return the typed input, or `undefined` to reject it.
* Runs on every client for every entry (anti-cheat), so keep it cheap.
*/
input(raw: unknown, seat: Seat, state: S): I | undefined;
/** lockstep: advance one tick. Mutate `state` or return a new one. */
step?(state: S, inputs: readonly I[], ctx: StepCtx): S | void;
/** lockstep: input used for a seat that sent nothing (timed out, left). Default `null`. */
readonly idle?: I;
/** lockstep: hide inputs until every seat committed (commit–reveal). For simultaneous secret turns. */
readonly secret?: boolean;
/** fold / authority: apply one validated command. Mutate `state` or return a new one. */
apply?(state: S, seat: Seat, input: I, ctx: StepCtx): S | void;
/** Optional time-driven update (deadlines). Called with the server time before each entry. */
clock?(state: S, now: number, ctx: StepCtx): S | void;
/**
* fold / authority games with `clock`: while playing, the authority (or, in fold, every seat)
* appends a `clock` entry at least this often so time-driven logic (phase timers, bots) advances
* even when nobody acts. Default: the presence heartbeat (`presenceMs / 4`). Min 250.
*/
readonly clockMs?: number;
/** Finished? Return the outcome, or null while the match runs. */
outcome?(state: S): Outcome | null;
/**
* Audience commands (bets, cheers, votes): sent by anyone in the room, spectators included, with
* `session.audience(value)`, kept apart from player commands (`input` / `apply`). Validated and applied by every
* client that holds the state (fold / lockstep: everyone; authority: the host) at the entry's place in the log,
* so all clients agree. They never move the tick, never wait for anybody and never block a seat.
* lockstep games with their own fixed-step loop (`confirmed(t)`) must read the audience part from `session.model.state`.
*/
readonly audience?: {
/** Validate an untrusted audience command. `who.seat` is -1 for a spectator. Return `undefined` to reject. */
input(raw: unknown, who: Audience, state: S): unknown;
/** Apply a validated audience command. Mutate `state` or return a new one. */
apply(state: S, who: Audience, input: unknown, ctx: StepCtx): S | void;
/** Who may send: 'spectators' (default) or 'all' (players too). */
readonly from?: 'spectators' | 'all';
};
/** Projection for one seat (-1 = spectator). Required for `authority`; default identity. */
view?(state: S, seat: Seat): V;
/** State hash for desync detection. Default: FNV-1a over a canonical serialization. */
hash?(state: S): number;
readonly timeouts?: {
/** lockstep: max server-time wait for a missing seat's input on one tick/turn. Default: none. */
readonly turnMs?: number;
/** Seat with no entries for this long is `away`. Default 20000. */
readonly presenceMs?: number;
/** Default 'idle' (lockstep continues with `idle`); 'forfeit' ends a 2-seat match. */
readonly onTimeout?: TimeoutPolicy;
/**
* authority: after the host seat goes away (no entries for `presenceMs`), wait this long for it to come back
* (reconnect, or a reload with the same `secretSeed` refolds the match) before ending the match for everyone
* with `{ winner: -1, reason: 'host-lost' }`. A host that leaves ends it at once (`'host-left'`). Default 60000.
*/
readonly hostGraceMs?: number;
};
/** lockstep: report a state hash every N ticks (default 30; 1 for turn-based). 0 disables. */
readonly hashEvery?: number;
}
/** One entry of the room log as delivered by a transport. `from` and `t` are set by the server. */
export interface Entry<B = Body> {
readonly seq: number;
readonly from: string;
readonly t: number;
/** Private entry addressed to one user id (authority views). */
readonly to?: string;
readonly body: B;
}
/**
* Wire bodies. Short keys keep polling payloads small. `m` = match number (rematch counter).
* `n` = the sender's own entry counter (set by Session): the reducer drops an entry whose `n` is not
* above the last one seen from that sender, so a re-sent append (lost response, retry) never applies twice.
*/
export type Body = BodyKind & { n?: number };
type BodyKind =
/** `locals`: names of extra players on the same device (local seats, see SessionOptions.locals). */
| { k: 'hello'; g: string; v: number; name?: string; spectate?: boolean; params?: Record<string, unknown>; locals?: string[] }
/** Lobby only: replace this member's local seats. */
| { k: 'locals'; names: string[] }
| { k: 'ready' }
/** `x[j-1]`: the batch of local seat j for the same ticks as `d` (missing = idle). */
| { k: 'in'; m: number; t: number; d: unknown[]; salt?: string; x?: unknown[][]; /** adaptiveDelay: the sender's echo time (ms) */ r?: number }
| { k: 'commit'; m: number; t: number; h: number }
/** `l`: local seat index (0 / missing = the member's own seat). */
/** `l`: one local seat of the sender's device; `a: 1`: every seat of that device (own first, then locals) — one entry, e.g. a clock report. */
| { k: 'cmd'; m: number; d: unknown; l?: number; a?: 1 }
| { k: 'hash'; m: number; t: number; h: number }
| { k: 'view'; m: number; s: number; seat: Seat; d: unknown; o?: Outcome | null }
| { k: 'clock' }
/** Audience command (`GameDef.audience`), from a spectator or (with `from: 'all'`) a player. */
| { k: 'aud'; m: number; d: unknown }
/** This member's tab went to the background: do not wait for its seats (any later entry brings them back). */
| { k: 'away' }
| { k: 'rematch'; m: number }
/** `l`: only that local seat leaves; missing = the member and all its local seats. */
| { k: 'leave'; l?: number };
export type PlayerStatus = 'on' | 'away' | 'left';
export interface PlayerInfo {
readonly id: string;
readonly seat: Seat;
readonly name: string;
readonly status: PlayerStatus;
readonly ready: boolean;
/** Server time of this player's last entry. */
readonly lastT: number;
/** Local seat: the member id of the device that plays it (same screen as that player). Missing = an own member. */
readonly owner?: string;
/** Local seat index on its device (1, 2, …); 0 = the member's own seat. */
readonly local?: number;
/** `away` because the device said so (tab in the background, `session.away(true)`), not because it went silent. */
readonly hidden?: boolean;
}
export type Phase = 'lobby' | 'playing' | 'over';
/** One finished match in this room, derived from the room log (same on every client, survives a reload). */
export interface MatchResult {
readonly match: number;
/** Winner's player id ('' = draw / no single winner). By id, not seat: seats can change between matches. */
readonly winner: string;
/** Every winner's player id, present only when the outcome had several (`Outcome.winners`); `winner` is the first. */
readonly winners?: readonly string[];
readonly reason?: string;
}
export interface Desync {
readonly tick: number;
readonly hashes: Readonly<Record<string, number>>;
}
/** Everything a UI needs, recomputed after every batch of entries. */
export interface Snapshot<S, V = S> {
readonly room: string;
readonly self: string;
/** My seat, -1 when spectating or not joined. */
readonly seat: Seat;
/** Every seat played on this device: my own seat first, then my local seats in local order (empty when spectating). */
readonly seats: readonly Seat[];
readonly phase: Phase;
readonly match: number;
readonly players: readonly PlayerInfo[];
readonly spectators: number;
/** Confirmed lockstep tick / applied command count. */
readonly tick: number;
/** Full state (lockstep / fold, or the authority itself). Null on non-authority clients. */
readonly state: S | null;
/** What this client should render: `view(state, seat)` or the last view sent by the authority. */
readonly view: V | null;
readonly outcome: Outcome | null;
readonly desync: Desync | null;
/** Seats that voted for a rematch in the current `over` phase. */
readonly rematch: readonly Seat[];
/** Finished matches in this room so far, oldest first (series score: see `seriesScore`). */
readonly results: readonly MatchResult[];
/** Last rejection or protocol problem, for UI hints and logs. */
readonly notice: string | null;
/** authority: the host is away — ms left (as of the last entry) before the match ends as 'host-lost'; null = host present. */
readonly hostWaitMs: number | null;
readonly connection: ConnectionState;
/** Why the connection is down or slowed: 'auth' (sign in first), 'rate' (server asked to slow down), 'not-published' (room script missing); null = no known reason. */
readonly issue: 'auth' | 'rate' | 'not-published' | 'full' | null;
}
export type ConnectionState = 'idle' | 'connecting' | 'online' | 'reconnecting' | 'offline';
/** A live connection to one room. */
export interface Link {
/** Server-assigned identity of this client (user id). */
readonly self: string;
/**
* Append a body to the room log (optionally private to one user id). Called without awaiting:
* the transport MUST keep call order (queue internally if the wire is async).
*/
send(body: Body, to?: string): Promise<void>;
/** Optional: several bodies in one request, same ordering rules (HTTP transports — request budget). */
sendMany?(items: readonly { body: Body; to?: string }[]): Promise<void>;
/** Optional (polling transports): poll no faster than `ms` (background tab: battery, data, request budget); null = normal pace, poll now. */
pace?(ms: number | null): void;
close(): void;
}
export interface TransportCaps {
/** Entries with `to` are delivered only to that user (server-enforced). */
readonly privateEntries: boolean;
/** Human label for logs: 'memory', 'polling', 'stackscript', 'wss'. */
readonly kind: string;
/** Hint: send queued inputs at most this often (ms) — request budget of HTTP transports. Session option `sendEveryMs` overrides. */
readonly sendEveryMs?: number;
}
/**
* Pluggable transport: memory (tests), polling (any HTTP log API), stackscript (generated room
* script via the SDK StackScript client), wss (push, when the platform upgrade works).
*/
export interface Transport {
readonly caps: TransportCaps;
connect(room: string, opts: ConnectOptions): Promise<Link>;
}
export interface ConnectOptions {
/** Deliver entries with seq > afterSeq (reconnect resumes here). */
readonly afterSeq: number;
readonly onEntries: (entries: readonly Entry[]) => void;
readonly onStatus?: (s: ConnectionState, detail?: string) => void;
}