@v12-engine/engine 0.1.1 → 0.4.0

package/dist/session/share.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"share.js","names":[],"sources":["../../src/session/share.ts"],"sourcesContent":["import type { PlayerId } from '#engine/entity'\nimport type { World } from '#engine/world'\nimport { SessionHost, type Transport } from './remote'\nimport { openSocket } from './socket'\n\n/*\n * A game played in the page, watched from others: through a relay (the server's `WatchRelay`), as a page cannot take\n * connections. The page shares its world under a key; the relay tells it of each watcher, and the page's own host\n * seats them at the world as observers, the way a server seats those who watch its games. The world is stepped by the\n * page's game as it always is: the host only sends (`SessionHost.publish`)\n */\n\n/**\n * What a page says to the relay, before it watches; and what a sharing page says all along\n *\n * @internal\n */\nexport type RelayRequest =\n\t/** The page plays a game under `key`, and lets others watch it */\n\t| { type: 'share'; key: string; name: string }\n\t/** The sharing page's game, for one watcher */\n\t| { type: 'send'; to: number; text: string }\n\t/** Watches what is shared under `key`, now or once it is */\n\t| { type: 'watch'; key: string }\n\n/**\n * What the relay tells pages besides the game itself\n *\n * @beta\n */\nexport type RelayNotice =\n\t/** To a sharing page: it shares under `key` now */\n\t| { type: 'shared'; key: string }\n\t/** To a sharing page: another page shares under that key already */\n\t| { type: 'taken'; key: string }\n\t/** To a sharing page: someone watches, by the id the relay gave them */\n\t| { type: 'watcher'; id: number }\n\t/** To a sharing page: what a watcher said (that it got a tick, a ping) */\n\t| { type: 'from'; watcher: number; text: string }\n\t/** To a sharing page: a watcher left */\n\t| { type: 'gone'; watcher: number }\n\t/** To a watcher: nothing is shared under the key right now. The game comes once it is */\n\t| { type: 'waiting'; key: string }\n\t/** To a watcher: the game shared ended. The next one under the key comes when it is shared */\n\t| { type: 'ended'; key: string }\n\n/**\n * What `shareGame` is given: the relay's address, the key and name of the share and whose side watchers see\n *\n * @beta\n */\nexport interface ShareOptions {\n\t/** The relay's address, `ws://host:port` */\n\turl: string\n\t/** What watchers ask for: the same for every game of a campaign, so they stay from one mission to the next */\n\tkey: string\n\t/** What it is, for the relay's log */\n\tname: string\n\t/** Whose side watchers see it from: they get that player's lines and cinematics, and see everything besides */\n\tplayer: PlayerId\n\t/** Snapshots a second to each watcher. 20 when left out */\n\tsendRate?: number\n}\n\n/**\n * A game shared for watching (`shareGame`)\n *\n * @beta\n */\nexport interface SharedGame {\n\t/** `shared` once the relay has it; `taken` when another page shares under the key; `closed` once it is over */\n\treadonly state: 'shared' | 'taken' | 'closed'\n\t/** How many watch it now */\n\treadonly watchers: number\n\t/** Told whenever the state or the number of watchers changes */\n\tonChange(handler: () => void): void\n\t/** Stops sharing: the watchers are told it ended */\n\tclose(): void\n}\n\n/** How often the host looks whether the world went on, a second: it sends at its own rate */\nconst LOOKS = 30\n\n/**\n * Shares the page's world through a relay, for others to watch. Fails when the relay cannot be reached\n *\n * @beta\n */\nexport async function shareGame(world: World, options: ShareOptions): Promise<SharedGame> {\n\tconst relay = await openSocket(options.url)\n\tconst host = new SessionHost(world, { sendRate: options.sendRate })\n\t/** Each watcher's end of the connection, as the host holds it: what the relay brings from them goes to it */\n\tconst ends = new Map<number, { message: (text: string) => void; closed: () => void }>()\n\tlet state: SharedGame['state'] = 'shared'\n\tlet changed: () => void = () => {}\n\tconst ask = (request: RelayRequest) => relay.send(JSON.stringify(request))\n\n\tconst seat = (id: number) => {\n\t\tconst end = { message: (_text: string) => {}, closed: () => {} }\n\t\tends.set(id, end)\n\t\tconst transport: Transport = {\n\t\t\tsend: (text) => ask({ type: 'send', to: id, text }),\n\t\t\tonMessage: (handler) => (end.message = handler),\n\t\t\tonClose: (handler) => (end.closed = handler),\n\t\t\t// a watcher leaves by closing their own connection: the relay says so\n\t\t\tclose: () => {}\n\t\t}\n\t\thost.connect(options.player, transport, { readOnly: true, observer: true })\n\t}\n\n\tlet last = performance.now()\n\tconst timer = setInterval(() => {\n\t\tconst now = performance.now()\n\t\thost.publish((now - last) / 1000)\n\t\tlast = now\n\t}, 1000 / LOOKS)\n\n\t/** Over once: closed, or never shared as the key was taken */\n\tconst stop = (next: 'closed' | 'taken' = 'closed') => {\n\t\tif (state !== 'shared') return\n\t\tclearInterval(timer)\n\t\thost.dispose()\n\t\tends.clear()\n\t\tstate = next\n\t\tchanged()\n\t}\n\n\trelay.onMessage((text) => {\n\t\tconst notice = JSON.parse(text) as RelayNotice\n\t\tif (notice.type === 'taken') {\n\t\t\tstop('taken')\n\t\t\trelay.close()\n\t\t} else if (notice.type === 'watcher') {\n\t\t\tseat(notice.id)\n\t\t\tchanged()\n\t\t} else if (notice.type === 'from') ends.get(notice.watcher)?.message(notice.text)\n\t\telse if (notice.type === 'gone') {\n\t\t\tends.get(notice.watcher)?.closed()\n\t\t\tends.delete(notice.watcher)\n\t\t\tchanged()\n\t\t}\n\t})\n\trelay.onClose(() => stop())\n\task({ type: 'share', key: options.key, name: options.name })\n\n\treturn {\n\t\tget state() {\n\t\t\treturn state\n\t\t},\n\t\tget watchers() {\n\t\t\treturn ends.size\n\t\t},\n\t\tonChange(handler) {\n\t\t\tchanged = handler\n\t\t},\n\t\tclose() {\n\t\t\tstop()\n\t\t\trelay.close()\n\t\t}\n\t}\n}\n"],"mappings":";;;;AAiFA,IAAM,QAAQ;;;;;;AAOd,eAAsB,UAAU,OAAc,SAA4C;CACzF,MAAM,QAAQ,MAAM,WAAW,QAAQ,GAAG;CAC1C,MAAM,OAAO,IAAI,YAAY,OAAO,EAAE,UAAU,QAAQ,SAAS,CAAC;;CAElE,MAAM,uBAAO,IAAI,IAAqE;CACtF,IAAI,QAA6B;CACjC,IAAI,gBAA4B,CAAC;CACjC,MAAM,OAAO,YAA0B,MAAM,KAAK,KAAK,UAAU,OAAO,CAAC;CAEzE,MAAM,QAAQ,OAAe;EAC5B,MAAM,MAAM;GAAE,UAAU,UAAkB,CAAC;GAAG,cAAc,CAAC;EAAE;EAC/D,KAAK,IAAI,IAAI,GAAG;EAQhB,KAAK,QAAQ,QAAQ,QAAQ;GAN5B,OAAO,SAAS,IAAI;IAAE,MAAM;IAAQ,IAAI;IAAI;GAAK,CAAC;GAClD,YAAY,YAAa,IAAI,UAAU;GACvC,UAAU,YAAa,IAAI,SAAS;GAEpC,aAAa,CAAC;EAEc,GAAW;GAAE,UAAU;GAAM,UAAU;EAAK,CAAC;CAC3E;CAEA,IAAI,OAAO,YAAY,IAAI;CAC3B,MAAM,QAAQ,kBAAkB;EAC/B,MAAM,MAAM,YAAY,IAAI;EAC5B,KAAK,SAAS,MAAM,QAAQ,GAAI;EAChC,OAAO;CACR,GAAG,MAAO,KAAK;;CAGf,MAAM,QAAQ,OAA2B,aAAa;EACrD,IAAI,UAAU,UAAU;EACxB,cAAc,KAAK;EACnB,KAAK,QAAQ;EACb,KAAK,MAAM;EACX,QAAQ;EACR,QAAQ;CACT;CAEA,MAAM,WAAW,SAAS;EACzB,MAAM,SAAS,KAAK,MAAM,IAAI;EAC9B,IAAI,OAAO,SAAS,SAAS;GAC5B,KAAK,OAAO;GACZ,MAAM,MAAM;EACb,OAAO,IAAI,OAAO,SAAS,WAAW;GACrC,KAAK,OAAO,EAAE;GACd,QAAQ;EACT,OAAO,IAAI,OAAO,SAAS,QAAQ,KAAK,IAAI,OAAO,OAAO,CAAC,EAAE,QAAQ,OAAO,IAAI;OAC3E,IAAI,OAAO,SAAS,QAAQ;GAChC,KAAK,IAAI,OAAO,OAAO,CAAC,EAAE,OAAO;GACjC,KAAK,OAAO,OAAO,OAAO;GAC1B,QAAQ;EACT;CACD,CAAC;CACD,MAAM,cAAc,KAAK,CAAC;CAC1B,IAAI;EAAE,MAAM;EAAS,KAAK,QAAQ;EAAK,MAAM,QAAQ;CAAK,CAAC;CAE3D,OAAO;EACN,IAAI,QAAQ;GACX,OAAO;EACR;EACA,IAAI,WAAW;GACd,OAAO,KAAK;EACb;EACA,SAAS,SAAS;GACjB,UAAU;EACX;EACA,QAAQ;GACP,KAAK;GACL,MAAM,MAAM;EACb;CACD;AACD"}

