@openturn/server

bun add @openturn/server

interface GameDeployment<TGame> {
  deploymentVersion: string;
  game: TGame;
  gameKey: string;
  match: MatchInput<GamePlayers<TGame>>;
  metadata?: ProtocolValue;
  schemaVersion: string;
}

const room = await createRoomRuntime({
  deployment,                  // GameDeployment
  roomID,                      // MatchID
  connectedPlayers?,           // pre-populate connected list
  initialNow?,                 // ms, for deterministic time
  persistence?,                // RoomPersistence
  seed?,                       // RNG seed, otherwise derived from roomID
});

interface RoomRuntime<TGame> {
  connect(playerID): Promise<readonly RoomRuntimeEnvelope<TGame>[]>;
  disconnect(playerID): void;
  getState(): RoomRuntimeState<TGame>;
  handleClientMessage(message): Promise<readonly RoomRuntimeEnvelope<TGame>[]>;
}

interface RoomRuntimeState<TGame> {
  branch: ProtocolHistoryBranch;
  connectedPlayers: readonly PlayerID[];
  revision: Revision;
  roomID: MatchID;
  snapshot: MatchSnapshot<GamePublicView<TGame>, GameResultState<TGame>>;
}

interface RoomRuntimeOptions<TGame> {
  deployment: GameDeployment<TGame>;
  roomID: MatchID;
  connectedPlayers?: readonly PlayerID[];
  initialNow?: number;
  initialSavedSnapshot?: InitialSavedSnapshot<TGame>;  // warm-start from a saved checkpoint
  onActionProfileCommit?: RoomActionProfileCommitHandler<TGame>;
  onSaveRequest?: RoomSaveHandler<TGame>;
  onSettle?: RoomSettleHandler<TGame>;
  persistence?: RoomPersistence;
  restorePersistedState?: boolean;
  seed?: string;
}

await createRoomRuntime({
  deployment,
  roomID,
  onSettle: async ({ delta, gameKey, profilesAtSetup, result, roomID }) => {
    // persist delta here — e.g. POST to your control plane.
  },
});

onActionProfileCommit: async ({ actionID, delta, roomID }) => {
  await profileStore.applyIdempotent({ key: `${roomID}:${actionID}`, delta });
}

interface RoomSaveHandlerInput<TGame> {
  branch: ProtocolHistoryBranch;
  clientRequestID: string;
  initialNow: number;
  match: MatchInput<GamePlayers<TGame>>;
  matchID: MatchID;
  playerID: PlayerID;
  revision: Revision;
  seed: string;
  snapshot: GameSnapshotOf<TGame>;
}

interface RoomSaveHandlerOutput {
  saveID: string;
  downloadURL?: string;
}

interface RoomActionProfileCommitInput<TGame> {
  actionID: string;
  delta: ProfileCommitDeltaMap<GamePlayers<TGame>>;
  deploymentVersion: string;
  gameKey: string;
  match: MatchInput<GamePlayers<TGame>>;
  revision: Revision;
  roomID: MatchID;
}

interface RoomPersistence {
  load(roomID: MatchID): Promise<RoomPersistenceRecord | null>;
  save(record: RoomPersistenceRecord): Promise<void>;
}

interface EncodeSaveOptions {
  keyId?: number;   // 1..255, identifies the encryption key version embedded in the envelope
  nonce?: Uint8Array; // 12 bytes; leave unset to randomize
}

interface RoomTokenClaims {
  deploymentVersion: string;
  exp: number;
  iat: number;
  playerID: PlayerID | null;
  roomID: MatchID;
  scope: "lobby" | "game";
  userID: string;
}

interface SignedRoomToken {
  claims: RoomTokenClaims;
  token: string; // base64url-encoded `${base64url(claims)}.${signature}`
}

import { LobbyRuntime } from "@openturn/server";

const runtime = new LobbyRuntime(env, persisted?);

interface LobbyEnv {
  hostUserID: string;
  capacity: number;
  minPlayers: number;
  playerIDs: readonly string[]; // keyed by seat index
}

interface SeatRecord {
  seatIndex: number;
  userID: string;
  userName: string | null;
  ready: boolean;
}

interface LobbyPersistedState {
  mode: LobbyPhase;
  seats: readonly SeatRecord[];
  userToPlayer: Readonly<Record<string, string>>;
}

interface LobbyStartAssignment {
  userID: string;
  seatIndex: number;
  playerID: string;
}

type LobbyApplyResult =
  | { ok: true; changed: boolean }
  | { ok: false; reason: LobbyRejectionReason };

type LobbyStartResult =
  | { ok: true; assignments: readonly LobbyStartAssignment[] }
  | { ok: false; reason: LobbyRejectionReason };

interface LobbyDropUserResult {
  changed: boolean;
  shouldCloseRoom: boolean;
}

import { BotDriver, resolveBotMap } from "@openturn/server";

// At lobby:start time, build a Map<playerID, Bot<TGame>> from the registry
// attached to game.bots:
const botMap = resolveBotMap(game.bots, lobbyStartResult.assignments);
const driver = botMap === null ? null : new BotDriver({ game, bots: botMap });

// After every dispatch (human or bot), tick the driver:
await driver?.tick({
  session: roomRuntime.getSession(),
  matchID,
  dispatch: (msg) => roomRuntime.handleClientMessage(msg),
});

import { createGameWorker } from "@openturn/server/worker";
import { deployment } from "./deployment";

const { default: handler, GameRoom } = createGameWorker(deployment, {
  idleReapMs?: 5 * 60 * 1000,
  lobbyTokenTtlSeconds?,
  gameTokenTtlSeconds?,
});

export { GameRoom };
export default handler;

interface GameWorkerExports {
  default: ExportedHandler<GameWorkerEnv>;
  GameRoom: DurableObjectConstructor<GameWorkerEnv>;
}