@v12-engine/engine 0.0.0-stage → 0.1.1

package/dist/server/ops.d.ts

@@ -0,0 +1,78 @@
+import type { Ratings } from './ratings';
+import type { GameResult } from '#engine/game';
+import { type GameKindListing, type GameListing } from '#engine/session/protocol';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/**
+ * What a game server says of itself: the numbers of `/metrics` (`GameServer.metrics`)
+ *
+ * @beta
+ */
+export interface ServerMetrics {
+    /** In its lobby, playing, or showing a game that ended */
+    phase: 'lobby' | 'game' | 'ended';
+    /** It takes no new games: it is stopping, once the running one is over (`close({ drain })`) */
+    draining: boolean;
+    /** Seconds since it started */
+    uptime: number;
+    /** Games running now (0 or 1 for one server), and played to their end since it started */
+    games: {
+        running: number;
+        played: number;
+    };
+    /** Seats held by someone connected, and those watching */
+    players: number;
+    watching: number;
+    /** Connections open, seated or not */
+    connections: number;
+    /** Ticks of the simulation stepped since it started, and the seconds they took; how long the last one took */
+    ticks: number;
+    tickSeconds: number;
+    lastTickSeconds: number;
+    /** Rounds of sending everyone what changed, and the seconds they took */
+    sends: number;
+    sendSeconds: number;
+    /** Bytes sent to those connected now, over the wire */
+    bytesSent: number;
+}
+/**
+ * Where the addresses are, and who may read the numbers (`GameServerOptions.http`)
+ *
+ * @beta
+ */
+export interface ServerHttpOptions {
+    /** The address that says whether it is well. `/health` when left out; false for none */
+    health?: string | false;
+    /** The address of its numbers. `/metrics` when left out; false for none */
+    metrics?: string | false;
+    /**
+     * The address of the list of its games, for a page to find one (`GameListing`, JSON, readable from any page). `/games`
+     * when left out; false for none
+     */
+    games?: string | false;
+    /**
+     * The address of the best of each mode (`/ratings?mode=melee&n=10&player=<rated id>`: the top and the player's own
+     * place, JSON, readable from any page), where the server keeps ratings. `/ratings` when left out; false for none @beta
+     */
+    ratings?: string | false;
+    /**
+     * What reading the numbers takes (`Authorization: Bearer <key>`): they say how many play, and when. Anyone who can
+     * reach the address when left out: keep it behind the proxy then
+     */
+    metricsKey?: string;
+}
+/**
+ * Answers the health and numbers addresses for the rooms of a process; false for any other request, which goes to
+ * what answered it before. `draining` is whether the process takes no new games
+ */
+export declare function answerOps(request: IncomingMessage, response: ServerResponse, options: ServerHttpOptions | undefined, state: () => {
+    draining: boolean;
+    rooms: ReadonlyMap<string, ServerMetrics>;
+}, games?: () => {
+    games: GameListing[];
+    kinds?: GameKindListing[];
+}, ratings?: {
+    ratings?: Ratings;
+    modes: readonly string[];
+}): boolean;
+/** A game's result as a file of its own in `dir` (`GameServerOptions.resultsDir`): by when it ended and its mode */
+export declare function writeResult(dir: string, result: GameResult): Promise<void>;

package/dist/server/packs.d.ts

@@ -0,0 +1,15 @@
+import type { GameModule } from '#engine/game';
+import { type PackMod } from '#engine/packs';
+/**
+ * The packs of content of a server, read from their files (`packs/<id>/pack.json`) in the order named: that order is
+ * the game's, as a page's `defineGame({ packs })` is
+ *
+ * @beta
+ */
+export declare function readPacks(files: readonly string[]): PackMod[];
+/**
+ * A server's game with its packs of content composed in (`readPacks`, `composeGame`): the game as is with none
+ *
+ * @beta
+ */
+export declare function withPackFiles(game: GameModule, files: readonly string[]): GameModule;

package/dist/server/ratings.d.ts