package/dist/session/socket.d.ts

@@ -3,6 +3,6 @@ import type { Transport } from './remote';
  * The player's end of a connection to a server, over a WebSocket: what `connect` and a server's lobby talk through.
  * Resolves once the connection is open; fails when it cannot be made
  *
- * @beta
+ * @public
  */
 export declare function openSocket(url: string): Promise<Transport>;

package/dist/session/socket.js

@@ -0,0 +1,29 @@
+//#region src/session/socket.ts
+/**
+* The player's end of a connection to a server, over a WebSocket: what `connect` and a server's lobby talk through.
+* Resolves once the connection is open; fails when it cannot be made
+*
+* @public
+*/
+function openSocket(url) {
+	return new Promise((resolve, reject) => {
+		const socket = new WebSocket(url);
+		let handler = () => {};
+		let closed = () => {};
+		socket.onmessage = (event) => handler(String(event.data));
+		socket.onclose = () => closed();
+		socket.onerror = () => reject(/* @__PURE__ */ new Error(`Could not connect to ${url}`));
+		socket.onopen = () => resolve({
+			send: (message) => {
+				if (socket.readyState === WebSocket.OPEN) socket.send(message);
+			},
+			onMessage: (next) => handler = next,
+			onClose: (next) => closed = next,
+			close: () => socket.close()
+		});
+	});
+}
+//#endregion
+export { openSocket };
+
+//# sourceMappingURL=socket.js.map

