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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Hopple authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,198 @@
-# Temporary Holding Version
+# @hopple/netcode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+What a game bundles to play a match over the network, on the Hopple SDK's
+match: its messages as bytes, the lobby between games, and a lockstep helper,
+with rollback.
+
+```bash
+npm install @hopple/sdk-preview-network @hopple/netcode
+```
+
+A game **bundles** it, as it bundles
+[`@hopple/deterministic`](https://www.npmjs.com/package/@hopple/deterministic):
+whatever decides the game is frozen into the game when it is built, so every
+device in a match runs the same bytes. It needs nothing but the game's own
+`@hopple/sdk` and
+[`@hopple/sdk-preview-network`](https://www.npmjs.com/package/@hopple/sdk-preview-network), peer
+dependencies, runs the same in browsers and in Node, and a game takes only the
+parts it imports. Install `@hopple/sdk-preview-network` beside it, as above, even where a
+package manager would install it for you: depending on it is what tells
+`hopple` the game plays over the network, and at which revision.
+
+The only contract is the network preview's match: one log, every message in one order on
+every device, the sender's own included, and what each player kept there for
+whoever comes later. A game is welcome to write any part of this its own way.
+
+## Bytes
+
+A match's messages are bytes. `ByteWriter` and `ByteReader`, from
+[`@hopple/bytes`](https://www.npmjs.com/package/@hopple/bytes) and exported
+here as well, write numbers, strings and packed bits, and read them back
+exactly: integers as varints (a byte under 128), floats as their bits,
+strings as UTF-8.
+
+```ts
+import { ByteReader, ByteWriter } from '@hopple/netcode';
+
+match.send(new ByteWriter().uint(PICK).uint(fighter).bool(ready).finish());
+
+const read = new ByteReader(data);   // throws a RangeError on a malformed message
+```
+
+## The lobby
+
+`@hopple/netcode/session` is the lobby every networked game has between its
+games: each player's pick and readiness, the host's settings, and the start of
+each game.
+
+```ts
+import { ByteWriter } from '@hopple/netcode';
+import { session } from '@hopple/netcode/session';
+
+const lobby = session({
+  match: sdk.match,
+  // What a player picks, and how it travels: written after the session's own bytes.
+  pick: { initial: 0, write: (out, fighter) => out.uint(fighter), read: (input) => input.uint() },
+  // The host's settings.
+  settings: { initial: { rounds: 3 }, write: (out, s) => out.uint(s.rounds), read: (input) => ({ rounds: input.uint() }) },
+  // What the host's start carries of the game's own.
+  config: { write: (out, c) => out.uint(c.rounds), read: (input) => ({ rounds: input.uint() }) },
+  // Every device in the match, at the same place in the log: build the game from `start` alone.
+  onStart: (start) => play(start),
+});
+
+await sdk.match.play({ maxPlayers: 4 });   // the party's match, or a new one
+lobby.pick(fighter);
+lobby.ready(true);
+for (const one of lobby.players) drawPlayer(one.person.name, one.pick, one.ready, one.host);
+
+if (lobby.hosting) {
+  lobby.configure({ rounds: 5 });
+  if (lobby.waiting.length === 0) lobby.start({ rounds: lobby.settings.rounds });
+}
+```
+
+- **Nothing is said twice.** A pick and readiness are one message kept under
+  one key, the host's settings one kept under another: whoever joins later, or
+  whose game loads again, finds them in `match.kept`. A game loaded again picks
+  up its own pick, readiness and, as host, settings.
+- **The host starts each game with one message** carrying a run number, a
+  seed, who sits where (every player in the order they joined, or the seats
+  `start` is given), what each picked as the host saw it, and the game's
+  config. Every device hears it at the same `seq` and builds the same game; a
+  device whose person has no seat watches. A start from anybody else starts
+  nothing. Nobody is ready for the next game until they say so again.
+- **The host is the match's**: the player who made it, then whoever it was
+  handed to, then, once the host has been disconnected or away for 10 s, the
+  one still there who has played it longest. Read `lobby.hosting` every frame, not once. A new
+  host keeps the settings the last one left. `lobby.waiting` leaves out
+  anybody whose connection is down: seated anyway, a lockstep run hands their
+  seat to the game until they are back.
+- **Being in the match is the game's.** The session follows
+  `sdk.match.current` and never joins or makes a match itself: the game calls
+  `sdk.match.play()` or `create()`, or the host puts the player in one from
+  an invite or a link, and the session is the lobby of whichever match that
+  is. A player whose connection comes back says their pick, and as host the
+  settings, again, as what was said as it went may have gone with it.
+- Its messages start with `SESSION_TAG`, and `isSessionMessage` tells them
+  apart; it keeps under keys 0 and 1 unless `keys` says otherwise.
+
+## Lockstep, if it suits
+
+`@hopple/netcode/lockstep` is one way to keep a match's devices in step: every
+device runs the same game, step by step, on every player's input for that
+step. Its game is one that computes the same everywhere: `@hopple/deterministic`.
+
+```ts
+import { hash } from '@hopple/deterministic';
+import { lockstep } from '@hopple/netcode/lockstep';
+
+// The session's start has what a run needs: the match, its `seq`, the run, the seats and `me`.
+function play(start) {
+  game = newGame(start.seed, start.picks, start.config);
+  run = lockstep({
+    ...start,
+    sample: () => Uint8Array.of(buttons()),        // this device's input, a few bytes
+    step: (inputs) => game.step(inputs),           // every seat's, or null for one the game plays
+    hash: () => hash(game.summary()),
+    onDesync: (tick) => report(tick),
+    onLost: () => leave(),
+  });
+}
+
+sdk.loop.tick((dt) => {
+  run?.advance(dt * 1000);
+  draw();
+});
+```
+
+- **Several players on one device.** The session's start says how many play
+  on each seat's device, as the match counts them (`start.locals`), and every
+  player of the game seat by seat (`start.players`: `seat`, `person`, `local`,
+  `me`). Given `locals`, which `...start` hands it, `sample` returns one input
+  for each player on this device and `step` is given one for each player of the
+  match; a device's players still travel in one message, and a device handed to
+  the game hands over each of its players.
+
+  ```ts
+  const mine = start.players.filter((one) => one.me).length;
+  sample: () => sdk.input.players.slice(0, mine).map((player) => bits(player.read())),
+  step: (inputs) => game.step(inputs),             // one for each of start.players
+  ```
+
+Without the session, a run is made in the listener that hears the message
+starting it, with that message's `seq`, a `run` number that differs from the
+match's other runs, and the same `seats` on every device.
+
+- **Input delay, as the network needs.** Each device's input is read some
+  steps ahead of the step it is for, so it can cross the relay in time. Every
+  device times its own round trips and says how many steps it needs, and all of
+  them read with the most any player needs: the same delay for everybody, so
+  nobody's controls answer later than another's. It grows as soon as somebody
+  needs more and shrinks after a few seconds of needing less. A game sets its
+  bounds, the same on every device: `delay: { min, max, start }` (2, 20 and 6
+  steps by default; a step is 16.7 ms). Round trips longer than `max` slow the
+  match down; `min` equal to `max` holds the delay fixed. `run.delay` is the
+  delay now, and `run.rtt` the last round trip.
+- **Sampling.** `sample` is asked for each step in order, but not always once a
+  frame: several times while the delay grows, and now and then not at all while
+  it shrinks. Give each press to the one call after it.
+- **Waiting and catching up.** A step runs once every seat's input for it is
+  in, the device's own included. Until then the game waits; after a hitch, or
+  time in the background, it catches up, up to `catchUp` steps a frame.
+- **Seats handed to the game.** A seat whose person left the match, or kept
+  everybody waiting for `timeoutMs`, reaches `step` as `null` from a step every
+  device agrees on: the game plays it (its AI, or nobody). Its device, once
+  caught up, asks for it back.
+- **Rollback, optionally.** With `rollback: { steps, save, restore, predict? }`
+  a device does not wait for the others' inputs: it runs on, up to `steps`
+  ahead of the log, guessing that each player still presses what they last
+  pressed (`predict` says otherwise, for inputs that say what went down this
+  step). When an input differs from the guess, it `restore`s the game to before
+  that step and runs it and the steps after it again, with `again` true: what
+  those played and showed has been. The delay then covers only the round trip
+  beyond what guessing covers, so a player's own controls answer after a step
+  or two. `run.confirmed` is how far the log has settled; hold back anything
+  that cannot be taken back (achievements, scores, the match's end) until it
+  passes the step. Somebody who only watches runs confirmed steps alone.
+
+  Lockstep suits games whose state is large or hard to copy, that are slow
+  enough not to mind the delay (turns, strategy, puzzles), or whose steps are
+  expensive. Rollback suits fast games with a small state, where a press must
+  answer at once: a bat, a fighter, a racer. It costs a `save` a step and up to
+  `steps` steps run again in a frame, and others' moves can jump when a guess
+  was wrong.
+- **Desyncs.** Every `hashEvery` steps the devices compare fingerprints, and
+  `onDesync` says from which step they differ.
+- **A device whose connection dropped** hears what it missed once it is back,
+  and carries on (its seat may have been handed to the game meanwhile, and is
+  asked back). One that missed more than the relay still held, a gap in its
+  numbering, cannot follow any more: `onLost`.
+- **Thirty messages a second** at most from each device, a few bytes each.
+- Messages of the run start with `LOCKSTEP_TAG`; a game's own messages in the
+  same match start with any other byte, and `isLockstepMessage` tells them
+  apart.
+
+## License
+
+MIT; see `LICENSE`.

package/index.d.ts

@@ -0,0 +1,2 @@
+import { ByteReader, ByteWriter } from "@hopple/bytes";
+export { ByteReader, ByteWriter };

package/index.js

@@ -0,0 +1,2 @@
+import { ByteReader, ByteWriter } from "@hopple/bytes";
+export { ByteReader, ByteWriter };

package/lockstep.d.ts

@@ -0,0 +1,252 @@
+//#region src/lockstep.d.ts
+/**
+ * One way to run a match in lockstep: every device runs the same game, step by
+ * step, on every player's input for that step. Optional: a game is welcome to
+ * keep its devices in step its own way.
+ *
+ * **The match is a log.** Every device in a match — the sender included —
+ * hears every message in the relay's one order, and every decision below is
+ * made from that log alone. Two devices
+ * that heard the same log run the same steps with the same inputs, whenever
+ * the messages happened to reach each of them.
+ *
+ * **Input delay, as long as the slowest needs.** Each device's input for step t
+ * is read some steps earlier, the delay, and sent, so it has time to cross the
+ * relay before anybody needs it. A step runs once every seat's input for it has
+ * come back through the log, this device's own included; until then the game
+ * waits, and catches up after. Every device times its own messages' round trip
+ * and says how many steps it needs, and every device reads with the most any
+ * playing seat needs, within the game's bounds: the same delay for everybody,
+ * so nobody's controls answer later than another's. It grows as soon as a seat
+ * needs more, and shrinks once they have all needed less for a few seconds.
+ * Where each device reads from changes nothing in the log's order, so the
+ * delay can change without the devices agreeing on when.
+ *
+ * **Seats are handed to the game, and back.** A seat whose person left the
+ * match, or went quiet for `timeoutMs` while the others waited, is dropped:
+ * from a step every device works out from the log, its input arrives as `null`,
+ * and the game plays it (its AI, or nobody). Its device, once caught up, asks
+ * for it back, and gets it from a step that, again, the log decides. A drop
+ * takes effect from the first step the seat's input is missing for in the log
+ * before the drop, and a return after the furthest step any device could have
+ * run, so no device has ever run a step the others will run differently.
+ *
+ * **Desyncs and lost devices are reported.** Every `hashEvery` steps each device
+ * that plays sends a fingerprint of its state, and a difference is reported with
+ * the step it was found at. A device whose connection dropped for a while
+ * hears what it missed once it is back, and carries on: what it sent as the
+ * connection went, and never heard come back before a later message of its
+ * own, it sends again. One that missed more than the relay still held — a gap
+ * in the relay's numbering — cannot follow the log any longer, and says so.
+ *
+ * **Rollback, optionally.** With `rollback`, a device does not wait for the
+ * others' inputs: it runs on, up to `rollback.steps` steps ahead of the log,
+ * guessing what they press from what they pressed last, and shows that. When an
+ * input comes in that differs from the guess, it puts the game back where it was
+ * before that step (`restore`) and runs the steps again, so the picture catches
+ * up with what was pressed. The delay then has only to cover the round trip
+ * beyond what guessing covers, and a player's own controls answer after a step
+ * or two whatever the connection. Only the log confirms a step, this device's
+ * own input included, so what every device agrees on, fingerprints, drops and
+ * returns, is decided as it is without rollback; a guess past a drop or a return
+ * is simply run again. Somebody who only watches runs confirmed steps alone.
+ *
+ * Messages are small: varints, inputs as the game's own bytes, `sendEvery`
+ * steps a message. A match's other messages (a game's lobby, say) share the
+ * log: tell them apart with `isLockstepMessage`.
+ *
+ * @module lockstep
+ */
+/**
+ * The first byte of every message this helper sends. A game sending messages
+ * of its own in the same match starts them with any other byte.
+ *
+ * @group Lockstep
+ */
+declare const LOCKSTEP_TAG = 245;
+/**
+ * What the helper needs of a match: `@hopple/sdk-preview-network`'s `Match` has it all.
+ *
+ * @group Lockstep
+ */
+type LockstepMatch = {
+  /** Who plays now, for noticing a seat's person has left. */
+  readonly players: readonly {
+    readonly id: string;
+  }[];
+  send(data: Uint8Array): void;
+  onMessage(listener: (data: Uint8Array, from: {
+    readonly id: string;
+  }, seq: number) => void): () => void;
+  on(listener: () => void): () => void;
+};
+/**
+ * What a game gives to run ahead of the log: a way to go back, and how far.
+ *
+ * @group Lockstep
+ */
+type Rollback<S> = {
+  /**
+   * The most steps the game may run ahead of what the log has confirmed, on
+   * guesses: the same on every device. Round trips beyond it, less a couple of
+   * steps kept for jitter, are covered by the delay. Every step ahead may be run
+   * again in a frame: it is a budget of the game's time as much as of the
+   * network's.
+   */
+  steps: number;
+  /** The game's whole state as it is now, to come back to: anything `restore` takes back. */
+  save(): S;
+  /** Put the game back as `save` found it. */
+  restore(saved: S): void;
+  /**
+   * What a seat presses at a step its input has not come in for, from the last
+   * input it is known to have pressed. That input by default: a game whose
+   * inputs say what went down this step, rather than what is held, takes that
+   * out.
+   */
+  predict?(last: Uint8Array, seat: number): Uint8Array;
+};
+/**
+ * @group Lockstep
+ */
+type LockstepOptions<S = unknown> = {
+  match: LockstepMatch;
+  /**
+   * The relay's `seq` of the message that started this run, as every device
+   * heard it. Make the run in the listener that heard it: it hears only what
+   * follows.
+   */
+  seq: number;
+  /**
+   * A number for this run, the same on every device and different from the
+   * match's other runs (a rematch is another run), so their messages are told
+   * apart.
+   */
+  run: number;
+  /** Who plays, by person id, in seat order: the same list on every device. */
+  seats: readonly string[];
+  /** This device's person id. A device whose person has no seat only watches. */
+  me: string;
+  /**
+   * Steps between reading an input and running it, as the round trips through
+   * the relay need, less what `rollback` guesses: bounds for it, the same on
+   * every device. `min` equal to `max` holds it fixed.
+   */
+  delay?: {
+    /** The least. 2 by default. */
+    min?: number;
+    /** The most. 20 by default: 333 ms at 60 steps a second. Round trips longer than it, and what guessing covers, slow the run down. */
+    max?: number;
+    /** The delay the first steps need, before any round trip is timed (guessing takes its share of it). 6 by default. */
+    start?: number;
+  };
+  /**
+   * How many players play on each seat's device, in seat order: `start.locals`
+   * from the session, the same on every device. With it, `sample` gives one
+   * input for each player on this device, `step` is given one for each player
+   * of the match (seat by seat, each seat's players in order) and `predict`'s
+   * `seat` is that player's place among them; a device's players still travel
+   * in one message. Left out, each seat is one input.
+   */
+  locals?: readonly number[];
+  /**
+   * This device's input for step `tick`: a few bytes, the game's own encoding,
+   * or with `locals` one for each of its players.
+   * Asked for each step in order: usually once a step, but several times in a
+   * frame while the delay grows, and not for a step now and then while it
+   * shrinks, so a press goes to the one call after it, whenever that comes.
+   * An empty array is what every seat presses before its first input arrives.
+   */
+  sample(tick: number): Uint8Array | readonly Uint8Array[];
+  /**
+   * Run step `tick`: each seat's input, in seat order, or `null` for a seat
+   * handed to the game; with `locals`, each player's. The same on every
+   * device once confirmed.
+   *
+   * With `rollback`, a step may be run on guesses and then `again`, after the
+   * game was put back to before it: what it played or showed the first time was
+   * played and shown, and anything that cannot be taken back (an achievement, a
+   * score, the end of the match) waits until `confirmed` has passed the step.
+   */
+  step(inputs: readonly (Uint8Array | null)[], tick: number, again: boolean): void;
+  /** A fingerprint of the game's state after a step, to compare between devices: `hash` from this package. */
+  hash?(): string;
+  /** Steps between fingerprints. 60 by default. */
+  hashEvery?: number;
+  /** Two devices' states differ after step `tick`. Said once. */
+  onDesync?(tick: number): void;
+  /** This device missed some of the match's messages and cannot follow it any longer. */
+  onLost?(): void;
+  /** How long a step is. A sixtieth of a second by default. */
+  tickMs?: number;
+  /** Steps in a message, at most. 2 by default: thirty messages a second. */
+  sendEvery?: number;
+  /** How long a seat may say nothing, while the others wait for it, before it is handed to the game. 3 s by default; `Infinity` waits for ever. */
+  timeoutMs?: number;
+  /** The most steps one `advance` runs to catch up. 30 by default. */
+  catchUp?: number;
+  /** The wall clock, in milliseconds: for timeouts and pacing, never for the game. */
+  now?: () => number;
+  /** Run ahead of the log on guesses, and back when they were wrong. Without it, every step waits for every input. */
+  rollback?: Rollback<S>;
+};
+/**
+ * A lockstep run in progress.
+ *
+ * @group Lockstep
+ */
+type Lockstep = {
+  /**
+   * Let `ms` of real time pass: run every step that is due and ready, and
+   * catch up when behind. Call it once a frame. Returns how many steps ran.
+   */
+  advance(ms: number): number;
+  /** Steps the game has run: the next step to run. Ahead of `confirmed` by the steps it guessed. */
+  readonly tick: number;
+  /** Steps the log has every input for: the same on every device, and never run again. `tick` without rollback. */
+  readonly confirmed: number;
+  /** The people the next step waits for, by id: empty when it is not waiting. */
+  readonly waiting: readonly string[];
+  /** `running`, `lost` once this device missed messages, or `stopped`. */
+  readonly status: 'running' | 'lost' | 'stopped';
+  /** Whether a seat is played by its person at the next step, rather than handed to the game. */
+  playing(seat: number): boolean;
+  /** The last round trip of this device's messages through the relay, in ms, or `null` before one. */
+  readonly rtt: number | null;
+  /** The delay inputs are read with now, in steps: at `max`, the connection is slower than the game allows. */
+  readonly delay: number;
+  /** Stop listening and running, sending what input it has read first. */
+  stop(): void;
+};
+/**
+ * Whether a match message is one of a lockstep run's, for a game's own
+ * listener to skip.
+ *
+ * @group Lockstep
+ */
+declare function isLockstepMessage(data: Uint8Array): boolean;
+/**
+ * Run a match in lockstep. See the module for how.
+ *
+ * ```ts
+ * const run = lockstep({
+ *   match, seq, run: 1, seats, me: match.me!.id,
+ *   sample: () => Uint8Array.of(pad.bits()),
+ *   step: (inputs) => world.step(inputs),
+ *   hash: () => hash(world.summary()),
+ * });
+ * sdk.loop.tick((dt) => { run.advance(dt * 1000); draw(); });
+ * ```
+ *
+ * With rollback, the game also says how to go back:
+ *
+ * ```ts
+ * rollback: { steps: 8, save: () => world.save(), restore: (saved) => world.restore(saved) },
+ * step: (inputs, tick, again) => world.step(inputs, { quiet: again }),
+ * ```
+ *
+ * @group Lockstep
+ */
+declare function lockstep<S>(options: LockstepOptions<S>): Lockstep;
+//#endregion
+export { LOCKSTEP_TAG, Lockstep, LockstepMatch, LockstepOptions, Rollback, isLockstepMessage, lockstep };