@@ -0,0 +1,62 @@
+import type { GameResult } from '#engine/game';
+/**
+ * A player's standing in a mode
+ *
+ * @beta
+ */
+export interface Rating {
+    rating: number;
+    games: number;
+    wins: number;
+    /** The name they last played by */
+    name: string;
+}
+/**
+ * Where a server keeps ratings (`GameServerOptions.ratings`): what it reads to show in the lobby and the list, and
+ * what it tells of every game that ended. `createRatings` keeps them in a file, or in memory; a game's own keeps them
+ * where it likes (a database)
+ *
+ * @beta
+ */
+export interface Ratings {
+    /** A player's standing in a mode, by their rated id (`ratedId`): none for one who never played it */
+    get(mode: string, player: string): Rating | undefined;
+    /** Takes in a game that ended: the rated seats' ratings move by how it went, against what was expected */
+    record(result: GameResult): void | Promise<void>;
+    /**
+     * The best of a mode, best first, with their rated ids and places (from 1): what `/ratings` lists. A store with none
+     * lists nothing @beta
+     */
+    top?(mode: string, count: number): RatedPlayer[];
+    /** A player's place in a mode (from 1), with their standing: none for one who never played it @beta */
+    placeOf?(mode: string, player: string): RatedPlayer | undefined;
+}
+/**
+ * A player in a list of the best: their standing, their rated id (`ratedId`), and their place, from 1
+ *
+ * @beta
+ */
+export interface RatedPlayer extends Rating {
+    id: string;
+    place: number;
+}
+/**
+ * The id a player is rated by: a hash of their key or login id, safe to show and keep. The same key, the same id
+ *
+ * @beta
+ */
+export declare const ratedId: (key: string) => string;
+/**
+ * Ratings kept in a file (`file`, JSON, read once and written after every game) or in memory: Elo, each side's
+ * players against the average of the other's, `k` 32, starting at 1500. The computer counts as `start`, and is not
+ * rated; a game with no winner, or with players of one side only, changes nothing
+ *
+ * @beta
+ */
+export declare function createRatings(options?: {
+    file?: string;
+    k?: number;
+    start?: number;
+}): Ratings & {
+    ready: Promise<void>;
+};

package/dist/server/relay.d.ts

@@ -0,0 +1,34 @@
+import type { Logger } from '#engine/log';
+import { type ServerLog } from './log';
+/** @beta */
+export interface RelayOptions {
+    /** Port to listen on: 0 for any free one */
+    port: number;
+    compress?: boolean;
+    /** Where it says what it does, as `GameServerOptions.log` */
+    log?: ServerLog;
+}
+/** @beta */
+export declare class WatchRelay {
+    private readonly socket;
+    private readonly shares;
+    private readonly watchers;
+    private next;
+    /** What the relay says: see `RelayOptions.log` */
+    readonly logger: Logger;
+    private constructor();
+    /** Starts a relay, and resolves once it listens */
+    static start(options: RelayOptions): Promise<WatchRelay>;
+    get port(): number;
+    /** How many watch what is shared under a key */
+    watching(key: string): number;
+    private accept;
+    private tell;
+    private share;
+    private unshare;
+    private watch;
+    private fromWatcher;
+    private leave;
+    /** Stops the relay: every connection closed */
+    close(): Promise<void>;
+}

package/dist/server/rooms.d.ts