package/dist/session/socket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.js","names":[],"sources":["../../src/session/socket.ts"],"sourcesContent":["import type { Transport } from './remote'\n\n/**\n * The player's end of a connection to a server, over a WebSocket: what `connect` and a server's lobby talk through.\n * Resolves once the connection is open; fails when it cannot be made\n *\n * @public\n */\nexport function openSocket(url: string): Promise<Transport> {\n\treturn new Promise((resolve, reject) => {\n\t\tconst socket = new WebSocket(url)\n\t\tlet handler: (message: string) => void = () => {}\n\t\tlet closed: () => void = () => {}\n\t\tsocket.onmessage = (event) => handler(String(event.data))\n\t\tsocket.onclose = () => closed()\n\t\tsocket.onerror = () => reject(new Error(`Could not connect to ${url}`))\n\t\tsocket.onopen = () =>\n\t\t\tresolve({\n\t\t\t\tsend: (message) => {\n\t\t\t\t\tif (socket.readyState === WebSocket.OPEN) socket.send(message)\n\t\t\t\t},\n\t\t\t\tonMessage: (next) => (handler = next),\n\t\t\t\tonClose: (next) => (closed = next),\n\t\t\t\tclose: () => socket.close()\n\t\t\t})\n\t})\n}\n"],"mappings":";;;;;;;AAQA,SAAgB,WAAW,KAAiC;CAC3D,OAAO,IAAI,SAAS,SAAS,WAAW;EACvC,MAAM,SAAS,IAAI,UAAU,GAAG;EAChC,IAAI,gBAA2C,CAAC;EAChD,IAAI,eAA2B,CAAC;EAChC,OAAO,aAAa,UAAU,QAAQ,OAAO,MAAM,IAAI,CAAC;EACxD,OAAO,gBAAgB,OAAO;EAC9B,OAAO,gBAAgB,uBAAO,IAAI,MAAM,wBAAwB,KAAK,CAAC;EACtE,OAAO,eACN,QAAQ;GACP,OAAO,YAAY;IAClB,IAAI,OAAO,eAAe,UAAU,MAAM,OAAO,KAAK,OAAO;GAC9D;GACA,YAAY,SAAU,UAAU;GAChC,UAAU,SAAU,SAAS;GAC7B,aAAa,OAAO,MAAM;EAC3B,CAAC;CACH,CAAC;AACF"}

package/dist/session/wire.d.ts

