@hopple/netcode 0.0.0-stage → 0.1.1-ci.1

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@hopple/netcode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1-ci.1",
+  "description": "What a Hopple game bundles to play a match over the network: exact byte encoding, a lobby, and a lockstep helper with rollback.",
+  "license": "MIT",
+  "homepage": "https://hopple.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pamarit/hopple.git"
+  },
+  "keywords": [
+    "hopple",
+    "game",
+    "netcode",
+    "lockstep",
+    "rollback",
+    "lobby",
+    "multiplayer"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@hopple/bytes": "^0.1.1-ci.1"
+  },
+  "peerDependencies": {
+    "@hopple/sdk": "^1.0.0-next.1",
+    "@hopple/sdk-preview-network": "^0.1.0"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./session": {
+      "types": "./session.d.ts",
+      "default": "./session.js"
+    },
+    "./lockstep": {
+      "types": "./lockstep.d.ts",
+      "default": "./lockstep.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./index.js",
+  "types": "./index.d.ts"
+}

package/session.d.ts

@@ -0,0 +1,226 @@
+import { ByteReader, ByteWriter } from "@hopple/bytes";
+//#region src/session.d.ts
+/**
+ * The first byte of every message the session sends. A game sending messages
+ * of its own in the same match starts them with any other byte.
+ *
+ * @group Session
+ */
+declare const SESSION_TAG = 246;
+/**
+ * How a value of the game's travels: written after the session's own bytes,
+ * and read back in the same order. A `read` that throws is a message that
+ * does not count.
+ *
+ * @group Session
+ */
+type Codec<T> = {
+  write(out: ByteWriter, value: T): void;
+  read(input: ByteReader): T;
+};
+/**
+ * What the session needs of a person: `@hopple/sdk-preview-network`'s `Person` has it all.
+ *
+ * @group Session
+ */
+type SessionPerson = {
+  readonly id: string;
+  readonly me: boolean;
+  readonly connected: boolean;
+  /** How many players play on their device, as the match counts them. One when left out. */
+  readonly locals?: number;
+};
+/**
+ * What the session needs of a match: `@hopple/sdk-preview-network`'s `Match` has it all.
+ *
+ * @group Session
+ */
+type SessionMatch<P extends SessionPerson = SessionPerson> = {
+  readonly id: string;
+  readonly maxPlayers: number;
+  readonly role: 'player' | 'spectator' | null;
+  readonly me: P | null;
+  readonly players: readonly P[];
+  readonly host: P | null;
+  readonly ended: boolean;
+  readonly kept: readonly {
+    readonly data: Uint8Array;
+    readonly from: P;
+    readonly key: number;
+    readonly seq: number;
+  }[];
+  send(data: Uint8Array, options?: {
+    keep?: number;
+  }): void;
+  onMessage(listener: (data: Uint8Array, from: P, seq: number) => void): () => void;
+  on(listener: () => void): () => void;
+};
+/**
+ * What the session needs of the game's matches: `@hopple/sdk-preview-network`'s `sdk.match`
+ * has it all.
+ *
+ * @group Session
+ */
+type SessionMatches<P extends SessionPerson = SessionPerson> = {
+  readonly current: SessionMatch<P> | null;
+  onChange(listener: (match: SessionMatch<P> | null) => void): () => void;
+};
+/**
+ * A game the host started, as every device builds it. It has what
+ * `lockstep` needs, so `lockstep({ ...start, sample, step })` runs it.
+ *
+ * @group Session
+ */
+type Start<Pick, Config, P extends SessionPerson = SessionPerson> = {
+  /** The match it is played in. */
+  match: SessionMatch<P>;
+  /** Where the start fell in the match's order: the run hears only what follows. */
+  seq: number;
+  /** A number for this game, different from the match's other games. */
+  run: number;
+  /** For the game's random generator: the same on every device. */
+  seed: number;
+  /** Who plays, by person id, in seat order: a seat is a device. */
+  seats: string[];
+  /**
+   * How many players play on each seat's device, in seat order, as the match
+   * counted them when the host started: what `lockstep` takes to run one
+   * input per player.
+   */
+  locals: number[];
+  /** Every player of the game, seat by seat and each seat's players in order: what `step` is given inputs for. */
+  players: StartPlayer[];
+  /** What each seat picked, as the host saw it. */
+  picks: Pick[];
+  /** The game's own config, as the host gave it. */
+  config: Config;
+  /** This device's person id: a device whose person has no seat watches. */
+  me: string;
+};
+/**
+ * One player of a game: a seat's device, and which of its players.
+ *
+ * @group Session
+ */
+type StartPlayer = {
+  /** Their seat, in `seats`. */
+  seat: number;
+  /** Their person's id. */
+  person: string;
+  /** Which of their device's players they are, from 0: `sdk.input.players`' order. */
+  local: number;
+  /** Whether they play on this device. */
+  me: boolean;
+};
+/**
+ * A player in the match, as the lobby shows them.
+ *
+ * @group Session
+ */
+type SessionPlayer<Pick, P extends SessionPerson = SessionPerson> = {
+  person: P;
+  /** What they picked: the game's `initial` until they say. */
+  pick: Pick;
+  /** Whether they said they are ready for the next game. */
+  ready: boolean;
+  /** Whether they host the match: they set it up and start each game. */
+  host: boolean;
+};
+/**
+ * @group Session
+ */
+type SessionOptions<Pick, Settings, Config, P extends SessionPerson> = {
+  /** `sdk.match`: the session is the lobby of whichever match is current. */
+  match: SessionMatches<P>;
+  /** What a player picks, as it travels, and what it is before they pick. */
+  pick: Codec<Pick> & {
+    initial: Pick;
+  };
+  /** The host's settings, as they travel, and what they are before a host says. */
+  settings: Codec<Settings> & {
+    initial: Settings;
+  };
+  /** What the host's start carries of the game's own, as it travels. */
+  config: Codec<Config>;
+  /**
+   * The host started a game: build it from `start` alone. Run in the listener
+   * that heard it, on every device in the match, watchers included.
+   */
+  onStart(start: Start<Pick, Config, P>): void;
+  /** The keys the session keeps its messages under: 0 and 1 by default. */
+  keys?: {
+    pick?: number;
+    settings?: number;
+  };
+};
+/**
+ * A match's lobby, followed as the player's match comes and goes.
+ *
+ * @group Session
+ */
+type Session<Pick, Settings, Config, P extends SessionPerson = SessionPerson> = {
+  /** The match the player is in, or `null`. */
+  readonly match: SessionMatch<P> | null;
+  /** This player's person id, or `''` outside a match. */
+  readonly me: string;
+  /** Whether this player hosts the match: they set it up and start each game. */
+  readonly hosting: boolean;
+  /** Who plays the match, in the order they joined, with what each picked. */
+  readonly players: readonly SessionPlayer<Pick, P>[];
+  /**
+   * The players the host waits for, the host aside: those connected and not
+   * ready. Somebody whose connection is down is not waited for: seated
+   * anyway, a lockstep run hands their seat to the game until they are back.
+   */
+  readonly waiting: readonly P[];
+  /** What this player picked, and whether they are ready. */
+  readonly mine: {
+    readonly pick: Pick;
+    readonly ready: boolean;
+  };
+  /** The host's settings, as last heard: kept by a new host until it changes them. */
+  readonly settings: Settings;
+  /** Say what this player picks. */
+  pick(pick: Pick): void;
+  /** Say whether this player is ready for the next game. */
+  ready(ready: boolean): void;
+  /** The host changes the settings (an object's are merged). Anybody else's change is ignored, and `false`. */
+  configure(settings: Partial<Settings>): boolean;
+  /**
+   * The host starts a game with `config`, seating `seats` (every player, in the
+   * order they joined, by default). Every device hears it in `onStart`. `false`
+   * for anybody but the host.
+   */
+  start(config: Config, seats?: readonly string[]): boolean;
+  /** Stop following the match. */
+  close(): void;
+};
+/**
+ * Whether a match message is one of the session's, for a game's own listener
+ * to skip.
+ *
+ * @group Session
+ */
+declare function isSessionMessage(data: Uint8Array): boolean;
+/**
+ * Follow the player's match as a lobby. See the module for how.
+ *
+ * ```ts
+ * const lobby = session({
+ *   match: sdk.match,
+ *   pick: { initial: 0, write: (out, fighter) => out.uint(fighter), read: (input) => input.uint() },
+ *   settings: { initial: { rounds: 3 }, write: (out, s) => out.uint(s.rounds), read: (input) => ({ rounds: input.uint() }) },
+ *   config: { write: (out, c) => out.uint(c.rounds), read: (input) => ({ rounds: input.uint() }) },
+ *   onStart: (start) => play(start),
+ * });
+ * await sdk.match.play({ maxPlayers: 4 });
+ * lobby.pick(fighter);
+ * lobby.ready(true);
+ * if (lobby.hosting && lobby.waiting.length === 0) lobby.start({ rounds: lobby.settings.rounds });
+ * ```
+ *
+ * @group Session
+ */
+declare function session<Pick, Settings, Config, P extends SessionPerson>(options: SessionOptions<Pick, Settings, Config, P>): Session<Pick, Settings, Config, P>;
+//#endregion
+export { Codec, SESSION_TAG, Session, SessionMatch, SessionMatches, SessionOptions, SessionPerson, SessionPlayer, Start, StartPlayer, isSessionMessage, session };