@@ -0,0 +1,162 @@
+import type { GameKindListing, GameListing } from '#engine/session/protocol';
+import { GameServer, type GameServerOptions } from './gameServer';
+import { type ServerLog } from './log';
+import { type ServerHttpOptions, type ServerMetrics } from './ops';
+/**
+ * A room's game server: all of `GameServerOptions` but what the port they share says once for all
+ *
+ * @beta
+ */
+export type RoomOptions = Omit<GameServerOptions, 'port' | 'compress' | 'idleTimeout' | 'maxBuffered' | 'maxConnections' | 'http' | 'log'>;
+/**
+ * A kind of game a player may make a room of (features-plan H2): what a "New game" makes (`POST /games`), with the
+ * settings asked for (the map) where the game offers them
+ *
+ * @beta
+ */
+export interface RoomKind {
+    /** What a list calls it */
+    name: string;
+    /**
+     * The room it makes: the same options for each, or a function that makes a room's options each time one is made,
+     * with the settings asked for (a random map for each: `generatedMode`). A kind of a function is listed and matched
+     * by a room it makes once, at first
+     */
+    room: RoomOptions | ((settings: Record<string, string>) => RoomOptions);
+}
+/** @beta */
+export interface GameRoomsOptions {
+    /** The port they share: 8787 when left out, 0 for any free one */
+    port?: number;
+    /**
+     * The rooms, by name: each a game server of its own (a lobby and its games), reached at its name
+     * (`ws://host:8787/arena`). A name is letters, digits, `-` and `_`. They are there for as long as the process is
+     */
+    rooms: Record<string, RoomOptions>;
+    /**
+     * What players may make rooms of, by id (`POST /games` with `{ kind, settings }`, a "New game"): each room made is
+     * named after its kind and closed once nobody has been in it for `emptyFor`. None when left out
+     */
+    kinds?: Record<string, RoomKind>;
+    /** How many rooms players may have made at once, those matchmaking made with them: 16 when left out */
+    maxMade?: number;
+    /** Seconds a made room may stay empty before it is closed: 60 when left out. A room nobody came to counts from when it was made */
+    emptyFor?: number;
+    /**
+     * Matchmaking (features-plan H3): players wait in a queue for a kind (`kinds`), at the address `queue`
+     * (`ws://host:8787/queue`, `{ type: 'queue', kind, name }`); once as many wait as its seats for players, it makes a
+     * room of the kind, which lets in only them, and hands each a ticket to it (`{ type: 'matched', room, ticket }`). On
+     * where there are kinds, unless `false`; `path` for another address
+     */
+    matchmaking?: boolean | {
+        path?: string;
+    };
+    compress?: boolean;
+    idleTimeout?: number;
+    maxBuffered?: number;
+    /**
+     * Connections open at once to all the rooms and the queue, at most (`SocketServerOptions.maxConnections`). 1024 when
+     * left out
+     *
+     * @beta
+     */
+    maxConnections?: number;
+    /**
+     * Seconds a connection to the queue has to say what it waits for (`queue`) before it is closed. 10 when left out;
+     * a room's own connections have their room's (`GameServerOptions.joinWithin`)
+     *
+     * @beta
+     */
+    joinWithin?: number;
+    /** Where they all say what they do, each line with its room */
+    log?: ServerLog;
+    /** The health and numbers addresses, for all of them: the numbers of each by its room */
+    http?: ServerHttpOptions;
+    /** Where ratings are kept, for every room's players (`GameServerOptions.ratings`), where a room says none of its own */
+    ratings?: GameServerOptions['ratings'];
+}
+/**
+ * Many games in a process (S58): game servers that share a port, each a room reached at its name, as a server of its
+ * own would be at its port. One process, one thread: each room's games step in turn, so the rooms of a process are as
+ * many as its ticks have time for (`/metrics` says how long they take). A connection to a room there is not is told so
+ * and closed. Rooms are added in code (`add`), or made by players of the kinds it offers (`kinds`, `POST /games`) and
+ * closed once empty
+ *
+ * @beta
+ */
+export declare class GameRooms {
+    private readonly socket;
+    private readonly options;
+    private readonly logger;
+    private readonly servers;
+    /** Where each room's connections come from, by its name */
+    private readonly doors;
+    /** The rooms players made, and since when each has been empty (nobody connected): what closes them */
+    private readonly made;
+    /** When each address last asked for rooms (`POST /games`): a few a minute each */
+    private readonly askedBy;
+    private sweeper?;
+    private nextMade;
+    /** Who waits to be matched, by kind, in the order they came */
+    private readonly queues;
+    private constructor();
+    /** The rooms there are now, by name */
+    get rooms(): ReadonlyMap<string, GameServer>;
+    /** Starts the rooms, and resolves once they listen */
+    static start(options: GameRoomsOptions): Promise<GameRooms>;
+    /** A kind it offers, by id: its own, never what every object has (`constructor`), whatever a page sends */
+    private kind;
+    /** The address of the queue, or none where there is no matchmaking */
+    private get queuePath();
+    /** A connection to a room: handed to its game server, or told there is no such room. The queue's, to the queue */
+    private connect;
+    /** Opens a room at a name, as `rooms` does: in code, while the rooms run */
+    add(name: string, room: RoomOptions): Promise<GameServer>;
+    /** Closes a room and lets go of its name: those in it are let go */
+    remove(name: string): Promise<void>;
+    /**
+     * Makes a room of a kind it offers (`kinds`), with the settings asked for: what `POST /games` does. Its name is the
+     * kind's and a number. Refused (with why) for a kind it does not offer, too many made, or while it stops
+     */
+    make(kind: string, settings?: Record<string, string>, seat?: RoomOptions['seat']): Promise<{
+        room: string;
+    } | {
+        refused: string;
+    }>;
+    /** A room a kind makes, as its listing and matchmaking read it: the one it makes, or one it made once (a kind of a function) */
+    private readonly samples;
+    private sampleOf;
+    /** How many of a kind's seats are for players: those the computer does not play */
+    private seatsFor;
+    /** A connection to the queue: it says the kind it waits for, is told how many wait, and its ticket once matched */
+    private waitInQueue;
+    /**
+     * Whether an address has asked for games too often to ask again now: a few a minute each, made (`POST /games`) or
+     * waited for in the queue, so that nobody fills every place there is by asking over and over. Counted when it has not
+     */
+    private askedTooOften;
+    /** Tells everyone waiting for a kind how many wait, of how many it takes */
+    private tellQueue;
+    /** As many wait for a kind as its seats: a room of it for them, which lets in only them, and a ticket each */
+    private match;
+    /** Closes the rooms players made that have been empty long enough */
+    private sweep;
+    /** `POST /games`: a room made of a kind it offers, `{ kind, settings }`, answered with its name. And what a page asks first */
+    private answerMake;
+    /** The port they share */
+    get port(): number;
+    /** Whether they take no new games: stopping */
+    get draining(): boolean;
+    /** The modes the rooms play, each once, in their order: what the ratings are kept by (`/ratings`) */
+    modes(): string[];
+    /** Every room's game, as a list of games says it (`GET /games`) */
+    listing(): GameListing[];
+    /** The kinds of game players may make a room of (`kinds`), by id, with their names and the settings they offer */
+    kinds(): GameKindListing[];
+    /** The numbers of each room, by its name */
+    metrics(): Map<string, ServerMetrics>;
+    /** Stops every room (see `GameServer.close`: with `drain`, each waits for its game, all at once), then the port */
+    close(options?: {
+        drain?: number;
+    }): Promise<void>;
+}