@@ -81,13 +81,18 @@ export type GameHostMessage = {
  * @beta
  */
 export interface DebugAsk {
+    /** The entity or object to inspect, or null to stop inspecting */
     inspect?: InspectTarget | null;
+    /** A value to change in the inspected object: the path to it and the new number or boolean */
     set?: {
         path: (string | number)[];
         value: number | boolean;
     };
+    /** Whether to send the list of inspectable things */
     listing?: boolean;
+    /** Whether to send the world's log lines */
     logging?: boolean;
+    /** Asks the world to clear its kept log lines */
     clearLog?: true;
 }
 /**

package/dist/session/wire.js

@@ -0,0 +1,84 @@
+//#region src/session/wire.ts
+/** The game's own messages to a player: the rest are a server's or a relay's (`ServerToPlayer`) */
+var GAME_TYPES = /* @__PURE__ */ new Set([
+	"welcome",
+	"pong",
+	"ground",
+	"failed",
+	"delta",
+	"debug"
+]);
+/**
+* Whether a message to a player is a server's or a relay's, not the game's
+*
+* @internal
+*/
+var isServerMessage = (message) => !GAME_TYPES.has(message.type);
+/** Every type a player is sent, each said once: what is not one of them is not read */
+var HOST_TYPES = {
+	welcome: true,
+	pong: true,
+	ground: true,
+	failed: true,
+	delta: true,
+	debug: true,
+	lobby: true,
+	seated: true,
+	watching: true,
+	full: true,
+	refused: true,
+	lobbyChat: true,
+	paused: true,
+	result: true,
+	waiting: true,
+	ended: true
+};
+/** Every type a host or a server is sent */
+var PLAYER_TYPES = {
+	command: true,
+	ack: true,
+	ping: true,
+	ground: true,
+	debug: true,
+	join: true,
+	start: true,
+	sit: true,
+	ready: true,
+	name: true,
+	resume: true,
+	setting: true,
+	seatSetting: true,
+	admin: true,
+	lobbyChat: true,
+	kick: true,
+	watch: true
+};
+/** A message as text, an object of a known type, or nothing: not JSON, not an object, a type that is not one of `types` */
+function read(text, types) {
+	let message;
+	try {
+		message = JSON.parse(text);
+	} catch {
+		return;
+	}
+	if (typeof message !== "object" || message === null || Array.isArray(message)) return void 0;
+	const { type } = message;
+	return typeof type === "string" && Object.hasOwn(types, type) ? message : void 0;
+}
+/**
+* What a host or a server sent, as text: one of its messages, or nothing for what is not (not JSON, not an object of a
+* type a player is sent). Its fields are its receiver's to check
+*
+* @internal
+*/
+var readHostMessage = (text) => read(text, HOST_TYPES);
+/**
+* What a player sent, as text: one of its messages, or nothing for what is not
+*
+* @internal
+*/
+var readPlayerMessage = (text) => read(text, PLAYER_TYPES);
+//#endregion
+export { isServerMessage, readHostMessage, readPlayerMessage };
+
+//# sourceMappingURL=wire.js.map

package/dist/session/wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.js","names":[],"sources":["../../src/session/wire.ts"],"sourcesContent":["/**\n * What goes over the wire between a host and a player, both layers of it in one place (design review E11): the game's\n * (`GameHostMessage`, `GameCommandMessage`: a `SessionHost` and a `RemoteSession`) and a server's lobby beside it\n * (`LobbyServerMessage`, `LobbyPlayerMessage`: a `GameServer`). One union each way (`HostToPlayer`, `PlayerToHost`),\n * discriminated by `type` (no type is both a game's and a lobby's), read with a shape check (`readHostMessage`,\n * `readPlayerMessage`), and `PROTOCOL_VERSION` is of all of it\n */\nimport type { GameData } from '#engine/gameData'\nimport type { Inspection, InspectTarget, LoggedEvent, WorldListing } from '#engine/inspect'\nimport type { PlayerId } from '#engine/entity'\nimport type { GameResult, ServerHooks, ServerSeat } from '#engine/game'\nimport type { SavedGround } from '#engine/ground'\nimport type { MapCamera, MapDoodad, MapEnvironment, MapPath, MapRegion } from '#engine/map'\nimport type { Delta } from './delta'\nimport type { PlayerCommand } from './protocol'\nimport type { RelayNotice, RelayRequest } from './share'\n\n/**\n * What the host sends a player\n *\n * @beta\n */\nexport type GameHostMessage =\n\t| {\n\t\t\ttype: 'welcome'\n\t\t\t/** The version of the wire the host speaks (`PROTOCOL_VERSION`): a player of another refuses the game */\n\t\t\tprotocol: number\n\t\t\tplayer: PlayerId\n\t\t\ttickRate: number\n\t\t\t/** The game module the world runs, by id, and the version of its data (`Registry.dataHash`): the player's has to be the same */\n\t\t\tgame: string\n\t\t\thash: string\n\t\t\t/**\n\t\t\t * The ground: all of it, or the map of the game it started as and what changed of it since (S36). A player\n\t\t\t * without that map asks for it (`ground`), and is sent it in parts\n\t\t\t */\n\t\t\tterrain: SavedGround\n\t\t\t/** What the map looks like beyond its ground, for the screen */\n\t\t\tenvironment?: MapEnvironment\n\t\t\t/** Its scenery, for the screen */\n\t\t\tdoodads?: MapDoodad[]\n\t\t\t/** Its regions, for the screen: what mist in places lies over by name */\n\t\t\tregions?: MapRegion[]\n\t\t\t/** Its views saved under names */\n\t\t\tcameras?: MapCamera[]\n\t\t\t/** Its paths, for a cinematic's camera on a rail */\n\t\t\tpaths?: MapPath[]\n\t\t\t/** What its definitions were changed to while it ran (`world.redefine`), copies and all: put in the player's registry */\n\t\t\tredefinitions?: GameData\n\t\t\t/** Everything the player knows, as a delta without a base */\n\t\t\tfirst: Delta\n\t\t\t/** The player only watches, and sees everything */\n\t\t\tobserver?: boolean\n\t\t\t/** The player may use the debug tools (`world.debugPlayers`): the host follows the world for them (`debug`) */\n\t\t\tdebug?: true\n\t  }\n\t| { type: 'pong'; at: number }\n\t/** A part of the ground a world started as, for a player who does not have its map: `text` of `parts`, joined, is a `TerrainSave` */\n\t| { type: 'ground'; part: number; parts: number; text: string }\n\t/** The game ended on an error in its rules (`World.failure`): what the players are told of it */\n\t| { type: 'failed'; message: string }\n\t| ({ type: 'delta' } & Delta)\n\t/** The debug tools' view of the world (`SessionDebug`), for a player who may use them and follows something: every tenth of a second */\n\t| { type: 'debug'; inspection: Inspection | null; world: WorldListing | null; log: readonly LoggedEvent[] }\n\n/**\n * What a player sends the host: commands, and which ticks it has got (what the next deltas are made against)\n *\n * @internal\n */\nexport type GameCommandMessage =\n\t| { type: 'command'; seq: number; command: PlayerCommand }\n\t| { type: 'ack'; tick: number; events?: number }\n\t/** To measure the time there and back: answered at once with a `pong` of the same `at` */\n\t| { type: 'ping'; at: number }\n\t/** A part of the ground the world started as, for a player who does not have its map (`ground` answers it) */\n\t| { type: 'ground'; part: number }\n\t/** What the debug tools follow, change and list (`SessionDebug`), from a player who may use them: `debug` answers it */\n\t| ({ type: 'debug' } & DebugAsk)\n\n/**\n * What the debug tools of a screen ask of a world elsewhere (`SessionDebug`), as said over the wire or to a worker\n *\n * @beta\n */\nexport interface DebugAsk {\n\t/** The entity or object to inspect, or null to stop inspecting */\n\tinspect?: InspectTarget | null\n\t/** A value to change in the inspected object: the path to it and the new number or boolean */\n\tset?: { path: (string | number)[]; value: number | boolean }\n\t/** Whether to send the list of inspectable things */\n\tlisting?: boolean\n\t/** Whether to send the world's log lines */\n\tlogging?: boolean\n\t/** Asks the world to clear its kept log lines */\n\tclearLog?: true\n}\n\n/**\n * What a player says to the server, besides what goes to the game\n *\n * @internal\n */\nexport type LobbyPlayerMessage =\n\t| {\n\t\t\ttype: 'join'\n\t\t\tname?: string\n\t\t\ttoken?: string\n\t\t\tticket?: string\n\t\t\twatch?: boolean\n\t\t\tkey?: string\n\t\t\tback?: boolean\n\t\t\twho?: string\n\t\t\t/**\n\t\t\t * The version of the wire the player speaks (`PROTOCOL_VERSION`): one of another is refused with why. Left\n\t\t\t * out, the player's own check of the welcome is what tells them\n\t\t\t */\n\t\t\tprotocol?: number\n\t  }\n\t| { type: 'start' }\n\t/** In the lobby: another seat, free, for who is seated */\n\t| { type: 'sit'; player: PlayerId }\n\t/** In the lobby: ready, or not. Once every player seated is, the game starts */\n\t| { type: 'ready'; ready: boolean }\n\t/** In the lobby: the name one is shown by */\n\t| { type: 'name'; name: string }\n\t/** In a game a player paused (`pause` command): it goes on, for everyone */\n\t| { type: 'resume' }\n\t| { type: 'setting'; name: string; value: string }\n\t/** In the lobby: a setting of a seat (`ServerHooks.seatSettings`): one's own, or one no other player holds */\n\t| { type: 'seatSetting'; player: PlayerId; name: string; value: string }\n\t| { type: 'admin'; key: string; action: 'pause' | 'resume' | 'stop' }\n\t/** In the lobby: a line said to everyone there, before the game */\n\t| { type: 'lobbyChat'; text: string }\n\t/** In the lobby: a vote to let another seated player go. Once most of the others vote so, they are let go */\n\t| { type: 'kick'; player: PlayerId }\n\n/**\n * What the server tells everyone connected, as it changes\n *\n * @beta\n */\nexport type LobbyServerMessage =\n\t| {\n\t\t\ttype: 'lobby'\n\t\t\tmode: string\n\t\t\tgame: string\n\t\t\tphase: 'lobby' | 'game' | 'ended'\n\t\t\tseats: ServerSeat[]\n\t\t\tsettings: Record<string, string>\n\t\t\t/** What the game offers to set (`ServerHooks.settings`) */\n\t\t\toffered: NonNullable<ServerHooks['settings']>\n\t\t\t/** What the game offers to set for each seat (`ServerHooks.seatSettings`, and a race: `seatSettingsOf`) */\n\t\t\tseatOffered: NonNullable<ServerHooks['seatSettings']>\n\t  }\n\t| { type: 'seated'; player: PlayerId; token: string }\n\t/** A line said in the lobby (`lobbyChat`): by whom, their seat where they have one */\n\t| { type: 'lobbyChat'; player?: PlayerId; name: string; text: string }\n\t| { type: 'watching'; player: PlayerId }\n\t| { type: 'full' }\n\t| { type: 'refused'; reason: string }\n\t/** The game paused, or going on: by a player (`player`, for `seconds` at most) or by an admin (no player) */\n\t| { type: 'paused'; paused: boolean; player?: PlayerId; seconds?: number }\n\t| { type: 'result'; result: GameResult }\n\n/**\n * What a player is told besides the game: a server's lobby, a pause, the result, or, watching through a relay, that\n * nothing is shared yet or that the game watched ended\n *\n * @beta\n */\nexport type ServerToPlayer = LobbyServerMessage | Extract<RelayNotice, { type: 'waiting' | 'ended' }>\n\n/**\n * Everything a host, a server or a relay sends a player\n *\n * @beta\n */\nexport type HostToPlayer = GameHostMessage | ServerToPlayer\n\n/**\n * Everything a player sends a host or a server, or a relay to watch through\n *\n * @internal\n */\nexport type PlayerToHost = GameCommandMessage | LobbyPlayerMessage | Extract<RelayRequest, { type: 'watch' }>\n\n/** The game's own messages to a player: the rest are a server's or a relay's (`ServerToPlayer`) */\nconst GAME_TYPES = new Set<string>(['welcome', 'pong', 'ground', 'failed', 'delta', 'debug'] satisfies GameHostMessage['type'][])\n\n/**\n * Whether a message to a player is a server's or a relay's, not the game's\n *\n * @internal\n */\nexport const isServerMessage = (message: HostToPlayer): message is ServerToPlayer => !GAME_TYPES.has(message.type)\n\n/** Every type a player is sent, each said once: what is not one of them is not read */\nconst HOST_TYPES: Record<HostToPlayer['type'], true> = {\n\twelcome: true,\n\tpong: true,\n\tground: true,\n\tfailed: true,\n\tdelta: true,\n\tdebug: true,\n\tlobby: true,\n\tseated: true,\n\twatching: true,\n\tfull: true,\n\trefused: true,\n\tlobbyChat: true,\n\tpaused: true,\n\tresult: true,\n\twaiting: true,\n\tended: true\n}\n\n/** Every type a host or a server is sent */\nconst PLAYER_TYPES: Record<PlayerToHost['type'], true> = {\n\tcommand: true,\n\tack: true,\n\tping: true,\n\tground: true,\n\tdebug: true,\n\tjoin: true,\n\tstart: true,\n\tsit: true,\n\tready: true,\n\tname: true,\n\tresume: true,\n\tsetting: true,\n\tseatSetting: true,\n\tadmin: true,\n\tlobbyChat: true,\n\tkick: true,\n\twatch: true\n}\n\n/** A message as text, an object of a known type, or nothing: not JSON, not an object, a type that is not one of `types` */\nfunction read<M extends { type: string }>(text: string, types: Record<string, true>): M | undefined {\n\tlet message: unknown\n\ttry {\n\t\tmessage = JSON.parse(text)\n\t} catch {\n\t\treturn undefined\n\t}\n\tif (typeof message !== 'object' || message === null || Array.isArray(message)) return undefined\n\tconst { type } = message as { type?: unknown }\n\treturn typeof type === 'string' && Object.hasOwn(types, type) ? (message as M) : undefined\n}\n\n/**\n * What a host or a server sent, as text: one of its messages, or nothing for what is not (not JSON, not an object of a\n * type a player is sent). Its fields are its receiver's to check\n *\n * @internal\n */\nexport const readHostMessage = (text: string): HostToPlayer | undefined => read(text, HOST_TYPES)\n\n/**\n * What a player sent, as text: one of its messages, or nothing for what is not\n *\n * @internal\n */\nexport const readPlayerMessage = (text: string): PlayerToHost | undefined => read(text, PLAYER_TYPES)\n"],"mappings":";;AA4LA,IAAM,6BAAa,IAAI,IAAY;CAAC;CAAW;CAAQ;CAAU;CAAU;CAAS;AAAO,CAAqC;;;;;;AAOhI,IAAa,mBAAmB,YAAqD,CAAC,WAAW,IAAI,QAAQ,IAAI;;AAGjH,IAAM,aAAiD;CACtD,SAAS;CACT,MAAM;CACN,QAAQ;CACR,QAAQ;CACR,OAAO;CACP,OAAO;CACP,OAAO;CACP,QAAQ;CACR,UAAU;CACV,MAAM;CACN,SAAS;CACT,WAAW;CACX,QAAQ;CACR,QAAQ;CACR,SAAS;CACT,OAAO;AACR;;AAGA,IAAM,eAAmD;CACxD,SAAS;CACT,KAAK;CACL,MAAM;CACN,QAAQ;CACR,OAAO;CACP,MAAM;CACN,OAAO;CACP,KAAK;CACL,OAAO;CACP,MAAM;CACN,QAAQ;CACR,SAAS;CACT,aAAa;CACb,OAAO;CACP,WAAW;CACX,MAAM;CACN,OAAO;AACR;;AAGA,SAAS,KAAiC,MAAc,OAA4C;CACnG,IAAI;CACJ,IAAI;EACH,UAAU,KAAK,MAAM,IAAI;CAC1B,QAAQ;EACP;CACD;CACA,IAAI,OAAO,YAAY,YAAY,YAAY,QAAQ,MAAM,QAAQ,OAAO,GAAG,OAAO,KAAA;CACtF,MAAM,EAAE,SAAS;CACjB,OAAO,OAAO,SAAS,YAAY,OAAO,OAAO,OAAO,IAAI,IAAK,UAAgB,KAAA;AAClF;;;;;;;AAQA,IAAa,mBAAmB,SAA2C,KAAK,MAAM,UAAU;;;;;;AAOhG,IAAa,qBAAqB,SAA2C,KAAK,MAAM,YAAY"}

package/dist/session/worker.d.ts

@@ -1,5 +1,5 @@
 import type { PlayerId } from '#engine/entity';
-import { type GameModule } from '#engine/game';
+import { type Rules } from '#engine/game';
 import { type LogEntry, Logger } from '#engine/log';
 import type { GameMap } from '#engine/map';
 import type { Message } from '#engine/messages';
@@ -15,16 +15,21 @@ import { type ConnectOptions, RemoteSession } from './remote';
  * @beta
  */
 export interface WorldWorkerLike {
+    /** Sends a message to the worker, with objects to transfer rather than copy */
     postMessage(message: unknown, transfer?: unknown[]): void;
+    /** Listens for the worker's messages or errors, where the worker is a page's `Worker` */
     addEventListener?(type: 'message' | 'error', listener: (event: {
         data?: unknown;
         message?: string;
     }) => void): void;
+    /** Stops a listener added with `addEventListener` */
     removeEventListener?(type: 'message' | 'error', listener: (event: {
         data?: unknown;
         message?: string;
     }) => void): void;
+    /** Listens for the worker's messages or errors, where the worker is Node's `worker_threads` one */
     on?(type: 'message' | 'error', listener: (value: unknown) => void): void;
+    /** Stops a listener added with `on` */
     off?(type: 'message' | 'error', listener: (value: unknown) => void): void;
 }
 /**
@@ -33,10 +38,13 @@ export interface WorldWorkerLike {
  * @beta
  */
 export interface WorldPort {
+    /** Sends a message to the page, with objects to transfer rather than copy */
     postMessage(message: unknown, transfer?: unknown[]): void;
+    /** Listens for the page's messages, where the port is a worker scope */
     addEventListener?(type: 'message', listener: (event: {
         data: unknown;
     }) => void): void;
+    /** Listens for the page's messages, where the port is Node's `parentPort` */
     on?(type: 'message', listener: (value: unknown) => void): void;
 }
 /**
@@ -47,16 +55,39 @@ export interface WorldPort {
 export interface WorkerGame {
     /** A map of the game: the world is made from it. Or a save to go on from (`from`); or neither, where the worker makes its world in code */
     map?: GameMap;
+    /** A save to continue the game from, in place of a map */
     from?: WorldSave;
     /** Who the player at the screen is: as the worker says (`ServeWorldOptions.player`), then the map's first with a start, when left out */
     player?: PlayerId;
+    /** The seed the world's random generator starts with */
     seed?: number;
     /** Whether the player may use the debug tools, and sees everything from the start */
     debug?: boolean;
+    /** Whether the player sees the whole map from the start */
     reveal?: boolean;
     /** Anything else the worker's own code is to know (`start`, `world`): plain data */
     args?: unknown;
 }
