@flayerlabs/gamemode-spec 0.1.0

package/src/live.ts

@@ -0,0 +1,173 @@
+import type { PlayerId } from './index.js';
+
+/** Static launch facts that are safe for every game and spectator to render. */
+export interface LaunchContext {
+  readonly roundId: string;
+  readonly poolId: string;
+  readonly coinAddress: string | null;
+  readonly name: string;
+  readonly symbol: string;
+  readonly imageUrl: string | null;
+  readonly opensAt: number;
+  readonly closesAt: number;
+  /** The chart/standings settlement tail may outlive gameplay and claim issuance. */
+  readonly booksCloseAt: number;
+}
+
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+
+/** Check an untrusted launch response before using it to choose a room or trusted service. */
+export function isLaunchContext(input: unknown): input is LaunchContext {
+  if (typeof input !== 'object' || input === null) return false;
+  const value = input as Record<string, unknown>;
+  return (
+    typeof value.roundId === 'string' &&
+    value.roundId.length > 0 &&
+    value.roundId.length <= 128 &&
+    typeof value.poolId === 'string' &&
+    value.poolId.length > 0 &&
+    value.poolId.length <= 128 &&
+    (value.coinAddress === null || (typeof value.coinAddress === 'string' && ADDRESS.test(value.coinAddress))) &&
+    typeof value.name === 'string' &&
+    value.name.length <= 256 &&
+    typeof value.symbol === 'string' &&
+    value.symbol.length <= 64 &&
+    (value.imageUrl === null || (typeof value.imageUrl === 'string' && value.imageUrl.length <= 2_048)) &&
+    Number.isSafeInteger(value.opensAt) &&
+    Number.isSafeInteger(value.closesAt) &&
+    Number.isSafeInteger(value.booksCloseAt) &&
+    (value.opensAt as number) < (value.closesAt as number) &&
+    (value.closesAt as number) <= (value.booksCloseAt as number)
+  );
+}
+
+export type ConnectionState = 'connecting' | 'connected' | 'reconnecting' | 'superseded' | 'ended';
+
+/**
+ * Who is currently connected. Telemetry, and deliberately nothing more.
+ *
+ * This carries no readiness, because the platform has no opinion about what "ready" means. A game
+ * that gates its lobby on players being ready defines a ready Action of its own: it then travels
+ * the same authenticated, ordered, persisted path as every other action and arrives in `decide()`,
+ * where it can actually change the round.
+ *
+ * Readiness modelled here instead was a rule the rules module could not see. It could not be
+ * replayed, it could not decide anything, and it imposed one lobby policy on every kind of game —
+ * a live quiz, a shooter and a turn-based game do not agree about when to start, and should not
+ * have to.
+ */
+export interface PresenceState {
+  connectedCount: number;
+}
+
+export interface PlayerIdentity {
+  player: PlayerId;
+  displayName: string | null;
+  avatarUrl: string | null;
+}
+
+export interface Reaction {
+  player: PlayerId;
+  id: string;
+}
+
+export interface MarketPrice {
+  at: number;
+  /** Display price of one whole coin in ETH. Market data never participates in scoring. */
+  priceEth: number;
+}
+
+export interface MarketTrade {
+  /** Stable across reconnects, normally transaction hash plus log index. */
+  id: string;
+  at: number;
+  player: PlayerId | null;
+  side: 'buy' | 'sell';
+  spendWei: bigint;
+  priceEth: number | null;
+  transactionHash?: string;
+}
+
+export interface MarketState {
+  status: 'unavailable' | 'loading' | 'live' | 'stale';
+  prices: readonly MarketPrice[];
+  trades: readonly MarketTrade[];
+  marketCapUsd: number | null;
+}
+
+export interface WireMarketTrade extends Omit<MarketTrade, 'spendWei'> {
+  spendWei: string;
+}
+
+export interface WireMarketState extends Omit<MarketState, 'trades'> {
+  trades: readonly WireMarketTrade[];
+}
+
+/** Authoritative ledger state. A signed but unsettled authorisation remains held. */
+export interface EconomyBalance {
+  /** Immutable entitlement rate for this round. This is wei, not a live dollar quote. */
+  weiPerPoint: bigint;
+  earnedWei: bigint;
+  heldWei: bigint;
+  spentWei: bigint;
+  availableWei: bigint;
+  /**
+   * When the earliest outstanding hold expires, in epoch ms, or null when nothing is held.
+   *
+   * A player who opens the buy dialog and then declines keeps that allowance held until this
+   * passes, which is correct — the authorisation is still live and could still be spent. But
+   * without the deadline on the balance, a game cannot explain the gap between what a player
+   * earned and what they can spend, so it either tracks the deadline itself or shows a number
+   * that is wrong for five minutes.
+   */
+  holdExpiresAt: number | null;
+}
+
+/** Stable player-facing reasons a platform buy did not happen. */
+export type BuyFailure =
+  | 'nothing-to-spend'
+  | 'declined'
+  | 'not-enough-for-fees'
+  | 'window-closed'
+  | 'try-again';
+
+/**
+ * JSON-safe form used on the wire.
+ *
+ * The wei fields cross as decimal strings because JSON has no bigint. `holdExpiresAt` is an
+ * ordinary millisecond number and stays one.
+ */
+export type WireEconomyBalance = {
+  [Key in keyof Omit<EconomyBalance, 'holdExpiresAt'>]: string;
+} & { holdExpiresAt: number | null };
+
+/** Keep cosmetic reaction identifiers bounded and safe to use as asset keys. */
+export function isReactionId(id: string): boolean {
+  return /^[A-Za-z0-9._:-]{1,64}$/.test(id);
+}
+
+export const LIVE_PROTOCOL_VERSION = 1 as const;
+
+export type LiveServerFrame<PublicView, PlayerView> =
+  | {
+      v: typeof LIVE_PROTOCOL_VERSION;
+      type: 'snapshot';
+      sequence: number;
+      now: number;
+      view: PublicView;
+      you: PlayerView | null;
+      economy: WireEconomyBalance;
+      launch: LaunchContext;
+      presence: PresenceState;
+    }
+  | { v: typeof LIVE_PROTOCOL_VERSION; type: 'reaction'; reaction: Reaction }
+  | { v: typeof LIVE_PROTOCOL_VERSION; type: 'market'; market: WireMarketState }
+  | { v: typeof LIVE_PROTOCOL_VERSION; type: 'presence'; presence: PresenceState };
+
+/**
+ * Everything a client may say over the socket.
+ *
+ * Reactions only. Actions go over HTTP so they are ordered and persisted with the round, and
+ * readiness is an ordinary action for whichever games want one.
+ */
+export type LiveClientFrame = { v: typeof LIVE_PROTOCOL_VERSION; type: 'reaction'; id: string };

