cotchu 0.0.1 → 0.1.0
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.
- package/README.md +19 -3
- package/dist/cli.js +119 -0
- package/dist/cotchu.min.js +2 -0
- package/dist/cotchu.min.js.map +7 -0
- package/dist/index.d.ts +519 -0
- package/dist/index.js +1749 -0
- package/dist/index.js.map +7 -0
- package/package.json +42 -5
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,519 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Every error a room can send, keyed by its stable code. Codes never change
|
|
3
|
+
* meaning once shipped; messages may be reworded. A specific error may carry
|
|
4
|
+
* a more precise sentence than the default here.
|
|
5
|
+
*/
|
|
6
|
+
declare const ERRORS: {
|
|
7
|
+
readonly bad_message: {
|
|
8
|
+
readonly fatal: false;
|
|
9
|
+
readonly message: "That message isn't valid Cotchu protocol; send it through the cotchu SDK or match the formats in llms.txt.";
|
|
10
|
+
};
|
|
11
|
+
readonly hello_required: {
|
|
12
|
+
readonly fatal: false;
|
|
13
|
+
readonly message: "The room hasn't had your hello yet; send a hello message first, or use cotchu.join(), which sends it for you.";
|
|
14
|
+
};
|
|
15
|
+
readonly unsupported_version: {
|
|
16
|
+
readonly fatal: true;
|
|
17
|
+
readonly message: "This client speaks a different protocol version than the room; update the cotchu package to the latest.";
|
|
18
|
+
};
|
|
19
|
+
readonly bad_key: {
|
|
20
|
+
readonly fatal: true;
|
|
21
|
+
readonly message: "That key isn't a valid Cotchu publishable key; pass your project's pk_ key as the key option to cotchu.join().";
|
|
22
|
+
};
|
|
23
|
+
readonly bad_origin: {
|
|
24
|
+
readonly fatal: true;
|
|
25
|
+
readonly message: "This page's website isn't on your project's allowed origins; add it to the project's allowed origins, then reload.";
|
|
26
|
+
};
|
|
27
|
+
readonly room_full: {
|
|
28
|
+
readonly fatal: true;
|
|
29
|
+
readonly message: "Every seat in this room is taken; try again in a moment or join a different room name.";
|
|
30
|
+
};
|
|
31
|
+
readonly room_limit: {
|
|
32
|
+
readonly fatal: true;
|
|
33
|
+
readonly message: "This project already has 50 rooms open, its current limit; finished rooms close a minute after their last player leaves.";
|
|
34
|
+
};
|
|
35
|
+
readonly type_mismatch: {
|
|
36
|
+
readonly fatal: true;
|
|
37
|
+
readonly message: "This room already exists with a different type; join with the room's type or pick a new room name.";
|
|
38
|
+
};
|
|
39
|
+
readonly wrong_room_type: {
|
|
40
|
+
readonly fatal: false;
|
|
41
|
+
readonly message: "That call doesn't work in this type of room; use set() in shared rooms, move() in turns rooms and input() in realtime rooms.";
|
|
42
|
+
};
|
|
43
|
+
readonly rate_limited: {
|
|
44
|
+
readonly fatal: false;
|
|
45
|
+
readonly message: "This player sent more than 60 messages a second; batch changes into fewer messages or send inputs on a fixed timer.";
|
|
46
|
+
};
|
|
47
|
+
readonly too_large: {
|
|
48
|
+
readonly fatal: false;
|
|
49
|
+
readonly message: "That message is over 16 KB; send smaller changes, or split large data across several paths.";
|
|
50
|
+
};
|
|
51
|
+
readonly forbidden_path: {
|
|
52
|
+
readonly fatal: false;
|
|
53
|
+
readonly message: "This player isn't allowed to write that path; write only to paths the room's writable list allows.";
|
|
54
|
+
};
|
|
55
|
+
readonly bad_move: {
|
|
56
|
+
readonly fatal: false;
|
|
57
|
+
readonly message: "That move doesn't match the room's move schema; send a move shaped the way the room's moveSchema describes.";
|
|
58
|
+
};
|
|
59
|
+
readonly not_your_turn: {
|
|
60
|
+
readonly fatal: false;
|
|
61
|
+
readonly message: "It isn't this player's turn; wait for a turn event naming this player before calling move().";
|
|
62
|
+
};
|
|
63
|
+
readonly balance_empty: {
|
|
64
|
+
readonly fatal: true;
|
|
65
|
+
readonly message: "This project's Cotchu balance is empty, so new rooms can't open; top up the balance in the console.";
|
|
66
|
+
};
|
|
67
|
+
readonly action_rejected: {
|
|
68
|
+
readonly fatal: false;
|
|
69
|
+
readonly message: "The room's script turned that action down; check the game's rules, or read the message the script gave.";
|
|
70
|
+
};
|
|
71
|
+
readonly script_error: {
|
|
72
|
+
readonly fatal: false;
|
|
73
|
+
readonly message: "The room's script failed, so the room restarted it from its last save; try again, and fix the script if it keeps happening.";
|
|
74
|
+
};
|
|
75
|
+
readonly script_not_found: {
|
|
76
|
+
readonly fatal: true;
|
|
77
|
+
readonly message: "This project has no deployed script by that name; deploy it with npx cotchu deploy room.js --name <name>, then join again.";
|
|
78
|
+
};
|
|
79
|
+
readonly bad_path: {
|
|
80
|
+
readonly fatal: false;
|
|
81
|
+
readonly message: "That path runs through a value that isn't an object; set the parent to an object first, or write a different path.";
|
|
82
|
+
};
|
|
83
|
+
readonly unknown_player: {
|
|
84
|
+
readonly fatal: false;
|
|
85
|
+
readonly message: "No player with that id is in the room; send direct messages only to ids from the room's player list.";
|
|
86
|
+
};
|
|
87
|
+
readonly internal: {
|
|
88
|
+
readonly fatal: false;
|
|
89
|
+
readonly message: "Something went wrong inside Cotchu; retry, and if it keeps happening, report it with the room name and time.";
|
|
90
|
+
};
|
|
91
|
+
readonly replaced: {
|
|
92
|
+
readonly fatal: true;
|
|
93
|
+
readonly message: "This seat was taken over by a newer connection using the same resume token; keep one connection per player.";
|
|
94
|
+
};
|
|
95
|
+
readonly room_closed: {
|
|
96
|
+
readonly fatal: true;
|
|
97
|
+
readonly message: "This room is closed because you left or it ended; call cotchu.join() again to get a new room object.";
|
|
98
|
+
};
|
|
99
|
+
readonly unreachable: {
|
|
100
|
+
readonly fatal: true;
|
|
101
|
+
readonly message: "Couldn't reach a Cotchu room; check the network and any url option you passed, then call cotchu.join() again.";
|
|
102
|
+
};
|
|
103
|
+
readonly not_found: {
|
|
104
|
+
readonly fatal: true;
|
|
105
|
+
readonly message: "Nothing lives at that path; connect with the cotchu SDK, which opens /v1/rooms/<project>/<room> for you.";
|
|
106
|
+
};
|
|
107
|
+
readonly bad_room: {
|
|
108
|
+
readonly fatal: true;
|
|
109
|
+
readonly message: "Project ids use lowercase letters and digits, and room names letters, digits, '.', '_' and '-' up to 64 characters; fix the URL.";
|
|
110
|
+
};
|
|
111
|
+
readonly bad_script: {
|
|
112
|
+
readonly fatal: true;
|
|
113
|
+
readonly message: "That script couldn't be loaded; fix what the message describes in room.js, then deploy again.";
|
|
114
|
+
};
|
|
115
|
+
readonly bad_region: {
|
|
116
|
+
readonly fatal: true;
|
|
117
|
+
readonly message: `That region isn't one Cotchu knows; use auto or one of ${string}.`;
|
|
118
|
+
};
|
|
119
|
+
readonly upgrade_required: {
|
|
120
|
+
readonly fatal: true;
|
|
121
|
+
readonly message: "Rooms only speak WebSocket; open the URL with new WebSocket(), or let cotchu.join() do it for you.";
|
|
122
|
+
};
|
|
123
|
+
};
|
|
124
|
+
type ErrorCode = keyof typeof ERRORS;
|
|
125
|
+
|
|
126
|
+
/** A location in a room's shared state, one key per level: `["players", "abc", "x"]`. */
|
|
127
|
+
type Path = string[];
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* Room types. The first joiner picks one; it can't change afterwards. `script`
|
|
131
|
+
* rooms run the project's own deployed room script (docs/plans/room-scripts.md).
|
|
132
|
+
*/
|
|
133
|
+
declare const ROOM_TYPES: readonly ["shared", "turns", "realtime", "script"];
|
|
134
|
+
type RoomType = (typeof ROOM_TYPES)[number];
|
|
135
|
+
/**
|
|
136
|
+
* Durable Object location hints. Best effort: `sam`, `afr` and `me` currently
|
|
137
|
+
* place rooms elsewhere, and only the hint on a room's first request counts.
|
|
138
|
+
*/
|
|
139
|
+
declare const REGIONS: readonly ["wnam", "enam", "sam", "weur", "eeur", "apac", "apac-ne", "apac-se", "oc", "afr", "me"];
|
|
140
|
+
type Region = (typeof REGIONS)[number];
|
|
141
|
+
/** What a client may ask for: a region, or `auto` to place the room near the first joiner. */
|
|
142
|
+
type RegionOption = Region | "auto";
|
|
143
|
+
|
|
144
|
+
declare const SCHEMA_TYPES: readonly ["object", "array", "string", "number", "integer", "boolean", "null"];
|
|
145
|
+
type SchemaType = (typeof SCHEMA_TYPES)[number];
|
|
146
|
+
interface MoveSchema {
|
|
147
|
+
type?: SchemaType;
|
|
148
|
+
/** The value must equal one of these. */
|
|
149
|
+
enum?: JsonValue[];
|
|
150
|
+
properties?: {
|
|
151
|
+
[key: string]: MoveSchema;
|
|
152
|
+
};
|
|
153
|
+
required?: string[];
|
|
154
|
+
/** false: no fields beyond `properties`. Default true. */
|
|
155
|
+
additionalProperties?: boolean;
|
|
156
|
+
items?: MoveSchema;
|
|
157
|
+
minItems?: number;
|
|
158
|
+
maxItems?: number;
|
|
159
|
+
minimum?: number;
|
|
160
|
+
maximum?: number;
|
|
161
|
+
minLength?: number;
|
|
162
|
+
maxLength?: number;
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/**
|
|
166
|
+
* The v1 wire protocol: JSON text frames over one WebSocket. Every message
|
|
167
|
+
* has `t`, its type. Messages a client may tag with `id` get that `id` echoed
|
|
168
|
+
* on any `err` they cause, so the SDK can fail the right call.
|
|
169
|
+
*/
|
|
170
|
+
|
|
171
|
+
type JsonPrimitive = string | number | boolean | null;
|
|
172
|
+
type JsonValue = JsonPrimitive | JsonValue[] | JsonObject;
|
|
173
|
+
interface JsonObject {
|
|
174
|
+
[key: string]: JsonValue;
|
|
175
|
+
}
|
|
176
|
+
/** A room's rules. The first joiner sets them; later joiners get them in `welcome`. */
|
|
177
|
+
interface RoomConfig {
|
|
178
|
+
type: RoomType;
|
|
179
|
+
seats: number;
|
|
180
|
+
/** `shared`/`turns`: paths players may write (see paths.ts). Unset means every path. */
|
|
181
|
+
writable?: string[];
|
|
182
|
+
/** `turns`: milliseconds per turn before the room moves on. Unset means no timer. */
|
|
183
|
+
turnMs?: number;
|
|
184
|
+
/** `turns`: moves must match this schema (a JSON Schema subset; see schema.ts). */
|
|
185
|
+
moveSchema?: MoveSchema;
|
|
186
|
+
/** `realtime`: snapshots per second. `script`: onTick calls per second, if the script has onTick. */
|
|
187
|
+
tickHz?: number;
|
|
188
|
+
/** `script`: the deployed script this room runs, pinned to the version it opened with. */
|
|
189
|
+
script?: {
|
|
190
|
+
name: string;
|
|
191
|
+
version: string;
|
|
192
|
+
};
|
|
193
|
+
}
|
|
194
|
+
/**
|
|
195
|
+
* What a joiner may ask for. Ignored by a room that already exists, except
|
|
196
|
+
* `type`, which must match. `script` names a deployed script; the room pins its
|
|
197
|
+
* current version.
|
|
198
|
+
*/
|
|
199
|
+
interface RoomOptions extends Partial<Omit<RoomConfig, "script">> {
|
|
200
|
+
script?: string;
|
|
201
|
+
}
|
|
202
|
+
interface Player {
|
|
203
|
+
id: string;
|
|
204
|
+
name: string;
|
|
205
|
+
}
|
|
206
|
+
/** `turns` rooms: one entry in the room's move history. */
|
|
207
|
+
interface Move {
|
|
208
|
+
/** Player id that made the move. */
|
|
209
|
+
by: string;
|
|
210
|
+
data: JsonValue;
|
|
211
|
+
}
|
|
212
|
+
type PatchOp =
|
|
213
|
+
/** Put `value` at `path`, creating missing parents. */
|
|
214
|
+
{
|
|
215
|
+
op: "set";
|
|
216
|
+
path: Path;
|
|
217
|
+
value: JsonValue;
|
|
218
|
+
}
|
|
219
|
+
/** Shallow-merge `value` into the object at `path`. An empty path merges into the root. */
|
|
220
|
+
| {
|
|
221
|
+
op: "merge";
|
|
222
|
+
path: Path;
|
|
223
|
+
value: JsonObject;
|
|
224
|
+
}
|
|
225
|
+
/** Remove whatever is at `path`. */
|
|
226
|
+
| {
|
|
227
|
+
op: "delete";
|
|
228
|
+
path: Path;
|
|
229
|
+
};
|
|
230
|
+
interface HelloMessage {
|
|
231
|
+
t: "hello";
|
|
232
|
+
/** PROTOCOL_VERSION the client speaks. */
|
|
233
|
+
v: number;
|
|
234
|
+
/** Publishable project key (`pk_…`). Sent here, never in the URL. */
|
|
235
|
+
key: string;
|
|
236
|
+
/** SDK name and version, e.g. `cotchu-js/0.1.0`. */
|
|
237
|
+
sdk: string;
|
|
238
|
+
/** Display name for this player. */
|
|
239
|
+
name?: string;
|
|
240
|
+
/** Player sign-in token (accounts arrive in a later milestone). */
|
|
241
|
+
token?: string;
|
|
242
|
+
/** `resume` from an earlier `welcome`, to take back a seat within RESUME_WINDOW_MS. */
|
|
243
|
+
resume?: string;
|
|
244
|
+
/** Rules for the room if this hello creates it. */
|
|
245
|
+
room?: RoomOptions;
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* Every error the SDK throws, rejects with or emits. `message` is one
|
|
250
|
+
* sentence: what went wrong, then how to fix it. `code` is stable; match on
|
|
251
|
+
* it, not on the message.
|
|
252
|
+
*/
|
|
253
|
+
declare class CotchuError extends Error {
|
|
254
|
+
readonly code: ErrorCode | (string & {});
|
|
255
|
+
readonly name = "CotchuError";
|
|
256
|
+
/** True when the room is closed for good and the SDK won't reconnect. */
|
|
257
|
+
readonly fatal: boolean;
|
|
258
|
+
constructor(code: ErrorCode | (string & {}), message?: string);
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
/** Typed event emitter. `Events` maps each event name to its argument list. */
|
|
262
|
+
declare class Emitter<Events extends Record<keyof Events, unknown[]>> {
|
|
263
|
+
private readonly listeners;
|
|
264
|
+
/** Calls `listener` on every `event`. Returns a function that stops it. */
|
|
265
|
+
on<E extends keyof Events>(event: E, listener: (...args: Events[E]) => void): () => void;
|
|
266
|
+
/** Calls `listener` on the next `event` only. */
|
|
267
|
+
once<E extends keyof Events>(event: E, listener: (...args: Events[E]) => void): () => void;
|
|
268
|
+
off<E extends keyof Events>(event: E, listener: (...args: Events[E]) => void): void;
|
|
269
|
+
/** Returns false when nobody was listening. A throwing listener is reported, not fatal. */
|
|
270
|
+
protected emit<E extends keyof Events>(event: E, ...args: Events[E]): boolean;
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
/** A path as a game writes it: `"players.me.x"`, or `["players", id, "x"]` for keys that contain dots. */
|
|
274
|
+
type PathInput = string | readonly string[];
|
|
275
|
+
|
|
276
|
+
/**
|
|
277
|
+
* Remembers a tab's seat across reloads, so a player who reloads or reopens
|
|
278
|
+
* the tab within the resume window gets the same seat back.
|
|
279
|
+
*
|
|
280
|
+
* The token lives in sessionStorage (one per tab) but only while the page is
|
|
281
|
+
* going away: it's read and deleted on join, and written again on `pagehide`.
|
|
282
|
+
* A reload or a reopened tab finds it. A duplicated tab copies sessionStorage
|
|
283
|
+
* while the token is absent, so the copy gets its own seat instead of taking
|
|
284
|
+
* the original's.
|
|
285
|
+
*/
|
|
286
|
+
declare class SeatMemory {
|
|
287
|
+
private readonly key;
|
|
288
|
+
private readonly browser;
|
|
289
|
+
private token;
|
|
290
|
+
private readonly onPageHide;
|
|
291
|
+
private constructor();
|
|
292
|
+
/** Null outside browsers, or when storage is blocked (private mode, sandboxed frames). */
|
|
293
|
+
static for(project: string, room: string): SeatMemory | null;
|
|
294
|
+
/** Returns the remembered token, if any, and forgets it. */
|
|
295
|
+
take(): string | undefined;
|
|
296
|
+
/** From now on, saves the current token whenever the page is hidden or unloaded. */
|
|
297
|
+
watch(token: () => string | undefined): void;
|
|
298
|
+
/** Stops saving and forgets the token: the player left for good. */
|
|
299
|
+
forget(): void;
|
|
300
|
+
private write;
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
type RoomStatus = "connecting" | "connected" | "reconnecting" | "closed";
|
|
304
|
+
interface StateChange {
|
|
305
|
+
/** The ops that changed the state. Empty when `reset` is true. */
|
|
306
|
+
ops: PatchOp[];
|
|
307
|
+
/** Player id that made the change, or null when the room did. */
|
|
308
|
+
by: string | null;
|
|
309
|
+
/** True when the whole state was replaced: on first listen, after a reconnect, or when the room rejected a write. */
|
|
310
|
+
reset: boolean;
|
|
311
|
+
}
|
|
312
|
+
interface RoomEvents {
|
|
313
|
+
/** The shared state changed. Fires right away for a new listener, then on every change. */
|
|
314
|
+
state: [state: JsonObject, change: StateChange];
|
|
315
|
+
join: [player: Player];
|
|
316
|
+
leave: [player: Player];
|
|
317
|
+
/** Something another player sent with send(). */
|
|
318
|
+
message: [data: JsonValue, from: Player];
|
|
319
|
+
/** `turns` rooms: the turn passed. `player` is null while nobody is seated. */
|
|
320
|
+
turn: [player: Player | null, deadline: number | null];
|
|
321
|
+
/** `turns` rooms: someone moved. `n` is the move's place in room.moves. */
|
|
322
|
+
move: [data: JsonValue, from: Player, n: number];
|
|
323
|
+
/** `realtime` rooms: new snapshot of everyone's latest input. */
|
|
324
|
+
snap: [inputs: Record<string, JsonValue>, tick: number];
|
|
325
|
+
/** `script` rooms: an event the room's script sent with room.broadcast() or room.send(). */
|
|
326
|
+
event: [name: string, data: JsonValue];
|
|
327
|
+
/**
|
|
328
|
+
* Anything changed: state, players, turn, moves, inputs or status. Fires
|
|
329
|
+
* right away for a new listener. The simplest correct game re-renders
|
|
330
|
+
* everything from the room's getters here.
|
|
331
|
+
*/
|
|
332
|
+
change: [];
|
|
333
|
+
/** Something went wrong. With no listener, the SDK logs it with console.warn instead. */
|
|
334
|
+
error: [error: CotchuError];
|
|
335
|
+
status: [status: RoomStatus];
|
|
336
|
+
}
|
|
337
|
+
/** What the room needs to (re)connect. Built and checked by cotchu.join(). */
|
|
338
|
+
interface Connection {
|
|
339
|
+
url: string;
|
|
340
|
+
hello: HelloMessage;
|
|
341
|
+
WebSocket: typeof WebSocket;
|
|
342
|
+
/** Keeps the seat across reloads of this tab; null outside browsers or when turned off. */
|
|
343
|
+
seats: SeatMemory | null;
|
|
344
|
+
}
|
|
345
|
+
/**
|
|
346
|
+
* A joined room. Get one from `cotchu.join()`. Writes show up locally at once
|
|
347
|
+
* and reach everyone else through the room; the room's order wins, so every
|
|
348
|
+
* player ends up with the same state.
|
|
349
|
+
*/
|
|
350
|
+
declare class Room extends Emitter<RoomEvents> {
|
|
351
|
+
private readonly connection;
|
|
352
|
+
/** The room's name, as passed to cotchu.join(). */
|
|
353
|
+
readonly name: string;
|
|
354
|
+
private me_;
|
|
355
|
+
private config_;
|
|
356
|
+
private readonly players_;
|
|
357
|
+
/** State in the room's order, as confirmed by the room. */
|
|
358
|
+
private confirmed;
|
|
359
|
+
/** What the game sees: `confirmed` plus this player's writes the room hasn't confirmed yet. */
|
|
360
|
+
private view;
|
|
361
|
+
private inflight;
|
|
362
|
+
private turn_;
|
|
363
|
+
private moves_;
|
|
364
|
+
private snap_;
|
|
365
|
+
private private_;
|
|
366
|
+
/** `script` rooms: act() calls waiting for the script's answer, by message id. */
|
|
367
|
+
private readonly acts;
|
|
368
|
+
private readonly outbox;
|
|
369
|
+
private nextId;
|
|
370
|
+
private ws;
|
|
371
|
+
private welcomed;
|
|
372
|
+
private status_;
|
|
373
|
+
private resume;
|
|
374
|
+
private attempt;
|
|
375
|
+
private lastSeen;
|
|
376
|
+
private helloTimer;
|
|
377
|
+
private reconnectTimer;
|
|
378
|
+
private heartbeat;
|
|
379
|
+
private settle;
|
|
380
|
+
/** The room's last reason for turning a join attempt away, if any; join() rejects with it when it gives up. */
|
|
381
|
+
private refusal;
|
|
382
|
+
/** @internal Use `cotchu.join()`. */
|
|
383
|
+
constructor(name: string, connection: Connection);
|
|
384
|
+
/** @internal Connects; resolves on the room's welcome. */
|
|
385
|
+
open(): Promise<Room>;
|
|
386
|
+
/** This player. The id is stable across reconnects within the 60 s resume window. */
|
|
387
|
+
get me(): Player;
|
|
388
|
+
/** The shared state. Read it freely; change it only with set(), merge() and delete(). */
|
|
389
|
+
get state(): JsonObject;
|
|
390
|
+
/** Everyone connected to the room, this player included. */
|
|
391
|
+
get players(): Player[];
|
|
392
|
+
/** The room's rules, set by whoever joined first. */
|
|
393
|
+
get config(): RoomConfig;
|
|
394
|
+
get status(): RoomStatus;
|
|
395
|
+
/** `turns` rooms: id of the player whose turn it is, or null. */
|
|
396
|
+
get turn(): string | null;
|
|
397
|
+
/** `turns` rooms: true when this player may move now. */
|
|
398
|
+
get isMyTurn(): boolean;
|
|
399
|
+
/** `turns` rooms: epoch milliseconds when the current turn times out, or null without a turn timer. */
|
|
400
|
+
get deadline(): number | null;
|
|
401
|
+
/** `turns` rooms: every move so far, oldest first. Derive the game from these. */
|
|
402
|
+
get moves(): readonly Move[];
|
|
403
|
+
/** `realtime` rooms: each player's latest input, by player id, as of the last snapshot. */
|
|
404
|
+
get inputs(): Record<string, JsonValue>;
|
|
405
|
+
/** `realtime` rooms: the last snapshot's tick number. Grows by tickHz every second. */
|
|
406
|
+
/** `script` rooms: this player's private state, which only this player receives (a hand of cards, a secret goal). */
|
|
407
|
+
get private(): JsonObject;
|
|
408
|
+
get tick(): number;
|
|
409
|
+
on<E extends keyof RoomEvents>(event: E, listener: (...args: RoomEvents[E]) => void): () => void;
|
|
410
|
+
/** Puts `value` at `path`. In a dotted path, `me` means this player: `room.set("players.me.x", 120)`. */
|
|
411
|
+
set(path: PathInput, value: unknown): void;
|
|
412
|
+
/** Copies the keys of `value` into the object at `path`, leaving its other keys alone. "" merges into the root. */
|
|
413
|
+
merge(path: PathInput, value: Record<string, unknown>): void;
|
|
414
|
+
/** Removes whatever is at `path`. */
|
|
415
|
+
delete(path: PathInput): void;
|
|
416
|
+
/** Sends `data` to everyone else in the room, or to one player. Not saved in the state. */
|
|
417
|
+
send(data: unknown, to?: string | Player): void;
|
|
418
|
+
/**
|
|
419
|
+
* `turns` rooms: plays a move on this player's turn. The room records it in
|
|
420
|
+
* room.moves and passes the turn. Throws if it isn't this player's turn or
|
|
421
|
+
* the move doesn't match the room's moveSchema.
|
|
422
|
+
*/
|
|
423
|
+
move(data: unknown): void;
|
|
424
|
+
/**
|
|
425
|
+
* `script` rooms: sends what this player did to the room's script (its
|
|
426
|
+
* onAction). Resolves once the script accepts it; rejects with the script's
|
|
427
|
+
* own reason (code `action_rejected`) if it turns it down.
|
|
428
|
+
*/
|
|
429
|
+
act(data: unknown): Promise<void>;
|
|
430
|
+
/** `realtime` and `script` rooms: sets this player's latest input. Unsent inputs are replaced, not queued. */
|
|
431
|
+
input(data: unknown): void;
|
|
432
|
+
private ensureType;
|
|
433
|
+
/** Leaves the room for good and frees the seat at once. */
|
|
434
|
+
leave(): void;
|
|
435
|
+
private ensureOpen;
|
|
436
|
+
private write;
|
|
437
|
+
private enqueue;
|
|
438
|
+
private backlogError;
|
|
439
|
+
/** Sends one queued message if connected. Returns false to keep it queued. */
|
|
440
|
+
private transmit;
|
|
441
|
+
private connect;
|
|
442
|
+
/** Gives up on a socket that has gone quiet, without waiting for TCP to notice. */
|
|
443
|
+
private abandon;
|
|
444
|
+
private dropped;
|
|
445
|
+
/** Closes for good: rejects a pending join, or reports the error. */
|
|
446
|
+
private fail;
|
|
447
|
+
private shutDown;
|
|
448
|
+
private stopTimers;
|
|
449
|
+
private startHeartbeat;
|
|
450
|
+
private setStatus;
|
|
451
|
+
private report;
|
|
452
|
+
private receive;
|
|
453
|
+
private playerFor;
|
|
454
|
+
private moved;
|
|
455
|
+
private welcome;
|
|
456
|
+
private patched;
|
|
457
|
+
private settleActs;
|
|
458
|
+
private errored;
|
|
459
|
+
/** view = confirmed + every write the room hasn't confirmed yet, in order. */
|
|
460
|
+
private rebuild;
|
|
461
|
+
}
|
|
462
|
+
|
|
463
|
+
/**
|
|
464
|
+
* cotchu: multiplayer rooms for games. No runtime dependencies.
|
|
465
|
+
*
|
|
466
|
+
* import { cotchu } from "cotchu";
|
|
467
|
+
* const room = await cotchu.join("main-lobby", { key: "pk_live_…" });
|
|
468
|
+
* room.on("state", (state) => draw(state));
|
|
469
|
+
* room.set("players.me", { x: 10, y: 20 });
|
|
470
|
+
*/
|
|
471
|
+
|
|
472
|
+
/** Matches package.json; sent to rooms in hello. */
|
|
473
|
+
declare const SDK_VERSION = "0.1.0";
|
|
474
|
+
interface JoinOptions {
|
|
475
|
+
/** Your project's publishable key, `pk_live_<project>_<secret>`. Safe to ship in game code. */
|
|
476
|
+
key: string;
|
|
477
|
+
/** Rooms server address. Default: Cotchu's hosted rooms. Pass `ws://localhost:8790` to use a local dev server. */
|
|
478
|
+
url?: string;
|
|
479
|
+
/** This player's display name, up to 32 characters. */
|
|
480
|
+
name?: string;
|
|
481
|
+
/** Where to create the room if it doesn't exist yet. `auto` (default) places it near the first player. */
|
|
482
|
+
region?: RegionOption;
|
|
483
|
+
/** Room rules, used only by the player who creates the room. Later joiners get the room's rules. */
|
|
484
|
+
type?: RoomType;
|
|
485
|
+
/**
|
|
486
|
+
* Run this project's deployed room script (`npx cotchu deploy room.js --name <name>`).
|
|
487
|
+
* Makes the room a `script` room: the script owns the state, and players send actions with room.act().
|
|
488
|
+
*/
|
|
489
|
+
script?: string;
|
|
490
|
+
seats?: number;
|
|
491
|
+
/** Paths players may write, such as `["players.$self"]`. Default: every path. */
|
|
492
|
+
writable?: string[];
|
|
493
|
+
/** `turns` rooms: milliseconds per turn before it passes to the next player. Default: no timer. */
|
|
494
|
+
turnMs?: number;
|
|
495
|
+
/** `turns` rooms: the shape every move must have, as a JSON Schema subset. */
|
|
496
|
+
moveSchema?: MoveSchema;
|
|
497
|
+
/** `realtime` rooms: snapshots per second; `script` rooms: onTick calls per second. 1 to 30. */
|
|
498
|
+
tickHz?: number;
|
|
499
|
+
/** A WebSocket class, for runtimes without a global one (Node before 22). */
|
|
500
|
+
WebSocket?: typeof WebSocket;
|
|
501
|
+
/**
|
|
502
|
+
* Browsers: give the seat back after a reload or a reopened tab, within the
|
|
503
|
+
* 60 s resume window. Default true. Each tab keeps its own seat.
|
|
504
|
+
*/
|
|
505
|
+
rememberSeat?: boolean;
|
|
506
|
+
}
|
|
507
|
+
/**
|
|
508
|
+
* Joins `room`, creating it if nobody is in it yet. Resolves once the room has
|
|
509
|
+
* welcomed this player, with its current state and players. Rejects with a
|
|
510
|
+
* CotchuError whose message says what to fix.
|
|
511
|
+
*/
|
|
512
|
+
declare function join(room: string, options: JoinOptions): Promise<Room>;
|
|
513
|
+
declare const cotchu: {
|
|
514
|
+
join: typeof join;
|
|
515
|
+
version: string;
|
|
516
|
+
};
|
|
517
|
+
|
|
518
|
+
export { CotchuError, Room, SDK_VERSION, cotchu, join };
|
|
519
|
+
export type { ErrorCode, JoinOptions, JsonObject, JsonValue, Move, MoveSchema, PatchOp, PathInput, Player, Region, RegionOption, RoomConfig, RoomEvents, RoomStatus, RoomType, StateChange };
|