+/**
+ * What the worker's code that runs on a world is given (`ServeWorldOptions.onStart`, `beforePlay`): the player at the
+ * screen, the map, what the page sent (`WorkerGame.args`), and a way to tell the page something
+ *
+ * @beta
+ */
+export interface WorkerGameContext {
+    /** The player at the screen */
+    player: PlayerId;
+    /** The map the world was made from, where it was made from one (or sent with a save) */
+    map?: GameMap;
+    /** What the page sent for the worker's own code (`WorkerGame.args`): plain data */
+    args: unknown;
+    /**
+     * Tells the page something, while this game lasts: plain data, as it crosses (a mission won and what it carries on).
+     * The page hears it on its session (`WorkerSession.onTold`), in order with the game's ticks: what is told in a tick
+     * is heard before the snapshot of that tick. Said for nothing once the game has ended
+     */
+    tell(data: unknown): void;
+}
 /**
  * What the worker's file gives besides the game: its code that runs on the world, which cannot be sent
  *
@@ -65,19 +96,33 @@ export interface WorkerGame {
 export interface ServeWorldOptions {
     /** A world made in code, where the page gives neither a map nor a save: generated ground, players of its own */
     world?: (context: {
-        rules: GameModule;
+        rules: Rules;
         seed: number;
         args: unknown;
         log: Logger;
     }) => World | Promise<World>;
     /** What the game does once a new world is made, before anyone plays: as `launch`'s `start`, which a worker's game has here */