package/dist/server/seat.d.ts

@@ -0,0 +1,2 @@
+/** A token to come back to a seat with: what only who has it knows */
+export declare function randomToken(): string;

package/dist/server/seatSettings.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What a lobby offers to choose for each seat (`seatSettingsOf`): a race where the game has races, and for a game that
+ * says how its computers play (`GameModule.ai`) a difficulty and a personality, the engine's and the game's own. On the
+ * server's side: it reads the computer player's profiles (`@v12-engine/engine/ai`), which the engine's core does not load
+ */
+import type { GameModule, ServerHooks } from '#engine/game';
+/**
+ * What a game offers to choose for each seat in a lobby (`ServerHooks.seatSettings`), with a race among them where the
+ * game has races and does not offer its own choice of one: each race, by its name, and `random` where there are two
+ * or more; only those of
+ * `races` where given (the races a map offers, `GameMap.races`). The first is chosen until someone does
+ *
+ * @beta
+ */
+export declare function seatSettingsOf(game: GameModule, races?: readonly string[]): NonNullable<ServerHooks['seatSettings']>;

package/dist/server/secret.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Whether what was brought is the secret (an admin's key, a key to watch, to the numbers), compared in a time that
+ * says nothing of how much of it is right (RV37)
+ */
+export declare const sameSecret: (brought: string, secret: string) => boolean;

package/dist/server/start.d.ts

@@ -0,0 +1,54 @@
+import type { Logger } from '#engine/log';
+import type { BrainDef } from '#engine/ai/brain';
+import type { GameModule } from '#engine/game';
+import type { GameMap } from '#engine/map';
+import type { World } from '#engine/world';
+import { GameServer, type GameServerOptions } from './gameServer';
+import { type GameMode, type ModeSeat } from './mode';
+/**
+ * What a game server is started with: the game, where its worlds come from, and the server's own options
+ *
+ * @beta
+ */
+export interface StartServerOptions extends Omit<GameServerOptions, 'mode' | 'port'> {
+    /** The rules of the game (`GameModule`): of a game defined whole, its `rules`. A server never sees a game's view */
+    game: GameModule;
+    /** The port to listen on: 8787 when left out, 0 for any free one */
+    port?: number;
+    /** A map of the game: each game is played on a world made from it, with a seat for each of its players with a start */
+    map?: GameMap;
+    /** A world made in code for each game, with the lobby's settings: in the place of a map. Says its `seats` too */
+    makeWorld?: (settings: Record<string, string>, context?: {
+        log?: Logger;
+    }) => World | Promise<World>;
+    /** The seats a player may take. Those of the map when left out */
+    seats?: ModeSeat[];
+    /** What the game does once a world is made, before anyone plays: a mission given, the first wave sent */
+    start?: (world: World, context: {
+        map?: GameMap;
+        settings: Record<string, string>;
+    }) => void | Promise<void>;
+    /**
+     * How a computer player in a seat plays (`ai` says which seats, and those nobody took are its too): its options by
+     * seat (`GameMode.ai`), or the brain that plays every seat of the computer (`defineBrain`), against everyone else's
+     * base; the first brain the game lists, against everyone else's base when left out; `null` for
+     * a game the computer does not play. `mode` for a brain by seat (`GameMode.brain`)
+     */
+    computer?: GameMode['ai'] | BrainDef | null;
+    /** A mode put together elsewhere, in the place of all of the above but the game */
+    mode?: GameMode;
+    /** What the mode is called. The map's name, or the game's */
+    name?: string;
+}
+/**
+ * Starts a server of a game, and resolves once it listens: a lobby that seats who joins, then games of it, one after
+ * the other, each on a world made anew.
+ *
+ *     const server = await startServer({ game: rules, map, start: (world) => startMission(world) })
+ *     // server.port, server.close()
+ *
+ * The parts are there on their own: `GameServer.start` with a `GameMode`, `mapMode`, `SessionHost`
+ *
+ * @beta
+ */
+export declare function startServer(options: StartServerOptions): Promise<GameServer>;

package/dist/server/websocket.d.ts

@@ -0,0 +1,74 @@
+import { type Logger } from '#engine/log';
+import { createServer, type Server } from 'node:http';
+import type { Transport } from '#engine/session/remote';
+/**
+ * A connection, with what it came with: the address it was asked at, and who from
+ *
+ * @beta
+ */
+export interface Connection extends Transport {
+    readonly url: string;
+    readonly address: string;
+    /** Bytes written to it so far, as they go over the wire: compressed, where it is */
+    readonly bytesSent: number;
+    /** Whether what goes over it is compressed (`permessage-deflate`) */
+    readonly compressed: boolean;
+}
+/** @beta */
+export interface SocketServerOptions {
+    port: number;
+    /** Where it says what goes wrong with a connection. The root logger when left out */
+    log?: Logger;
+    /** Characters a message may have at most: a longer one closes the connection. 64 KB when left out */
+    maxMessage?: number;
+    /** Whether to compress what goes over connections whose other end can take it. Yes when left out */
+    compress?: boolean;
+    /**
+     * Seconds a connection may say nothing before it is closed: it is pinged meanwhile, and a browser answers a ping by
+     * itself, so only one that is gone (a machine that vanished without closing) goes. 60 when left out
+     */
+    idleTimeout?: number;
+    /**
+     * Bytes waiting to go out to a connection, at most: one that takes what it is sent too slowly is closed, where it
+     * once queued in the server's memory without end. 16 MB when left out
+     */
+    maxBuffered?: number;
+    /**
+     * Connections open at once, at most: one more is answered `503` and never upgraded (RV38). 1024 when left out
+     *
+     * @beta
+     */
+    maxConnections?: number;
+    /** What answers plain HTTP requests: a page saying what this is, by default */
+    onRequest?: Parameters<typeof createServer>[1];
+}
+/**
+ * Where a game server's connections come from (`GameServer.attach`): `onConnection` is told of each one made, `close`
+ * closes them all. A socket server, or a room of a port that several share (`GameRooms`)
+ *
+ * @beta
+ */
+export interface ConnectionSource {
+    /** The port they come in at */
+    readonly port: number;
+    /** Who is told of each connection made: one handler, the last given */
+    onConnection(handler: (connection: Connection) => void): void;
+    /** Closes every connection it made */
+    close(): Promise<void>;
+}
+/**
+ * A WebSocket server: `onConnection` is told of each connection made. `close` stops it, and closes them all
+ *
+ * @beta
+ */
+export interface SocketServer extends ConnectionSource {
+    readonly server: Server;
+    /** The port it listens on: the one given, or the one it was given for 0 */
+    readonly port: number;
+}
+/**
+ * Starts a WebSocket server, and resolves once it listens
+ *
+ * @beta
+ */
+export declare function startSocketServer(options: SocketServerOptions): Promise<SocketServer>;