package/src/round.ts

@@ -0,0 +1,141 @@
+import type { Award, Command, Decision, GameModule, PlayerId, Refusal, RoundWindow } from './index.js';
+import { isRefusal } from './index.js';
+
+/**
+ * Drives a game module through commands. Pure, in-memory, no I/O.
+ *
+ * This is the only implementation of "how to run a round". The server persists around it and the
+ * browser mock runs it directly, so a game cannot behave one way offline and another way live —
+ * there is no second copy to drift. The reference games this platform replaces had exactly that
+ * bug: two copies of the same scoring rules, disagreeing about a constant, with the mechanism
+ * meant to pin them not covering the part that moved.
+ *
+ * Ordering is the platform's job, not the game's: commands are applied one at a time, in the
+ * order they arrive here.
+ */
+export class Round<Config, State, Event, Action, PublicView, PlayerView> {
+  private readonly points = new Map<PlayerId, number>();
+
+  /**
+   * @param onAward Called for every award as it happens, including ones produced by a wake that
+   * `send` ran on the way to a command. A durable caller needs this: it has to write the state and
+   * the money in one transaction, and it cannot see inside a wake any other way.
+   */
+  private constructor(
+    private readonly game: GameModule<Config, State, Event, Action, PublicView, PlayerView>,
+    private state: State,
+    readonly window: RoundWindow,
+    private readonly onAward?: (award: Award) => void,
+  ) {}
+
+  /** Begin a new round. */
+  static start<Config, State, Event, Action, PublicView, PlayerView>(
+    game: GameModule<Config, State, Event, Action, PublicView, PlayerView>,
+    config: Config,
+    seed: number,
+    window: RoundWindow,
+    onAward?: (award: Award) => void,
+  ): Round<Config, State, Event, Action, PublicView, PlayerView> {
+    return new Round(game, game.initRound(config, seed, window), window, onAward);
+  }
+
+  /**
+   * Pick a round back up from a stored state.
+   *
+   * Nothing is replayed and nothing recomputed: the state is the game's own and the platform never
+   * inspects it, so resuming is a straight substitution. That is what makes a restart cheap.
+   */
+  static resume<Config, State, Event, Action, PublicView, PlayerView>(
+    game: GameModule<Config, State, Event, Action, PublicView, PlayerView>,
+    state: State,
+    window: RoundWindow,
+    onAward?: (award: Award) => void,
+  ): Round<Config, State, Event, Action, PublicView, PlayerView> {
+    return new Round(game, state, window, onAward);
+  }
+
+  /**
+   * Apply one command. Fires any wakes that fall due at or before it first, so a game never sees
+   * an action from after a deadline it asked to be woken for.
+   */
+  send(command: Command<Action>): Decision<Event> | Refusal {
+    this.runWakesUpTo(command.at);
+    return this.apply(command);
+  }
+
+  /**
+   * Fire every wake due at or before `time`, and report how many fired.
+   *
+   * The count is what a durable caller needs: zero means nothing changed and there is nothing to
+   * write. Never send a wake through {@link send} to achieve this — `send` runs due wakes on the
+   * way to the command, so a synthetic wake command fires the same deadline twice and collapses
+   * whatever phase sat between them.
+   */
+  advanceTo(time: number): number {
+    return this.runWakesUpTo(time);
+  }
+
+  private runWakesUpTo(time: number): number {
+    // A wake may schedule the next one. Bounded by each wake having to move strictly forward.
+    let previous = -Infinity;
+    let fired = 0;
+    for (;;) {
+      const at = this.game.nextWakeAt(this.state);
+      if (at === null) return fired;
+      if (!Number.isFinite(at)) {
+        throw new Error(`${this.game.id}: nextWakeAt returned a non-finite time`);
+      }
+      if (!Number.isSafeInteger(at)) {
+        throw new Error(`${this.game.id}: nextWakeAt returned a non-safe-integer time`);
+      }
+      if (at > this.window.closesAt) {
+        throw new Error(`${this.game.id}: nextWakeAt ${at} is after the round closes at ${this.window.closesAt}`);
+      }
+      if (at > time) return fired;
+      if (at <= previous) {
+        throw new Error(`${this.game.id}: nextWakeAt did not advance past ${at}`);
+      }
+      previous = at;
+      this.apply({ kind: 'wake', at });
+      fired += 1;
+    }
+  }
+
+  private apply(command: Command<Action>): Decision<Event> | Refusal {
+    const result = this.game.decide(this.state, command);
+    if (isRefusal(result)) return result;
+
+    for (const event of result.events) {
+      this.state = this.game.evolve(this.state, event);
+    }
+    for (const award of result.awards ?? []) {
+      this.credit(award);
+    }
+    return result;
+  }
+
+  private credit(award: Award): void {
+    if (!Number.isFinite(award.points) || award.points < 0) {
+      throw new Error(`${this.game.id}: award of ${award.points} points to ${award.player}`);
+    }
+    this.points.set(award.player, (this.points.get(award.player) ?? 0) + award.points);
+    this.onAward?.(award);
+  }
+
+  pointsFor(player: PlayerId): number {
+    return this.points.get(player) ?? 0;
+  }
+
+  publicView(): PublicView {
+    return this.game.publicView(this.state);
+  }
+
+  playerView(player: PlayerId): PlayerView {
+    return this.game.playerView(this.state, player);
+  }
+
+  /** For replay assertions. Structural equality of this is what determinism means. */
+  snapshot(): State {
+    return this.state;
+  }
+}

