@pithy-sh/multiplayer 0.1.0

package/src/index.ts

@@ -0,0 +1,83 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The package entrypoint — the surface `pithy add multiplayer` wires into `pithy.config.ts`. Deliberately
+ * narrow: the capability factory, its config and options types, the game-model seam, and the session shapes
+ * an app renders. Every other module is imported by deep path (`@pithy-sh/multiplayer/src/...`); this is the
+ * documented contract, not a barrel over the package.
+ *
+ * **The `MultiplayerSession` Durable Object is deliberately not here.** It imports `cloudflare:workers`,
+ * which resolves in workerd and nowhere else, and this module is what an adopter's `pithy.config.ts`
+ * imports — a file loaded by every Node-side CLI command. Re-exporting the class from here put the whole
+ * Durable Object chain on that path and broke `pithy upgrade` for any project composing multiplayer (#172).
+ * The factory and the DO are two things with two runtimes, and this entry point carries only the first.
+ *
+ * The adopter's worker still exports the class, from its own module:
+ *
+ * ```ts
+ * export { MultiplayerSession } from "@pithy-sh/multiplayer/src/session/durableObject";
+ * ```
+ *
+ * — which is what wrangler's `class_name` resolves against, and `pithy add multiplayer` writes that line
+ * for you, beside the binding and the class migration tag (#428). To ship a custom game model, call
+ * `registerGameModel(myModel)` in the worker entry.
+ */
+
+export {
+  isMultiplayerCapability,
+  MULTIPLAYER_MIGRATION_ORDER,
+  MULTIPLAYER_SESSION_CLASS,
+  MULTIPLAYER_SESSION_MODULE,
+  MULTIPLAYER_SESSIONS_BINDING,
+  type MultiplayerCapability,
+  type MultiplayerOptions,
+  multiplayer,
+} from "./capability";
+export {
+  MultiplayerConfig,
+  type MultiplayerConfigInput,
+  MultiplayerGame,
+  MultiplayerLeaderboard,
+  type ResolvedGame,
+  resolveGame,
+  validateGames,
+} from "./config/config";
+export { MultiplayerResult, SessionResultStatus } from "./data/result";
+export { BUILT_IN_GAMES } from "./game/builtins";
+export type { LedgerEffect } from "./game/effects";
+// Example games, each built on a reusable pattern helper.
+export {
+  BattleConfig,
+  battleGame,
+  DefenseMove,
+  Move,
+  OffenseMove,
+  scoreBattle,
+  validateMove,
+} from "./game/games/battle";
+export { BoardState, ConnectNConfig, connectNGame, findWinner, GridMove } from "./game/games/connectN";
+export { CrapsBet, CrapsBetType, CrapsConfig, CrapsRound, crapsGame } from "./game/games/craps";
+// The game-model seam and its registry — the extension point for custom games.
+export {
+  type ApplyResult,
+  type GameContext,
+  type GameModel,
+  type ModelOutcome,
+  nextState,
+  type ResolveResult,
+  registeredKinds,
+  registerGameModel,
+  resolveModel,
+} from "./game/model";
+// The pattern helpers — layer a new game on one of these.
+export { type SimultaneousSpec, simultaneous } from "./game/patterns/simultaneous";
+export { type TurnBasedSpec, turnBased } from "./game/patterns/turnBased";
+export {
+  type BetDecision,
+  type PendingBet,
+  type WageringTableSpec,
+  wageringTable,
+} from "./game/patterns/wageringTable";
+export { createRngState, type RandomSource, RngState, randomSource } from "./game/random";
+export { GameSnapshot, isTerminal, type SessionOutcome, SessionPhase, SessionView } from "./session/state";

package/src/migrations/0001_results.ts

@@ -0,0 +1,52 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Kysely } from "kysely";
+import type { Migration } from "kysely/migration";
+
+/**
+ * The multiplayer results table — the durable record a terminal session writes.
+ *
+ * camelCase identifiers; `CamelCasePlugin` snake-cases them in the DDL. `down` is the tested inverse.
+ *
+ * There is no session/membership/commit table on purpose: live session state lives in the Durable
+ * Object's own storage, which is where authority and hidden state belong. D1 holds only what must outlive
+ * the object and be queryable beside the adopter's tables — the result.
+ */
+export const multiplayer_0001_results: Migration = {
+  up: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema
+      .createTable("pithyMultiplayerResults")
+      // Plain INTEGER PRIMARY KEY (a rowid alias), not autoincrement — the id is internal and never
+      // exposed, so the never-reuse-a-deleted-id guarantee autoincrement adds is not worth its cost.
+      .addColumn("id", "integer", (c) => c.primaryKey())
+      .addColumn("sessionId", "text", (c) => c.notNull().unique())
+      .addColumn("gameKey", "text", (c) => c.notNull())
+      .addColumn("status", "text", (c) => c.notNull())
+      .addColumn("players", "text", (c) => c.notNull())
+      .addColumn("scores", "text")
+      .addColumn("winnerUserId", "text")
+      .addColumn("draw", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .addColumn("resolvedAt", "integer", (c) => c.notNull())
+      .execute();
+
+    // Results are browsed by game ("recent battles") and by winner ("this player's wins"), so both get an
+    // index. The unique constraint on sessionId already covers by-session lookups.
+    await db.schema
+      .createIndex("pithyMultiplayerResultsGameIdx")
+      .on("pithyMultiplayerResults")
+      .columns(["gameKey", "resolvedAt"])
+      .execute();
+    await db.schema
+      .createIndex("pithyMultiplayerResultsWinnerIdx")
+      .on("pithyMultiplayerResults")
+      .columns(["winnerUserId"])
+      .execute();
+  },
+  down: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema.dropIndex("pithyMultiplayerResultsWinnerIdx").execute();
+    await db.schema.dropIndex("pithyMultiplayerResultsGameIdx").execute();
+    await db.schema.dropTable("pithyMultiplayerResults").execute();
+  },
+};

