minimojs 1.0.0-alpha.4 → 1.0.0-alpha.41

package/dist/minimo-multiplayer.d.ts

@@ -0,0 +1,387 @@
+import { Game } from "./minimo.js";
+/**
+ * How a room plays:
+ *
+ * - `"turns"`: the players take turns on a state the room keeps, such as a
+ *   card game or a board game. Only the player whose turn it is changes it.
+ * - `"competition"`: every player plays the same round on their own, from the
+ *   same seed, and the room compares their scores at the end.
+ */
+export type RoomMode = "turns" | "competition";
+/**
+ * Where a room is: `"lobby"`, waiting for its players; `"playing"`; or
+ * `"finished"`, showing its results until the host starts again.
+ */
+export type RoomPhase = "lobby" | "playing" | "finished";
+/** Which score wins: `higher`, for points, or `lower`, for times. */
+export type RoomOrder = "higher" | "lower";
+/**
+ * How the game's rooms work. Every field is optional.
+ */
+export interface MultiplayerOptions {
+    /** How the room plays. Default `"turns"`. */
+    mode?: RoomMode;
+    /** The fewest players who can start. Default `2` by turns, `1` in a competition. */
+    minPlayers?: number;
+    /** The most players a room seats, at most `8`. Default `8`. */
+    maxPlayers?: number;
+    /** In a competition and in results, which score wins. Default `"higher"`. */
+    order?: RoomOrder;
+    /**
+     * A live competition's round ends this many seconds after it starts, from 5
+     * to 3600, even if some players have not finished. Default: it waits for
+     * every player, and the host can end it.
+     */
+    timeLimit?: number;
+    /**
+     * Makes a competition an asynchronous challenge: its round starts as soon
+     * as the room is made, and anyone with its link joins and plays it within
+     * this many hours, from 1 to 168. Results show as they arrive.
+     */
+    challengeHours?: number;
+    /**
+     * How many seconds a disconnected player keeps their turn, and a
+     * disconnected host the room, before it passes to the next player, from 0
+     * to 3600. `0` waits forever. Default `60`.
+     */
+    turnTimeout?: number;
+    /** The lobby's title. Default `"Play with friends"`. */
+    title?: string;
+    /** CSS font family of the lobby, such as one of the game's fonts. Default: the system font. */
+    font?: string;
+    /** Background color of the lobby's panels. Default `"#15151d"`. */
+    background?: string;
+    /** Text color. Default `"#ffffff"`. */
+    color?: string;
+    /** Color of titles, buttons, and the player's own row. Default `"#ffcc33"`. */
+    accent?: string;
+    /**
+     * Whether a thin strip at the top of the game says whose turn it is and who
+     * dropped out, during a game by turns. Default `true`.
+     */
+    strip?: boolean;
+}
+/** A player in a room. */
+export interface RoomPlayer {
+    /** The player's id in this room. It says nothing about who they are. */
+    id: string;
+    /** The name Minimo Games shows for the player, the same as in leaderboards. */
+    name: string;
+    /** Their place at the table, from 0, in the order they joined. */
+    seat: number;
+    host: boolean;
+    /** Whether the player is connected now. */
+    connected: boolean;
+    /** In a competition, whether they have reported this round's result. */
+    finished: boolean;
+    /** Their result, once reported or given when the game ended, or `null`. */
+    score: number | null;
+    /** Whether this is the player playing on this device. */
+    me: boolean;
+}
+/** One row of a room's results, best first. */
+export interface RoomResult {
+    id: string;
+    name: string;
+    score: number;
+    /** 1 for the best. Equal scores share a rank. */
+    rank: number;
+    me: boolean;
+}
+/** A change to the room, made with {@link Room.update}. Every field is optional. */
+export interface RoomUpdate {
+    /** The new shared state, which every player receives: plain JSON, at most 16 KB. */
+    state?: unknown;
+    /**
+     * Private states by player id, each received only by that player, such as
+     * the hands dealt: plain JSON, at most 4 KB each. `null` clears one.
+     */
+    private?: Record<string, unknown>;
+    /** Passes the turn: `"next"`, the next player by seat, or a player's id. */
+    turn?: "next" | string;
+}
+/**
+ * The room a player is expected in when the game starts, from
+ * {@link Multiplayer.pendingRoom}.
+ */
+export interface PendingRoom {
+    /** The room's code, such as `KQ7XA`. */
+    code: string;
+    /**
+     * `true` when the player opened the room's link, an invitation; `false`
+     * when they were already in the room on this device, as after a reload.
+     */
+    invited: boolean;
+}
+/** Options for {@link Room.showResults}. */
+export interface RoomResultsOptions {
+    /** A title instead of `"Results"`. */
+    title?: string;
+    /** How a score is written, such as `(s) => s.toFixed(2) + " s"`. Default: the number, with digit grouping. */
+    format?: (score: number) => string;
+}
+/**
+ * What a room promise is refused with. `reason` is one of:
+ * `unavailable` (not on Minimo Games, or the game's creator is not on Pro),
+ * `cancelled` (the player closed the lobby), `room_not_found`, `full`,
+ * `in_progress`, `removed`, `not_your_turn`, `stale` (another change came
+ * first; read the room again and retry), `not_host`, `wrong_phase`,
+ * `not_enough_players`, `state_too_large`, `closed`, or another the room
+ * names.
+ */
+export declare class MultiplayerError extends Error {
+    readonly reason: string;
+    constructor(message: string, reason: string);
+}
+/**
+ * A room the player is in: its players, its phase, its shared state, the
+ * player's private state, and whose turn it is. Every field reads the room as
+ * the player last received it.
+ *
+ * Changes made by the other players arrive between frames, and the listeners
+ * given to {@link Room.onChange} and {@link Room.onMessage} are called inside
+ * the game's loop, before the scene's `onUpdate`, so a game never sees the room
+ * change halfway through a frame. A change the player makes themselves is in
+ * the room when its promise resolves.
+ *
+ * Get a room from {@link Multiplayer.lobby}, {@link Multiplayer.create}, or
+ * {@link Multiplayer.join}.
+ */
+export declare class Room {
+    /** The room's code, such as `KQ7XA`, which friends type to join. */
+    get code(): string;
+    /** The address that opens the game straight into this room. */
+    get link(): string;
+    get mode(): RoomMode;
+    get phase(): RoomPhase;
+    /** Grows each time the room starts a new round: 1 for the first. */
+    get round(): number;
+    /** The players in the room, by seat. */
+    get players(): RoomPlayer[];
+    /** The player playing on this device. */
+    get me(): RoomPlayer;
+    /** Whether the player on this device is the room's host. */
+    get isHost(): boolean;
+    /** The id of the player whose turn it is, or `null`. */
+    get turn(): string | null;
+    /** Whether it is the turn of the player on this device. */
+    get isMyTurn(): boolean;
+    /**
+     * Whether the player on this device can change the state now: on their
+     * turn, or, when no one has the turn, if they are the host.
+     */
+    get canUpdate(): boolean;
+    /** The shared state every player receives, or `null` before anyone writes one. */
+    get state(): any;
+    /** This player's private state, which no other player receives, or `null`. */
+    get mine(): any;
+    /** The state's version, which grows with every change. */
+    get version(): number;
+    /** The round's seed, the same for every player, or `null` before the first round. */
+    get seed(): number | null;
+    /** When a competition's round, or a challenge, ends, or `null`. */
+    get deadline(): Date | null;
+    /** The fewest players who can start. */
+    get minPlayers(): number;
+    /** The most players the room seats. */
+    get maxPlayers(): number;
+    /** For an asynchronous challenge, how many hours it runs; otherwise `null`. */
+    get challengeHours(): number | null;
+    /**
+     * The results, best first: in a competition, the players who have finished
+     * so far; in a game by turns, the scores given to {@link Room.end}. `null`
+     * when there are none.
+     */
+    get results(): RoomResult[] | null;
+    /** Whether the player's connection to the room is up. It reconnects on its own. */
+    get connected(): boolean;
+    /** Whether the room has closed, or the player left it. */
+    get closed(): boolean;
+    /**
+     * A random number from 0 up to 1, from the round's seed: every player who
+     * calls it in the same order gets the same numbers, so they can deal the
+     * same deck or build the same level. It starts again at each round.
+     */
+    random(): number;
+    /** A shuffled copy of `items`, from the round's seed, as {@link Room.random} is. */
+    shuffle<T>(items: readonly T[]): T[];
+    /** The player with this id, or `null`. */
+    player(id: string): RoomPlayer | null;
+    /**
+     * Calls `listener` whenever the room changes: a player joins or leaves, the
+     * state or the turn changes, the phase moves on. It runs inside the game's
+     * loop. Returns a function that stops it.
+     */
+    onChange(listener: (room: Room) => void): () => void;
+    /**
+     * Calls `listener` for each message another player sends with
+     * {@link Room.send}. It runs inside the game's loop. Returns a function that
+     * stops it.
+     */
+    onMessage(listener: (kind: string, data: any, from: RoomPlayer | null) => void): () => void;
+    /**
+     * Calls `listener` once when the room closes, the player is removed, or the
+     * player leaves. `reason` is `"closed"`, `"removed"`, or `"left"`.
+     */
+    onClose(listener: (reason: string) => void): () => void;
+    /** Starts the game, as the host, once enough players are in. Every player's lobby closes. */
+    start(): Promise<void>;
+    /**
+     * Changes the room, on the player's turn or, when no one has the turn, as
+     * the host: the shared state, players' private states, and whose turn it
+     * is. It names the version it started from, and is refused with `stale` if
+     * another change came first.
+     *
+     * ```js
+     * await room.update({ state: { board }, turn: "next" });
+     * ```
+     */
+    update(changes: RoomUpdate): Promise<void>;
+    /**
+     * Ends a game by turns, on the player's turn or as the host. `scores`, by
+     * player id, become the results, ranked by the room's order; `state` is a
+     * last state to show, such as the final board.
+     */
+    end(scores?: Record<string, number>, state?: unknown): Promise<void>;
+    /**
+     * Reports the player's result in a competition's round. The round finishes
+     * when every player has reported, when its time limit passes, or when the
+     * host ends it.
+     */
+    finish(score: number): Promise<void>;
+    /** Ends a competition's round now, as the host, with the results reported so far. */
+    endRound(): Promise<void>;
+    /** Passes the turn to the next player, as the host, such as when its player dropped out. */
+    skipTurn(): Promise<void>;
+    /** Removes a player from the room, as the host. They cannot join it again. */
+    remove(playerId: string): Promise<void>;
+    /**
+     * Plays again, as the host, once the room has finished: the room goes back
+     * to its lobby with the same players, or, for a challenge, starts a new
+     * round at once.
+     */
+    rematch(): Promise<void>;
+    /**
+     * Sends a message to the other players, which the room passes on and does
+     * not keep, such as a reaction. `kind` is a short name; `data` is plain
+     * JSON, at most 1 KB.
+     */
+    send(kind: string, data?: unknown): Promise<void>;
+    /** Leaves the room. The others are told, and the turn and the host pass on. */
+    leave(): Promise<void>;
+    /** Resolves when the room's game starts, or at once if it is playing. */
+    waitForStart(): Promise<void>;
+    /**
+     * Shows the results over the game, in HTML, and keeps them up to date as
+     * players finish. The host can play again from it, or end a round still
+     * running. Resolves `"rematch"` when the next game starts, with the lobby
+     * shown while the players wait, or `"leave"` when the player leaves or the
+     * room closes.
+     */
+    showResults(options?: RoomResultsOptions): Promise<"rematch" | "leave">;
+}
+/**
+ * Multiplayer rooms for a game on Minimo Games: two to eight players, each on
+ * their own device, meet in a room by its code or its link, and play by turns
+ * on a small state the room keeps, or each play the same round of a
+ * competition and compare their scores. Nothing is synchronized frame by
+ * frame: it suits card games, board games, word games, and races against the
+ * clock, not action games.
+ *
+ * It works only inside Minimo Games, and only while the game's creator is on
+ * Minimo Games Pro. Players need no account: a guest types a name once.
+ *
+ * {@link Multiplayer.lobby} shows the lobby over the game, in HTML: creating a
+ * room, joining one by its code, sharing its link, and waiting for the others
+ * until the host starts. A player who opened the room's link lands in it as
+ * soon as the game calls it.
+ *
+ * ```js
+ * import { Multiplayer } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo-multiplayer.js";
+ *
+ * const mp = new Multiplayer(game, { mode: "turns", minPlayers: 2, maxPlayers: 4 });
+ * const room = await mp.lobby();        // resolves when the host starts
+ * if (room.isHost) await room.update({ state: deal(room.shuffle(deck)), turn: "next" });
+ * room.onChange(() => redraw(room.state, room.mine));
+ * // On the player's turn:
+ * if (room.isMyTurn) await room.update({ state: next, turn: "next" });
+ * // When someone wins:
+ * await room.end({ [winnerId]: 1 });
+ * const choice = await room.showResults(); // "rematch" or "leave"
+ * ```
+ *
+ * A player who opens a room's link has already chosen to play online and
+ * which room to join. So a game asks {@link Multiplayer.pendingRoom} as soon
+ * as its assets are loaded, before showing anything. When a room is pending,
+ * it skips every screen that only leads to a room or that the host decides,
+ * such as a title screen, menus, playing alone or online, creating or joining,
+ * the mode, the difficulty, the rules, or the level, and shows only the
+ * choices that are the player's own, such as a character or a color, before
+ * {@link Multiplayer.lobby} or after it:
+ *
+ * ```js
+ * const pending = await mp.pendingRoom();
+ * if (pending) {
+ *   await chooseCharacter();   // only the player's own choices
+ *   room = await mp.lobby();   // that room's lobby, or its game in progress
+ * } else showWelcome();        // Play online, then mp.lobby() to create or join
+ * ```
+ *
+ * What every player must share is the host's choice and travels in the
+ * room's state. A player returning to a room after a reload (`invited` is
+ * false) is asked again only what the game could not keep. When the player
+ * closes the lobby, show the welcome screen.
+ */
+export declare class Multiplayer {
+    /**
+     * @param game - The game.
+     * @param options - How its rooms work, and how the lobby looks.
+     */
+    constructor(game: Game, options?: MultiplayerOptions);
+    /** The room the player is in, or `null`. */
+    get room(): Room | null;
+    /**
+     * Whether multiplayer can be played here: inside Minimo Games, with the
+     * game's creator on Pro.
+     */
+    available(): Promise<boolean>;
+    /** Creates a room, without the lobby. The player is its host. */
+    create(): Promise<Room>;
+    /** Joins a room by its code, without the lobby, or returns to one the player is in. */
+    join(code: string): Promise<Room>;
+    /**
+     * The room this player is expected in, before any screen is shown: the room
+     * whose link they opened, an invitation, or the room they were in on this
+     * device before the page reloaded. `null` on a normal visit, outside
+     * Minimo Games, and when the game's creator is not on Pro.
+     *
+     * It opens nothing, joins nothing, and can be asked again: the room stays
+     * pending until the player is in it. {@link Multiplayer.lobby} then takes
+     * them straight into it. A room that has closed since, as an old link's,
+     * is still returned, and the lobby then says there is no room with that
+     * code.
+     */
+    pendingRoom(): Promise<PendingRoom | null>;
+    /**
+     * The player's name on Minimo Games, the one leaderboards show, or `null`
+     * before they choose one.
+     */
+    playerName(): Promise<string | null>;
+    /**
+     * Shows the lobby over the game, in HTML, and resolves with the room when
+     * its game starts. The player chooses a name if they have none, creates a
+     * room or joins one by its code, shares its code and link with friends, and
+     * waits; the host starts once enough players are in. A player who opened the
+     * game from a room's link goes straight into that room, and one who reloads
+     * the page returns to theirs.
+     *
+     * Refused with `unavailable` outside Minimo Games or when the game's creator
+     * is not on Pro, after the lobby says so, and with `cancelled` when the
+     * player closes it.
+     */
+    lobby(): Promise<Room>;
+    /** Closes the lobby or the results, if showing. The room is kept. */
+    close(): void;
+    /** Closes the lobby and the strip. The player stays in their room; call {@link Room.leave} to leave it. */
+    destroy(): void;
+}