eric/game-kit
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Table options: the host's choices when opening a table, declared by the game, recorded on the room line

Browse Source 
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Jm2auWk6RP71CjaAb4FMoG
This commit is contained in:
Eric Wagoner
2026-09-23 12:45:42 -04:00
co-authored by Claude Fable 5.1
parent 2ab6dc4b5f
commit 63bd154798
10 changed files with 89 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONVENTIONS.md
+5
View File
@@ -64,6 +64,11 @@ README.
where the keeper roosts. It lives in the about panel; the colophons, the
rules page and the guide each carry a one-line mail link.
- **Table options** are the host's choices when opening a table (a
variant, a side, a length): the game declares them in `GameSpec.options`,
the hall renders them as selects, the room line records them, and
`create` receives them. A game with one way to play declares none.
## The engine
- Pure and deterministic: `create(names, seed, rules)` and
template/server/src/index.ts
+2 -2
View File
@@ -1,7 +1,7 @@
// The front door for games between people. Plain HTTP for actions, a
// websocket only to say "something changed, fetch the view again".
//
// POST /api/rooms {name, size?} create a room and take seat A
// POST /api/rooms {name, size?, options?} create a room and take seat A; options are the game's table choices
// POST /api/rooms/:id/join {name} take the next seat
// POST /api/rooms/:id/bot {token} the host seats a bot, before the game begins
// POST /api/rooms/:id/begin {token} the host begins with the players seated so far
@@ -188,7 +188,7 @@ async function handle(req: IncomingMessage, res: ServerResponse): Promise<void>
if (parts.length === 2 && req.method === 'POST') {
if (!doors.allow(clientOf(req))) throw new RoomError('Too many rooms opened from here just now; try again later.', 429);
const body = await readBody(req);
const { room, seat, token } = rooms.create(String(body.name ?? ''), Number(body.size ?? game.minSeats));
const { room, seat, token } = rooms.create(String(body.name ?? ''), Number(body.size ?? game.minSeats), body.options);
return send(res, 201, { seat: seat.id, token, view: rooms.view(room, seat.id) });
}
template/server/src/rooms.ts
+25 -11
View File
@@ -5,7 +5,7 @@
// game beyond the GameSpec it is given.
import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
import { SPECTATOR, type GameSpec, type SeatId } from '../../src/lib/game/spec';
import { SPECTATOR, type GameSpec, type SeatId, type TableOptions } from '../../src/lib/game/spec';
import type { ChatLine, RoomView } from '../../src/lib/net/view';
import type { LedgerLine, Store } from './store';
@@ -41,6 +41,8 @@ export interface Room<State> {
rematch: { to: string; by: SeatId } | null;
/** The table this one is the rematch of. */
rematchOf: string | null;
/** The host's choices for this table, every declared option filled. */
options: TableOptions;
state: State | null;
/** Inputs received for the round in progress, by seat. */
pending: Record<SeatId, unknown>;
@@ -158,26 +160,37 @@ export class Rooms<State, Input> {
return seat;
}
create(name: string, size: number): { room: Room<State>; seat: Seat; token: string } {
create(name: string, size: number, rawOptions?: unknown): { room: Room<State>; seat: Seat; token: string } {
const { minSeats } = this.game;
if (!Number.isInteger(size) || size < minSeats || size > this.maxSeats) {
throw new RoomError(`A table seats ${minSeats} to ${this.maxSeats} players.`);
}
return this.open(name, size);
return this.open(name, size, this.cleanOptions(rawOptions));
}
/** The host's choices, kept to the options the game declares and the choices it offers; the rest default. */
private cleanOptions(raw: unknown): TableOptions {
const given = (typeof raw === 'object' && raw !== null ? raw : {}) as Record<string, unknown>;
const options: TableOptions = {};
for (const o of this.game.options ?? []) {
const v = given[o.key];
options[o.key] = typeof v === 'string' && o.choices.some((c) => c.value === v) ? v : o.default;
}
return options;
}
/** A table with nobody seated yet. */
private blank(id: string, size: number, createdAt: number, rematchOf: string | null, expected: string[], seq = 0): Room<State> {
return { id, size, createdAt, seats: [], galleryTalk: false, challenge: null, expected, rematch: null, rematchOf, state: null, pending: {}, chat: [], seq, updatedAt: createdAt };
private blank(id: string, size: number, createdAt: number, rematchOf: string | null, expected: string[], options: TableOptions, seq = 0): Room<State> {
return { id, size, createdAt, seats: [], galleryTalk: false, challenge: null, expected, rematch: null, rematchOf, options, state: null, pending: {}, chat: [], seq, updatedAt: createdAt };
}
/** Open a table with its first seat taken; a rematch names the table it follows and holds seats for its players. */
private open(name: string, size: number, follows?: { rematchOf: string; expected: string[] }): { room: Room<State>; seat: Seat; token: string } {
private open(name: string, size: number, options: TableOptions, follows?: { rematchOf: string; expected: string[] }): { room: Room<State>; seat: Seat; token: string } {
let id = newCode();
while (this.rooms.has(id) || this.store.exists(id)) id = newCode();
const room = this.blank(id, size, Date.now(), follows?.rematchOf ?? null, follows?.expected ?? []);
const room = this.blank(id, size, Date.now(), follows?.rematchOf ?? null, follows?.expected ?? [], options);
this.rooms.set(id, room);
this.commit(room, { t: 'room', id, seats: size, createdAt: room.createdAt, ...(follows ? { rematchOf: follows.rematchOf, expected: follows.expected } : {}) });
this.commit(room, { t: 'room', id, seats: size, createdAt: room.createdAt, options, ...(follows ? { rematchOf: follows.rematchOf, expected: follows.expected } : {}) });
return { room, ...this.sit(room, name, false) };
}
@@ -232,7 +245,7 @@ export class Rooms<State, Input> {
if (!room.state || !this.game.over(room.state)) throw new RoomError('The game is not over yet.', 409);
if (room.rematch) return { roomId: room.rematch.to, seat: null, token: null, created: false };
const others = room.seats.filter((s) => !s.bot && s.id !== caller.id).map((s) => s.name);
const next = this.open(caller.name, room.size, { rematchOf: room.id, expected: others });
const next = this.open(caller.name, room.size, room.options, { rematchOf: room.id, expected: others });
for (const bot of room.seats.filter((s) => s.bot)) this.sit(next.room, bot.name, true);
this.commit(room, { t: 'rematch', at: Date.now(), to: next.room.id, by: caller.id });
return { roomId: next.room.id, seat: next.seat, token: next.token, created: true };
@@ -397,6 +410,7 @@ export class Rooms<State, Input> {
expected: this.awaited(room),
rematch: room.rematch,
rematchOf: room.rematchOf,
options: room.options,
keeper: this.keeper.name,
keeperZone: this.keeper.zone
};
@@ -464,7 +478,7 @@ export class Rooms<State, Input> {
room.seats = room.seats.filter((s) => s.id !== line.id);
break;
case 'start':
room.state = this.game.create(Object.fromEntries(room.seats.map((s) => [s.id, s.name])), line.seed, line.rules ?? 1);
room.state = this.game.create(Object.fromEntries(room.seats.map((s) => [s.id, s.name])), line.seed, line.rules ?? 1, room.options);
break;
case 'turn':
if (!room.state) return;
@@ -481,7 +495,7 @@ export class Rooms<State, Input> {
private replay(id: string, lines: LedgerLine[]): Room<State> | null {
const first = lines[0];
if (!first || first.t !== 'room') return null;
const room = this.blank(id, first.seats, first.createdAt, first.rematchOf ?? null, first.expected ?? [], lines.length);
const room = this.blank(id, first.seats, first.createdAt, first.rematchOf ?? null, first.expected ?? [], this.cleanOptions(first.options), lines.length);
for (const line of lines) {
this.apply(room, line);
if (line.t === 'turn' || line.t === 'input') room.updatedAt = line.at;
template/server/src/store.ts
+1 -1
View File
@@ -8,7 +8,7 @@ import type { SeatId } from '../../src/lib/game/spec';
export type LedgerLine =
/** `rematchOf` and `expected` mark a table opened for a rematch: whose it follows, and whose seats are held. */
| { t: 'room'; id: string; seats: number; createdAt: number; rematchOf?: string; expected?: string[] }
| { t: 'room'; id: string; seats: number; createdAt: number; rematchOf?: string; expected?: string[]; options?: Record<string, string> }
/** A seat holds only the hash of its token; the token itself goes once to the browser that earned it. Ledgers written before hashing carry `token` and are read once more. */
| { t: 'seat'; id: SeatId; name: string; tokenHash?: string; token?: string; bot: boolean }
/** One seat's move for the round in progress, so a restart keeps it. The turn line that follows carries every input again. */
template/src/lib/components/Hall.svelte
+29 -2
View File
@@ -13,6 +13,8 @@
let name = $state(playerName());
let code = $state('');
/** The host's choices for the next table, from the game's declared options. */
let options = $state<Record<string, string>>(Object.fromEntries((game.options ?? []).map((o) => [o.key, o.default])));
let busy = $state(false);
let error = $state('');
let seats = $state(allSeats());
@@ -157,9 +159,21 @@
<span>Your name</span>
<input type="text" bind:value={name} maxlength={NAME_MAX} placeholder="e.g. Morwenna" autocomplete="nickname" />
</label>
<button type="button" class="commit primary" disabled={!ready || busy} onclick={() => open(() => Room.createWithBot(name.trim()))}>Play now against the bot</button>
{#if game.options?.length}
<div class="options">
{#each game.options as o (o.key)}
<label class="option">
<span>{o.label}</span>
<select bind:value={options[o.key]}>
{#each o.choices as c (c.value)}<option value={c.value}>{c.label}</option>{/each}
</select>
</label>
{/each}
</div>
{/if}
<button type="button" class="commit primary" disabled={!ready || busy} onclick={() => open(() => Room.createWithBot(name.trim(), options))}>Play now against the bot</button>
<div class="ways">
<button type="button" class="quiet" disabled={!ready || busy} onclick={() => open(() => Room.create(name.trim(), game.seatIds.length))}>Open a table</button>
<button type="button" class="quiet" disabled={!ready || busy} onclick={() => open(() => Room.create(name.trim(), game.seatIds.length, options))}>Open a table</button>
<form class="joinform" onsubmit={join}>
<span class="or">or join one</span>
<input type="text" class="code" bind:value={code} maxlength="4" placeholder="CODE" autocapitalize="characters" autocomplete="off" aria-label="room code" />
@@ -551,4 +565,17 @@
.family li + li {
margin-top: 0.3rem;
}
.options {
display: flex;
flex-wrap: wrap;
gap: 0.5rem 1.2rem;
margin: 0.2rem 0 0.6rem;
}
.option {
display: flex;
align-items: center;
gap: 0.5rem;
font-size: 0.9rem;
}
</style>
template/src/lib/game/index.ts
+2 -2
View File
@@ -5,7 +5,7 @@
// withholds the round in progress, and a rules revision. Replace this file
// with your own game and keep the GameSpec shape.
import { SPECTATOR, type GameSpec, type Outcome, type SeatId } from './spec';
import { SPECTATOR, type GameSpec, type Outcome, type SeatId, type TableOptions } from './spec';
export const CURRENT_RULES = 1;
export const TARGET = 3;
@@ -41,7 +41,7 @@ function random(seed: number): number {
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
}
export function createGame(names: Record<SeatId, string>, seed = Date.now(), rules = CURRENT_RULES): State {
export function createGame(names: Record<SeatId, string>, seed = Date.now(), rules = CURRENT_RULES, _options?: TableOptions): State {
const seats = Object.keys(names);
return {
rules,
template/src/lib/game/spec.ts
+15 -1
View File
@@ -21,9 +21,23 @@ export interface Outcome {
reason: string;
}
/** A choice the host makes when opening a table: a variant, a side, a length. */
export interface TableOption {
key: string;
label: string;
choices: { value: string; label: string }[];
/** The value a table gets when the host chooses nothing. */
default: string;
}
/** The host's choices for a table, by option key; only keys the game declares get through. */
export type TableOptions = Record<string, string>;
export interface GameSpec<State, Input> {
/** Seats in table order; the table takes at most this many. */
seatIds: SeatId[];
/** What the host may choose when opening a table; empty for a game with one way to play. */
options?: TableOption[];
minSeats: number;
/** Names the server draws for bots, in preference order. */
botNames: string[];
@@ -35,7 +49,7 @@ export interface GameSpec<State, Input> {
*/
currentRules: number;
create(names: Record<SeatId, string>, seed: number, rules: number): State;
create(names: Record<SeatId, string>, seed: number, rules: number, options?: TableOptions): State;
/** Resolve one round. Must be a pure function of its arguments: the ledger is replayed through it. */
resolve(state: State, inputs: Record<SeatId, Input>): State;
/** Whether this seat's input is needed before the next resolution. */
template/src/lib/net/client.ts
+2 -2
View File
@@ -1,7 +1,7 @@
// The browser's side of the game server: a few JSON calls, and the seats this
// browser holds, remembered so a shared link never has to carry a token.
import type { SeatId } from '$lib/game/spec';
import type { SeatId, TableOptions } from '$lib/game/spec';
import type { RoomView } from './view';
export interface HeldSeat {
@@ -132,7 +132,7 @@ export function makeApi<State, Input>() {
type Seated = { seat: SeatId; token: string; view: RoomView<State> };
type View = RoomView<State>;
return {
create: (name: string, size: number) => call<Seated>('POST', '/api/rooms', { name, size }),
create: (name: string, size: number, options?: TableOptions) => call<Seated>('POST', '/api/rooms', { name, size, options }),
join: (roomId: string, name: string) => call<Seated>('POST', `/api/rooms/${roomId}/join`, { name }),
addBot: (roomId: string, token: string) => call<View>('POST', `/api/rooms/${roomId}/bot`, { token }),
begin: (roomId: string, token: string) => call<View>('POST', `/api/rooms/${roomId}/begin`, { token }),
template/src/lib/net/room.svelte.ts
+5 -5
View File
@@ -3,7 +3,7 @@
// through GameSpec; a game's own store wraps or extends this one.
import { game } from '$lib/game';
import { SPECTATOR, type SeatId } from '$lib/game/spec';
import { SPECTATOR, type SeatId, type TableOptions } from '$lib/game/spec';
import type { Input, State } from '$lib/game';
import { makeApi, rememberSeat, watchRoom, type HeldSeat } from './client';
import { markTalkSeen } from './talk';
@@ -152,15 +152,15 @@ export class Room {
}
/** Open a table on the server, seated as its host; it begins when the host says. */
static async create(name: string, size: number): Promise<Room> {
const seated = await api.create(name, size);
static async create(name: string, size: number, options?: TableOptions): Promise<Room> {
const seated = await api.create(name, size, options);
rememberSeat(seated.view.roomId, { seat: seated.seat, token: seated.token });
return new Room(seated.view, seated.token);
}
/** A room with a bot seated and the game begun, so a solo game is a ledger like any other. */
static async createWithBot(name: string): Promise<Room> {
const seated = await api.create(name, 2);
static async createWithBot(name: string, options?: TableOptions): Promise<Room> {
const seated = await api.create(name, 2, options);
rememberSeat(seated.view.roomId, { seat: seated.seat, token: seated.token });
await api.addBot(seated.view.roomId, seated.token);
return new Room(await api.begin(seated.view.roomId, seated.token), seated.token);
template/src/lib/net/view.ts
+3 -1
View File
@@ -1,7 +1,7 @@
// What the server tells a viewer about a room. The game's own state is
// whatever GameSpec.view returned for that viewer; nothing else leaves.
import type { Outcome, SeatId } from '../game/spec';
import type { Outcome, SeatId, TableOptions } from '../game/spec';
/** One line of table talk: from a seat, or from the Peanut Gallery when the host allows it (id SPECTATOR, signed with `name`). */
export interface ChatLine {
@@ -40,6 +40,8 @@ export interface RoomView<State> {
rematch: { to: string; by: SeatId } | null;
/** The table this one is the rematch of. */
rematchOf: string | null;
/** The host's choices for this table, every declared option filled. */
options: TableOptions;
/** The keeper of the site, and where they live, for a table that calls them. */
keeper: string;
keeperZone: string;