package/src/schedule.ts

@@ -0,0 +1,58 @@
+import type { RoundWindow } from './index.js';
+
+export interface ScheduleStep<Value> {
+  value: Value;
+  durationMs: number;
+}
+
+export interface ScheduledStep<Value> {
+  value: Value;
+  startsAt: number;
+  endsAt: number;
+}
+
+export class ScheduleWindowError extends RangeError {
+  constructor(readonly requiredMs: number, readonly availableMs: number) {
+    super(`schedule needs ${requiredMs}ms but the round window has ${availableMs}ms`);
+    this.name = 'ScheduleWindowError';
+  }
+}
+
+/** Turn relative authored durations into the absolute timestamps a round can replay forever. */
+export function scheduleWithin<Value>(
+  window: RoundWindow,
+  steps: readonly ScheduleStep<Value>[],
+): ScheduledStep<Value>[] {
+  if (
+    !Number.isSafeInteger(window.opensAt) ||
+    !Number.isSafeInteger(window.closesAt) ||
+    window.closesAt <= window.opensAt
+  ) {
+    throw new RangeError('schedule needs safe-integer timestamps whose close is after its open');
+  }
+  const availableMs = window.closesAt - window.opensAt;
+  if (!Number.isSafeInteger(availableMs)) {
+    throw new RangeError('schedule round-window duration is outside the safe-integer range');
+  }
+  let cursor = window.opensAt;
+  const scheduled = steps.map((step, index) => {
+    if (!Number.isSafeInteger(step.durationMs) || step.durationMs <= 0) {
+      throw new RangeError(`schedule phase ${index} must have a positive safe-integer duration`);
+    }
+    const endsAt = cursor + step.durationMs;
+    if (!Number.isSafeInteger(endsAt)) {
+      throw new RangeError(`schedule phase ${index} ends outside the safe-integer timestamp range`);
+    }
+    const scheduledStep = { value: step.value, startsAt: cursor, endsAt };
+    cursor = scheduledStep.endsAt;
+    return scheduledStep;
+  });
+  if (cursor > window.closesAt) {
+    const requiredMs = cursor - window.opensAt;
+    if (!Number.isSafeInteger(requiredMs)) {
+      throw new RangeError('schedule duration is outside the safe-integer range');
+    }
+    throw new ScheduleWindowError(requiredMs, availableMs);
+  }
+  return scheduled;
+}