package/src/publish/leaderboard.ts

@@ -0,0 +1,59 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { LeaderboardBoard } from "@pithy-sh/leaderboard/src/config/config";
+import { leaderboardDatabase } from "@pithy-sh/leaderboard/src/data/tables";
+import { entryStore } from "@pithy-sh/leaderboard/src/entry/store";
+import { ALL_TIME_WINDOW, windowKeyAt } from "@pithy-sh/leaderboard/src/window/schedule";
+import type { MultiplayerLeaderboard } from "../config/config";
+
+/** What resolution hands the publisher — who played, who won, and when. */
+export interface PublishInput {
+  /** The session's members, in join order. */
+  members: readonly string[];
+  /** The winner's user id, or null on a draw. */
+  winnerUserId: string | null;
+  /** Whether the session was a draw. */
+  draw: boolean;
+  /** When the session resolved — the instant the window is computed from and the score is stamped with. */
+  at: Date;
+}
+
+/**
+ * Publish a resolved session's result to a `@pithy-sh/leaderboard` board — one-way, and only ever loaded
+ * by dynamic import from the DO so leaderboard stays an optional peer.
+ *
+ * This is the composition seam the capability exists to demonstrate: a session's authority ends at its
+ * result, and that result flows *into* the leaderboard's own submit path — the same `INSERT … ON CONFLICT`
+ * upsert a score submission uses — rather than reimplementing ranking. Leaderboard never depends on
+ * multiplayer; the arrow runs one direction only.
+ *
+ * The board's coordinates (direction, aggregation, window) are carried on the game's `leaderboard` config
+ * and must match the leaderboard board's own definition — they decide how the awarded points fold in. A
+ * points board is `sum`/`desc` by default: each session adds the winner's, loser's, or draw points to a
+ * running total.
+ */
+export async function publishResultToLeaderboard(
+  d1: D1Database,
+  config: MultiplayerLeaderboard,
+  input: PublishInput,
+): Promise<void> {
+  const board = LeaderboardBoard.parse({
+    key: config.board,
+    direction: config.direction,
+    aggregation: config.aggregation,
+    window: config.window,
+  });
+  const windowKey = config.window ? windowKeyAt(config.window, input.at) : ALL_TIME_WINDOW;
+  const store = entryStore(leaderboardDatabase(d1));
+
+  for (const userId of input.members) {
+    const points = input.draw
+      ? config.points.draw
+      : userId === input.winnerUserId
+        ? config.points.win
+        : config.points.loss;
+    await store.submit(board, windowKey, userId, points, input.at, true);
+  }
+}

package/src/seeds/example.ts

@@ -0,0 +1,54 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { EXAMPLE_ADA, EXAMPLE_ALAN, EXAMPLE_GRACE } from "@pithy-sh/core/src/seed/exampleIdentities";
+import { d1SeedGroup, defineSeed, type SeedSet } from "@pithy-sh/core/src/seed/seed";
+import { MultiplayerResult } from "../data/result";
+import { MULTIPLAYER_RESULTS_TABLE } from "../data/tables";
+
+/**
+ * Where the example set sorts among the whole project's seed registry. It runs after `auth` (100),
+ * whose example seeds the users this result belongs to, so the owning identities exist first — the
+ * order encodes that dependency, exactly like the migration registry. It sits after leaderboard's own
+ * example (200), matching migration order (multiplayer sits after leaderboard, at 500). It need not
+ * line up with {@link MULTIPLAYER_MIGRATION_ORDER} (a different registry, composed separately by
+ * `pithy seed`).
+ */
+const MULTIPLAYER_EXAMPLE_SEED_ORDER = 300;
+
+const now = () => new Date();
+
+/**
+ * A single resolved demo match: Ada wins a `demo` session over Grace and Alan — the same shared cast
+ * `auth` seeds and `leaderboard`/`ledger` also reference. The row is authored as the durable *result*
+ * a session writes once it reaches its terminal state — the natural shape `pithy_multiplayer_results`
+ * stores, not a live session (which lives only in the Durable Object while play is underway). Composed
+ * in only when the project turns on `seed.includeExamples` (`pithy.config.ts`), and only for `dev` and
+ * `staging` — an example fixture never targets production, regardless of that setting.
+ */
+export const multiplayerExampleSeed: SeedSet = defineSeed({
+  name: "example",
+  order: MULTIPLAYER_EXAMPLE_SEED_ORDER,
+  environments: ["dev", "staging"],
+  example: true,
+  d1: [
+    d1SeedGroup("app", MULTIPLAYER_RESULTS_TABLE, MultiplayerResult, [
+      {
+        id: 1,
+        sessionId: "example000000000000000000000001",
+        gameKey: "demo",
+        status: "resolved",
+        players: [EXAMPLE_ADA.id, EXAMPLE_GRACE.id, EXAMPLE_ALAN.id],
+        scores: {
+          [EXAMPLE_ADA.id]: 300,
+          [EXAMPLE_GRACE.id]: 250,
+          [EXAMPLE_ALAN.id]: 200,
+        },
+        winnerUserId: EXAMPLE_ADA.id,
+        draw: false,
+        createdAt: now(),
+        resolvedAt: now(),
+      },
+    ]),
+  ],
+});