package/session.js

@@ -0,0 +1,361 @@
+import { ByteReader, ByteWriter } from "@hopple/bytes";
+//#region src/session.ts
+/**
+* The lobby every networked game has between its games: what each player
+* picked and whether they are ready, the host's settings, and starting each
+* game so that every device builds the same one. Optional: a game is welcome
+* to write its own on the SDK's match.
+*
+* **Nothing is said twice.** A player's pick and readiness are one message
+* kept under one key, and the host's settings one kept under another: whoever
+* joins later, or whose game loads again, finds them in `match.kept`, so
+* nobody says them again on a timer. A game loaded again picks up its own; a
+* player whose connection comes back says theirs again, as what they said as
+* it went may have gone with it.
+*
+* **The host starts each game with one message**, not kept, carrying a run
+* number, a seed, who sits where and what each of them picked, and the
+* game's own config: every device hears it at the same place in the log, and
+* builds the game from it alone. A start from anybody else starts nothing.
+* Nobody is ready for the game after it until they say so again.
+*
+* **The host is the match's**, as the relay picks it: the player who made
+* it, then whoever it was handed to, then, once the host has been gone a
+* while, the one still there who has played it longest. A new host keeps the
+* settings the last one left, and can start the next game.
+*
+* **Being in a match is the game's.** The session follows `sdk.match.current`
+* and never joins or makes a match of its own: the game calls
+* `sdk.match.play()` or `create()`, or the host puts the player in one, and
+* the session is the lobby of whichever match that is.
+*
+* Its messages start with `SESSION_TAG`; a game's own in the same match start
+* with any other byte, and `isSessionMessage` tells them apart.
+*
+* @module session
+*/
+/**
+* The first byte of every message the session sends. A game sending messages
+* of its own in the same match starts them with any other byte.
+*
+* @group Session
+*/
+const SESSION_TAG = 246;
+const PICK = 1;
+const SETTINGS = 2;
+const START = 3;
+/** The most seats a start message is read with. */
+const MOST_SEATS = 64;
+/**
+* Whether a match message is one of the session's, for a game's own listener
+* to skip.
+*
+* @group Session
+*/
+function isSessionMessage(data) {
+	return data[0] === 246;
+}
+function encode(codec, value) {
+	const out = new ByteWriter();
+	codec.write(out, value);
+	return out.finish();
+}
+/**
+* Follow the player's match as a lobby. See the module for how.
+*
+* ```ts
+* const lobby = session({
+*   match: sdk.match,
+*   pick: { initial: 0, write: (out, fighter) => out.uint(fighter), read: (input) => input.uint() },
+*   settings: { initial: { rounds: 3 }, write: (out, s) => out.uint(s.rounds), read: (input) => ({ rounds: input.uint() }) },
+*   config: { write: (out, c) => out.uint(c.rounds), read: (input) => ({ rounds: input.uint() }) },
+*   onStart: (start) => play(start),
+* });
+* await sdk.match.play({ maxPlayers: 4 });
+* lobby.pick(fighter);
+* lobby.ready(true);
+* if (lobby.hosting && lobby.waiting.length === 0) lobby.start({ rounds: lobby.settings.rounds });
+* ```
+*
+* @group Session
+*/
+function session(options) {
+	const matches = options.match;
+	const pickKey = options.keys?.pick ?? 0;
+	const settingsKey = options.keys?.settings ?? 1;
+	let match = null;
+	let stopMatch = null;
+	const mine = {
+		pick: options.pick.initial,
+		ready: false
+	};
+	let settings = options.settings.initial;
+	/** Where the settings last taken from the match fell in its order. */
+	let settingsSeq = 0;
+	/** Each player's kept pick, read once: by person id. */
+	const picks = /* @__PURE__ */ new Map();
+	/** Where the last start fell: readiness said before it was for that game. */
+	let startedAt = 0;
+	/** Whether this player's pick, and as host its settings, are kept in the match now. */
+	let said = false;
+	let hostSaid = false;
+	/** Whether this player's connection was down while playing: what it said as it went may have gone with it. */
+	let dropped = false;
+	function readPick(data) {
+		try {
+			const input = new ByteReader(data);
+			if (input.byte() !== 246 || input.byte() !== PICK) return null;
+			return {
+				ready: input.bool(),
+				pick: options.pick.read(input)
+			};
+		} catch {
+			return null;
+		}
+	}
+	function readSettings(data) {
+		try {
+			const input = new ByteReader(data);
+			if (input.byte() !== 246 || input.byte() !== SETTINGS) return null;
+			return { value: options.settings.read(input) };
+		} catch {
+			return null;
+		}
+	}
+	function playing() {
+		return match !== null && match.role === "player" && !match.ended;
+	}
+	function hosting() {
+		return playing() && match.host?.me === true;
+	}
+	function sendPick() {
+		if (!playing()) return;
+		const out = new ByteWriter().byte(246).byte(PICK).bool(mine.ready);
+		options.pick.write(out, mine.pick);
+		said = true;
+		match.send(out.finish(), { keep: pickKey });
+	}
+	function sendSettings() {
+		if (!hosting()) return;
+		const out = new ByteWriter().byte(246).byte(SETTINGS);
+		options.settings.write(out, settings);
+		hostSaid = true;
+		match.send(out.finish(), { keep: settingsKey });
+	}
+	/** What the match keeps now, read: everybody's picks, and the newest settings somebody else kept. */
+	function refresh() {
+		if (match === null) return;
+		let newest = null;
+		for (const one of match.kept) {
+			if (one.data[0] !== 246) continue;
+			if (one.key === pickKey) {
+				if (picks.get(one.from.id)?.seq === one.seq) continue;
+				const read = readPick(one.data);
+				if (read !== null) picks.set(one.from.id, {
+					seq: one.seq,
+					...read
+				});
+			} else if (one.key === settingsKey && !one.from.me && one.seq > settingsSeq && (newest === null || one.seq > newest.seq)) newest = one;
+		}
+		if (newest !== null) {
+			settingsSeq = newest.seq;
+			const read = readSettings(newest.data);
+			if (read !== null) settings = read.value;
+		}
+	}
+	/** The match changed: read it, and say what this player has not said in it. */
+	function changed() {
+		refresh();
+		if (!playing()) {
+			said = hostSaid = false;
+			dropped = false;
+			return;
+		}
+		if (match.me?.connected === false) {
+			dropped = true;
+			return;
+		}
+		if (dropped) {
+			dropped = false;
+			said = hostSaid = false;
+		}
+		if (!said) sendPick();
+		if (!hosting()) hostSaid = false;
+		else if (!hostSaid) sendSettings();
+	}
+	function follow(next) {
+		if (next === match) return;
+		stopMatch?.();
+		stopMatch = null;
+		match = next;
+		picks.clear();
+		settingsSeq = 0;
+		startedAt = 0;
+		said = hostSaid = false;
+		dropped = false;
+		if (next !== null) {
+			let newest = 0;
+			for (const one of next.kept) newest = Math.max(newest, one.key === settingsKey ? one.seq : 0);
+			for (const one of next.kept) {
+				if (!one.from.me || next.role !== "player") continue;
+				if (one.key === pickKey) {
+					const read = readPick(one.data);
+					if (read !== null) {
+						mine.pick = read.pick;
+						mine.ready = read.ready;
+						said = true;
+					}
+				} else if (one.key === settingsKey) {
+					const read = readSettings(one.data);
+					if (read !== null && one.seq === newest) {
+						settings = read.value;
+						settingsSeq = one.seq;
+						hostSaid = true;
+					}
+				}
+			}
+			const stops = [next.onMessage(hear), next.on(changed)];
+			stopMatch = () => stops.forEach((stop) => stop());
+		}
+		changed();
+	}
+	function hear(data, from, seq) {
+		if (data[0] !== 246 || match === null) return;
+		if (data[1] !== START) {
+			refresh();
+			return;
+		}
+		if (from.id !== match.host?.id) return;
+		let start;
+		try {
+			const input = new ByteReader(data.subarray(2));
+			const run = input.uint();
+			const seed = input.uint();
+			const count = input.uint();
+			if (count > MOST_SEATS) return;
+			const seats = [];
+			const locals = [];
+			const chosen = [];
+			for (let i = 0; i < count; i++) {
+				seats.push(input.string());
+				locals.push(Math.max(1, Math.min(MOST_SEATS, input.uint())));
+				const bytes = input.bytes();
+				let pick = options.pick.initial;
+				try {
+					pick = options.pick.read(new ByteReader(bytes));
+				} catch {}
+				chosen.push(pick);
+			}
+			const config = options.config.read(input);
+			const me = match.me?.id ?? "";
+			const players = seats.flatMap((person, seat) => Array.from({ length: locals[seat] }, (_, local) => ({
+				seat,
+				person,
+				local,
+				me: person === me
+			})));
+			start = {
+				match,
+				seq,
+				run,
+				seed,
+				seats,
+				locals,
+				players,
+				picks: chosen,
+				config,
+				me
+			};
+		} catch {
+			return;
+		}
+		startedAt = seq;
+		if (mine.ready) {
+			mine.ready = false;
+			sendPick();
+		}
+		options.onStart(start);
+	}
+	const stop = matches.onChange(follow);
+	follow(matches.current);
+	return {
+		get match() {
+			return match;
+		},
+		get me() {
+			return match?.me?.id ?? "";
+		},
+		get hosting() {
+			return hosting();
+		},
+		get players() {
+			const current = match;
+			if (current === null) return [];
+			return current.players.map((person) => {
+				const host = person.id === current.host?.id;
+				if (person.me) return {
+					person,
+					pick: mine.pick,
+					ready: mine.ready,
+					host
+				};
+				const known = picks.get(person.id);
+				return {
+					person,
+					pick: known?.pick ?? options.pick.initial,
+					ready: known !== void 0 && known.ready && known.seq > startedAt,
+					host
+				};
+			});
+		},
+		get waiting() {
+			return this.players.filter((one) => !one.host && !one.ready && one.person.connected).map((one) => one.person);
+		},
+		get mine() {
+			return {
+				pick: mine.pick,
+				ready: mine.ready
+			};
+		},
+		get settings() {
+			return settings;
+		},
+		pick(pick) {
+			mine.pick = pick;
+			sendPick();
+		},
+		ready(ready) {
+			mine.ready = ready;
+			sendPick();
+		},
+		configure(change) {
+			if (!hosting()) return false;
+			settings = typeof settings === "object" && settings !== null && !Array.isArray(settings) ? {
+				...settings,
+				...change
+			} : change;
+			sendSettings();
+			return true;
+		},
+		start(config, seats) {
+			if (!hosting()) return false;
+			const ids = (seats ?? match.players.map((one) => one.id)).slice(0, MOST_SEATS);
+			const out = new ByteWriter().byte(246).byte(START).uint(Math.floor(Math.random() * 2147483647)).uint(Math.floor(Math.random() * 4294967296)).uint(ids.length);
+			for (const id of ids) {
+				const pick = id === match.me?.id ? mine.pick : picks.get(id)?.pick ?? options.pick.initial;
+				const locals = match.players.find((one) => one.id === id)?.locals ?? 1;
+				out.string(id).uint(Math.max(1, locals)).bytes(encode(options.pick, pick));
+			}
+			options.config.write(out, config);
+			match.send(out.finish());
+			return true;
+		},
+		close() {
+			stopMatch?.();
+			stopMatch = null;
+			stop();
+		}
+	};
+}
+//#endregion
+export { SESSION_TAG, isSessionMessage, session };