-    start?: (world: World, context: {
-        player: PlayerId;
-        map?: GameMap;
-        args: unknown;
+    onStart?: (world: World, context: WorkerGameContext) => void | Promise<void>;
+    /**
+     * What the game does before anyone plays, a new world or one loaded from a save (`fresh`), after `onStart`: as
+     * `prepareGame`'s `beforePlay`, which a worker's game has here. What it listens to on the world it listens to for
+     * this game alone, as a loaded game has none of what the game before listened to
+     */
+    beforePlay?: (world: World, context: WorkerGameContext & {
+        fresh: boolean;
     }) => void | Promise<void>;
     /** Who the player at the screen is, where the page does not say */
     player?: (world: World, map?: GameMap) => PlayerId;
+    /**
+     * What the page is told of the world as the game starts, which it cannot reach into: where the player's base is, who
+     * the other side is. Plain data, as it crosses; the page reads it on its session (`WorkerSession.about`). Asked once
+     * the world is made and started (`onStart`), for a new game and for one loaded
+     */
+    about?: (world: World, context: {
+        player: PlayerId;
+        map?: GameMap;
+        args: unknown;
+    }) => unknown;
     /** Where it hears: the worker's own scope when left out (a page's worker); Node's `parentPort` in a worker thread */
     port?: WorldPort;
     /**
@@ -86,7 +131,7 @@ export interface ServeWorldOptions {
      * now: `(version) => import(/* @vite-ignore *\/ `./index.ts?t=${version}`).then((module) => module.myGame)` (a path
      * from the worker's file). Only ever asked for in the dev server. Without it, a game in the worker keeps the version it began with
      */
-    reload?: (version: number) => Promise<GameModule | undefined> | GameModule | undefined;
+    reload?: (version: number) => Promise<Rules | undefined> | Rules | undefined;
 }
 /** What goes between the page and the worker besides the session's own text */
 type ToWorker = ({
@@ -115,6 +160,7 @@ type ToWorker = ({
 type FromWorker = {
     vg: 'ready';
     player: PlayerId;
+    about?: unknown;
 } | {
     vg: 'refused';
     message: string;
@@ -142,15 +188,18 @@ type FromWorker = {
     tickMax: number;
     send: number;
     systems: SystemTiming[];
+} | {
+    vg: 'told';
+    data: unknown;
 };
 /**
- * What a game's worker file does: `serveWorld(game, { start })`. It waits for the page to say what to play (a map, a
+ * What a game's worker file does: `serveWorld(game, { onStart })`. It waits for the page to say what to play (a map, a
  * save, or nothing for a world made here in code), makes the world, runs it by the clock, and seats the page's player
  * at it. A new game asked for ends the one before: a restart is the same worker, its navigation built already
  *
- * @beta
+ * @public
  */
-export declare function serveWorld(first: GameModule, options?: ServeWorldOptions): void;
+export declare function serveWorld(first: Rules, options?: ServeWorldOptions): void;
 /**
  * A seat at a game run in a worker of this page (`workerSession`): a `RemoteSession` whose host is a message away,
  * with what a game played in the page has besides: its pace held and stepped (`speed`, `advance`), a save of it
@@ -161,10 +210,13 @@ export declare function serveWorld(first: GameModule, options?: ServeWorldOption
 export declare class WorkerSession extends RemoteSession {
     /** What the world says (`World.log`), said again here: the page shows it with its own */
     log: Logger;
+    /** The label and save of the last checkpoint the worker's game took, to retry from */
     checkpoint?: {
         label: Message;
         save: WorldSave;
     };
+    /** What the worker's file said of the world as the game started (`ServeWorldOptions.about`): plain data, none where it says nothing */
+    about?: unknown;
     /** The debug tools' view of the world, where they are on: over the session's own words, as a server's is */
     get debug(): SessionDebug | undefined;
     /** Its pace held and stepped, saves of it, the debug tools' view where they are on, and where its time went and in which systems */
@@ -177,24 +229,36 @@ export declare class WorkerSession extends RemoteSession {
     private readonly saves;
     private nextSave;
     private stopHearing;
+    /** Who hears what the worker's code tells (`onTold`), and what it told before anyone listened */
+    private readonly listening;
+    private readonly toldBefore;
     /** What `workerSession` gives it once it is made: the way to the worker, and what stops hearing it */
     wire(post: (message: ToWorker) => void, log: Logger, stop: () => void): void;
     /** What the worker said that is not the session's own text */
     heard(said: FromWorker): void;
+    /**
+     * Hears what the worker's code tells the page (`WorkerGameContext.tell`): plain data, in order with the ticks. What
+     * it told before anyone listened is heard by the first listener, at once. Gives back what stops hearing it
+     */
+    onTold(listener: (data: unknown) => void): () => void;
     /**
      * How far behind the newest tick the screen is shown, in ticks: one, and room for how unevenly they come (a tick
      * that took long comes late). Less than over a wire, where two are kept in hand: there is no line to stall here
      */
     get delay(): number;
+    /** The simulation speed multiplier the worker's game runs at, 0 pauses; setting it tells the worker */
     get speed(): number;
     set speed(speed: number);
+    /** Asks the worker to step the held game by this many ticks */
     advance(ticks?: number): void;
     /**
      * Asks the worker to take a new version of the game (hot reload): it loads the game again itself, as its file says
      * (`serveWorld` `reload`), and puts it into its world
      */
     reloadGame(): void;
+    /** Asks the worker for a save of its world and resolves with it; rejects if the game ends first */
     save(): Promise<WorldSave>;
+    /** Where the worker's time went (tick, send and receive milliseconds and each system's), or undefined until it has said */
     timing(): {
         tick: number;
         tickMax: number;
@@ -211,7 +275,8 @@ export declare class WorkerSession extends RemoteSession {
  * @beta
  */
 export interface WorkerSessionOptions extends WorkerGame, Pick<ConnectOptions, 'navigation' | 'maps'> {
-    game: GameModule;
+    /** The game module's rules the worker's game runs, which the page needs the data of */
+    rules: Rules;
     /** The logger what the world says is said under, in the page: the root one when left out */
     log?: Logger;
 }
@@ -219,7 +284,7 @@ export interface WorkerSessionOptions extends WorkerGame, Pick<ConnectOptions, '
  * Plays a game in a worker, and seats this page's player at it: the worker's file calls `serveWorld` with the same
  * game. Settles once the world is made there and its welcome is in; fails with what the worker said went wrong
  *
- *     const session = await workerSession(new Worker(new URL('./game.worker.ts', import.meta.url), { type: 'module' }), { game, map })
+ *     const session = await workerSession(new Worker(new URL('./game.worker.ts', import.meta.url), { type: 'module' }), { rules: game, map })
  *
  * @beta
  */