minimojs 1.0.0-alpha.4 → 1.0.0-alpha.40

package/dist/minimo-leaderboard.d.ts

@@ -0,0 +1,199 @@
+import { Game } from "./minimo.js";
+/**
+ * When a leaderboard starts again. Every period is a UTC calendar unit, and a
+ * week is an ISO week, starting on Monday, so every player sees the table
+ * reset at the same moment. Past periods stay readable.
+ */
+export type LeaderboardCycle = "never" | "daily" | "weekly" | "monthly" | "yearly";
+/** Which score is better: `higher`, for points, or `lower`, for times. */
+export type LeaderboardOrder = "higher" | "lower";
+/**
+ * What a leaderboard's table calls each player: `player`, the name the player
+ * wrote, or `noname`; `hidden`, no names; or `assigned`, a name such as
+ * `Blue Fox 42`, given to each player.
+ */
+export type LeaderboardNames = "player" | "hidden" | "assigned";
+/**
+ * Who can be in a leaderboard. `account`: players signed in to Minimo Games,
+ * in one table every player sees. `local`: light users, whose scores stay on
+ * their own device, so each player sees only their own.
+ */
+export type LeaderboardPlayer = "account" | "local";
+/**
+ * How a leaderboard works. On Minimo Games the creator sets these on the
+ * game's Edit leaderboards page, or an AI agent sets them with the
+ * `saveGameLeaderboard` tool, and the game reads them; the settings passed to
+ * {@link Leaderboard} are used only when the game runs anywhere else.
+ */
+export interface LeaderboardSettings {
+    /** The title its table shows. */
+    title: string;
+    cycle: LeaderboardCycle;
+    order: LeaderboardOrder;
+    names: LeaderboardNames;
+    player: LeaderboardPlayer;
+}
+/**
+ * Which period of a leaderboard to read: `"current"` (the default),
+ * `"previous"`, such as yesterday's table of a daily leaderboard, or a period
+ * written out: `"2026-10-17"`, `"2026-W42"`, `"2026-10"`, or `"2026"`.
+ */
+export type LeaderboardPeriod = "current" | "previous" | string;
+/** One row of a leaderboard's table. */
+export interface LeaderboardEntry {
+    /** 1 for the best score. Equal scores share a rank. */
+    rank: number;
+    /** The player's name, or `null` when the leaderboard shows no names. */
+    name: string | null;
+    score: number;
+    /** Whether this is the player playing now. */
+    mine: boolean;
+}
+/** One period of a leaderboard, best score first. */
+export interface LeaderboardTable {
+    key: string;
+    settings: LeaderboardSettings;
+    /** The period read, or `null` for the period before a leaderboard that never resets. */
+    period: string | null;
+    entries: LeaderboardEntry[];
+    /** The player's own entry in the period, wherever it ranks, or `null`. */
+    mine: LeaderboardEntry | null;
+    /**
+     * `false` when the leaderboard does not exist, such as a key no leaderboard
+     * of the game has. The table is then empty.
+     */
+    available: boolean;
+    /** Whether the scores are kept on this device rather than by Minimo Games. */
+    local: boolean;
+}
+/**
+ * What became of a score:
+ *
+ * - `saved`: it is the player's best in the period, and the table shows it.
+ * - `not_better`: the player already has a better score in the period.
+ * - `pending_sign_in`: the leaderboard takes Minimo Games accounts and the
+ *   player is not signed in. Minimo Games asks them to sign in, keeps the
+ *   score, and saves it when they come back.
+ * - `unavailable`: the leaderboard does not exist, or the game is not taking
+ *   new records now.
+ */
+export type LeaderboardSubmitStatus = "saved" | "not_better" | "pending_sign_in" | "unavailable";
+export interface LeaderboardSubmitResult {
+    status: LeaderboardSubmitStatus;
+    /** The player's best score in the period, or `null` when nothing was saved. */
+    best: number | null;
+    /** The rank of that best score, or `null` when nothing was saved. */
+    rank: number | null;
+    period: string | null;
+}
+/** Options for {@link Leaderboard.top}. */
+export interface LeaderboardTopOptions {
+    /** Which period to read. Default `"current"`. */
+    period?: LeaderboardPeriod;
+}
+/** Options for {@link Leaderboard.show}. Every field is optional. */
+export interface LeaderboardShowOptions {
+    /** How many of the best scores the table shows. Default `10`, at most `100`. */
+    top?: number;
+    /** Which period the table opens on. Default `"current"`; the player can switch to the previous one. */
+    period?: LeaderboardPeriod;
+    /** A title instead of the leaderboard's own. */
+    title?: string;
+    /** How a score is written, such as `(s) => s.toFixed(2) + " s"`. Default: the number, with digit grouping. */
+    format?: (score: number) => string;
+    /** CSS font family, such as one of the game's fonts. Default: the system font. */
+    font?: string;
+    /** Background color of the table. Default `"#15151d"`. */
+    background?: string;
+    /** Text color. Default `"#ffffff"`. */
+    color?: string;
+    /** Color of the title and of the player's own row. Default `"#ffcc33"`. */
+    accent?: string;
+}
+/**
+ * A leaderboard of the game: a table of each player's best score, per period.
+ *
+ * On Minimo Games, the creator sets up a game's leaderboards, up to 5, on the
+ * game's Edit leaderboards page, or an AI agent with the `saveGameLeaderboard`
+ * tool; the game names one by its key. Their settings come from there, and a
+ * key that no leaderboard of the game has is unavailable. Leaderboards are part
+ * of Minimo Games Pro: while the creator is not on it, the game shows its
+ * tables but saves no new records.
+ *
+ * Scores of a leaderboard that takes Minimo Games accounts go to one table
+ * that every player sees. Minimo Games posts them for the signed-in player, and
+ * asks a player who is not signed in to sign in, keeping the score until they
+ * do. Scores of a leaderboard for light users stay on the device, and a game
+ * preview keeps every score on the device, so a working version never changes
+ * the published game's tables.
+ *
+ * Anywhere else, every leaderboard keeps its scores on the device, with the
+ * settings passed here.
+ *
+ * Nothing here pauses the game. Await {@link Leaderboard.show} to continue
+ * after the player closes the table.
+ *
+ * ```js
+ * import { Leaderboard } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo-leaderboard.js";
+ *
+ * const best = new Leaderboard(game, "best-score");
+ * // When a run ends:
+ * await best.submit(score);
+ * await best.show({ top: 10 });
+ * ```
+ */
+export declare class Leaderboard {
+    /** The key the game names this leaderboard by. */
+    readonly key: string;
+    /**
+     * @param game - The game.
+     * @param key - The leaderboard's key, as set up on Minimo Games.
+     * @param settings - Used only when the game runs outside Minimo Games.
+     *   Default: a leaderboard on the device that never resets, where higher is
+     *   better and players are named by their own name.
+     */
+    constructor(game: Game, key: string, settings?: Partial<LeaderboardSettings>);
+    /** Whether the table is showing. */
+    get isShowing(): boolean;
+    /**
+     * This leaderboard's settings, and whether it exists and keeps its scores on
+     * the device.
+     */
+    info(): Promise<{
+        settings: LeaderboardSettings;
+        available: boolean;
+        local: boolean;
+    }>;
+    /**
+     * Posts a score. Only the player's best score in the current period is
+     * kept, so posting every finished run is right.
+     *
+     * @param score - A finite number. Which is better, higher or lower, is the
+     *   leaderboard's setting.
+     */
+    submit(score: number): Promise<LeaderboardSubmitResult>;
+    /**
+     * Reads one period of the table, best score first.
+     *
+     * @param limit - How many of the best scores. Default `10`, at most `100`.
+     */
+    top(limit?: number, options?: LeaderboardTopOptions): Promise<LeaderboardTable>;
+    /**
+     * The light user's name on this device, shared by every Minimo Games game,
+     * or `null` before the player writes one. The table asks for it on its own
+     * when a leaderboard for light users shows names.
+     */
+    playerName(): Promise<string | null>;
+    /** Sets the light user's name on this device. Returns it cleaned, or `null` when it is empty or too long. */
+    setPlayerName(name: string): Promise<string | null>;
+    /**
+     * Shows the table over the game, in HTML: the best scores of a period, the
+     * player's own entry, and, for a leaderboard that resets, a switch to the
+     * previous period. Resolves when the player closes it.
+     */
+    show(options?: LeaderboardShowOptions): Promise<void>;
+    /** Closes the table, if it is showing. */
+    close(): void;
+    /** Closes the table. The leaderboard's scores are kept. */
+    destroy(): void;
+}