@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/score.d.ts

@@ -0,0 +1,306 @@
+import { type Component } from './components';
+import type { PlayerId } from './entity';
+import type { EventKey } from './events';
+import type { GameModule } from './game';
+import type { System } from './registry';
+import type { World } from './world';
+/**
+ * How a stat takes what it is told: `sum` adds it up (the default), `count` adds one each time whatever the amount,
+ * `max` keeps the most it was told, `min` the least, `last` what it was told last (a gauge: the army now)
+ *
+ * @beta
+ */
+export type ScoreKind = 'sum' | 'count' | 'max' | 'min' | 'last';
+/**
+ * How a stat's number reads on a screen: a whole `number` (the default), a `decimal` one, a `percent` (0..1), or
+ * `time` (seconds, as 3:05). A screen's own (`GameView.hud.score.format`) goes over it
+ *
+ * @beta
+ */
+export type ScoreFormat = 'number' | 'decimal' | 'percent' | 'time';
+/**
+ * What a stat is told of an event, for a player: how much (`amount`, 1 when left out) and what of (`type`: a unit
+ * type, an ability, anything the stat is split by, `ScoreStatDef.byType`)
+ *
+ * @beta
+ */
+export interface ScoreCount {
+    /** Whose number it is */
+    player: PlayerId;
+    /** How much: 1 when left out */
+    amount?: number;
+    /** What it was counted of, for a stat kept `byType`: a unit type, an ability */
+    type?: string;
+}
+/**
+ * What a stat's source makes of an event: nothing to count (`undefined`), one player (one more for them), what one
+ * player is counted, or several of those
+ *
+ * @beta
+ */
+export type ScoreCounted = PlayerId | ScoreCount | readonly ScoreCount[] | undefined | void;
+/**
+ * Where a stat's numbers come from: an event of the world's (`'entityDied'`) or of the game's own (`defineEvent`), and
+ * what it counts of each (`scoreOn`)
+ *
+ * @beta
+ */
+export interface ScoreSource {
+    /** The event: one of the engine's (`entityDied`) or of the game's own (`defineEvent`) */
+    event: EventKey<any>;
+    /** What it counts of each: nothing, a player, or what a player is counted */
+    count(payload: any, world: World): ScoreCounted;
+}
+/**
+ * A number the score keeps for each player (`GameRules.score`, `defineStat`): what it is called, how it adds up, where
+ * it comes from, and how it is shown. One with no source is counted by the game's code alone (`world.score.add`)
+ *
+ * @beta
+ */
+export interface ScoreStatDef {
+    /** Its own, among the game's stats: `world.score.add(player, id, …)` names it */
+    id: string;
+    /** What it is called on a screen: its id when left out */
+    label?: string;
+    /** What the screen says it is, in a tip */
+    description?: string;
+    /** The tab of the score screen it is in: `units`, `heroes`, `resources`, `combat`, or the game's own. `other` when left out */
+    category?: string;
+    /** How it adds up: `sum` when left out, `last` for one that only samples */
+    kind?: ScoreKind;
+    /** The events it is counted from */
+    from?: ScoreSource | readonly ScoreSource[];
+    /**
+     * A gauge: what it is for a player now (their supply used, their gold), read once a second and at each point of the
+     * timeline, and taken as `kind` says (`last` when left out). Nothing taken for `undefined`
+     */
+    sample?(world: World, player: PlayerId): number | undefined;
+    /** Kept by what it was counted of too (`ScoreCount.type`): units killed by unit type, abilities cast by ability */
+    byType?: boolean;
+    /** On the timeline: sampled every `ScoreRules.every` seconds, for a screen's graph */
+    timeline?: boolean;
+    /** How its number is written: `number` (when left out), `decimal`, `percent` (0 to 1), `time` (seconds) */
+    format?: ScoreFormat;
+    /** Counted, and not on the score screen: for the game's own use (an achievement, a mission's goal) */
+    hidden?: boolean;
+}
+/**
+ * Who of the players is told a player's numbers: that player alone (`own`), their side (`allies`), `everyone`, or
+ * `none`; or a function of the world, who is told (`undefined` for an observer) and whose numbers they are
+ *
+ * @beta
+ */
+export type ScoreAudience = 'own' | 'allies' | 'everyone' | 'none' | ((world: World, viewer: PlayerId | undefined, player: PlayerId) => boolean);
+/**
+ * What a game counts of its players (`GameRules.score`): the stats, how often the timeline is sampled, and who is told
+ * what while the game goes on and after it ended. `presetScore()` makes one of the engine's stats
+ *
+ * @beta
+ */
+export interface ScoreRules {
+    /** The stats, or what makes them of the game (the engine's set makes one of each resource) */
+    stats: readonly ScoreStatDef[] | ((game: GameModule) => readonly ScoreStatDef[]);
+    /** Seconds between two points of the timeline: 10 when left out, 0 for no timeline */
+    every?: number;
+    /**
+     * Points the timeline keeps at most: past it, every other point goes and they are twice as far apart, so a long
+     * game keeps its whole story in as much room. 360 when left out
+     */
+    maxPoints?: number;
+    /** Who is told a player's numbers while the game goes on: their side (`allies`) when left out. An observer is told everyone's */
+    live?: ScoreAudience;
+    /** Who is told them once the game is decided: `everyone` when left out */
+    end?: ScoreAudience;
+    /** Seconds between two tellings of the numbers to the screens while the game goes on: 1 when left out */
+    refresh?: number;
+    /** Whose numbers are kept: every player but the neutral ones and the creeps when left out */
+    counts?(world: World, player: PlayerId): boolean;
+    /** The tabs of the score screen, in order, with their names: those of the stats, in the order met, when left out */
+    categories?: readonly {
+        id: string;
+        label: string;
+    }[];
+}
+/**
+ * The score's rules, its stats made: what the registry keeps (`registry.score`)
+ *
+ * @beta
+ */
+export interface ResolvedScore {
+    /** The rules as the game gave them */
+    readonly rules: ScoreRules;
+    /** Every stat, made */
+    readonly stats: readonly ScoreStatDef[];
+    /** Every stat by its id */
+    readonly byId: ReadonlyMap<string, ScoreStatDef>;
+    /** The tabs of the score screen, in order */
+    readonly categories: readonly {
+        id: string;
+        label: string;
+    }[];
+}
+/**
+ * What the score keeps in the world (`world.state(scoreData)`), plain data for a save: by stat, by player, the number;
+ * by stat, player and type, the numbers of a stat kept `byType`; the ticks of the timeline's points, and by stat and
+ * player, the number at each
+ *
+ * @beta
+ */
+export interface ScoreData {
+    /** By stat, by player: the number */
+    values: Record<string, Record<number, number>>;
+    /** By stat, player and type: the numbers of a stat kept `byType` */
+    types: Record<string, Record<number, Record<string, number>>>;
+    /** Ticks between two points of the timeline, as it is now (doubled each time it was thinned) */
+    every: number;
+    /** The ticks of the timeline's points */
+    ticks: number[];
+    /** By stat and player: the number at each point of the timeline */
+    line: Record<string, Record<number, number[]>>;
+}
+/**
+ * The world's component the score is kept in (`core.score`, on the world's own entity): what a save keeps of it
+ *
+ * @beta
+ */
+export declare const scoreData: Component<ScoreData>;
+/**
+ * What a player is told of the score (`Snapshot.score`): the numbers of the players they may see, as they stood at
+ * `tick`. Rounded to hundredths
+ *
+ * @beta
+ */
+export interface ScoreState {
+    /** The tick the numbers stood at */
+    tick: number;
+    /** The game is decided: these are the numbers it ended with, told as `ScoreRules.end` says */
+    final: boolean;
+    /** Whose numbers are in it */
+    players: PlayerId[];
+    /** By stat, by player */
+    values: Record<string, Record<number, number>>;
+    /** By stat, by player, by type: of the stats kept `byType` */
+    types?: Record<string, Record<number, Record<string, number>>>;
+}
+/**
+ * The timeline a player is told (`Snapshot.scoreLine`): the ticks of its points, and by stat and player the number at
+ * each, for the players they may see
+ *
+ * @beta
+ */
+export interface ScoreLineState {
+    /** Seconds between two points */
+    every: number;
+    /** The ticks of its points */
+    ticks: number[];
+    /** By stat and player: the number at each point */
+    values: Record<string, Record<number, number[]>>;
+}
+/**
+ * A source of a stat, typed by its event, the engine's or the game's own: `scoreOn(entityDied, ({ entity, killer }) =>
+ * killer && { player: killer.owner })`
+ *
+ * @beta
+ */
+export declare function scoreOn<T>(event: EventKey<T>, count: (payload: T, world: World) => ScoreCounted): ScoreSource;
+/**
+ * A stat of the game's own, for `GameRules.score`: `defineStat('towersLost', { label: 'Towers lost', category: 'units',
+ * from: scoreOn(entityDied, ({ entity }) => entity.def.tags?.includes('tower') ? entity.owner : undefined) })`.
+ * One with no source is counted in code (`world.score.add(player, 'towersLost')`)
+ *
+ * @beta
+ */
+export declare function defineStat(id: string, def?: Omit<ScoreStatDef, 'id'>): ScoreStatDef;
+/** The score's rules with their stats made of the game, checked: an id twice, or a timeline of no length, throws */
+export declare function resolveScore(rules: ScoreRules | undefined | null, game: GameModule): ResolvedScore | null;
+/**
+ * The score of a world (`world.score`): counts what its stats are told of the world's events, takes the gauges and
+ * the timeline's points, and is what the game's code counts with, and reads, in the rules. What it keeps is the
+ * world's state (`scoreData`); nothing of it is kept here but what is made again from the game
+ *
+ * @beta
+ */
+export declare class Score {
+    private readonly world;
+    /** Goes up with every change of a number: what a session tells the screens again by */
+    version: number;
+    /** Goes up with every point of the timeline */
+    lineVersion: number;
+    private offs;
+    constructor(world: World);
+    /** The game's score, as its rules say: none for a game that counts nothing */
+    get rules(): ResolvedScore | null;
+    /** Whether the game counts anything */
+    get on(): boolean;
+    /** The stats, in order */
+    stats(): readonly ScoreStatDef[];
+    /** Hears the events the stats are counted from: again when the game takes a new version (`reloadGame`) */
+    listen(): void;
+    private take;
+    /** Whether a player's numbers are kept: as the rules say, every player but the neutral ones and the creeps when they do not */
+    counts(player: PlayerId): boolean;
+    /** Who `counts`, by player id, where the rules leave it to the engine (whether a player is neutral never changes) */
+    private counted;
+    /** The players whose numbers are kept, by id */
+    players(): PlayerId[];
+    private put;
+    private stat;
+    /** Counts something for a player, as the stat's kind takes it (adds it up for a sum): one when no amount is given */
+    add(player: PlayerId, id: string, amount?: number, type?: string): void;
+    /** Sets a player's number, whatever the stat's kind */
+    set(player: PlayerId, id: string, value: number, type?: string): void;
+    /** A player's number of a stat: 0 for one never counted */
+    get(player: PlayerId, id: string): number;
+    /** A player's numbers of a stat kept by type, by type */
+    byType(player: PlayerId, id: string): Readonly<Record<string, number>>;
+    /** A team's number of a stat: its players' added up, or the most or the least of them for `max` and `min` */
+    team(team: number, id: string): number;
+    /** The timeline of a player's number of a stat on it: its points, at `ticks` */
+    timeline(player: PlayerId, id: string): {
+        ticks: readonly number[];
+        values: readonly number[];
+    };
+    /** Reads the gauges, and on a point of the timeline (or `point`) takes a point. Run once a second by the score's system */
+    sample(point?: boolean): void;
+    /** Whether `viewer` (`undefined` for an observer) is told `player`'s numbers now */
+    tells(viewer: PlayerId | undefined, player: PlayerId, final: boolean): boolean;
+    /** What `viewer` is told of the numbers (`Snapshot.score`): nothing for a game that counts none, or a viewer told of no one */
+    stateFor(viewer: PlayerId | undefined, final: boolean): ScoreState | undefined;
+    /** What `viewer` is told of the timeline (`Snapshot.scoreLine`): nothing without one */
+    lineFor(viewer: PlayerId | undefined, final: boolean): ScoreLineState | undefined;
+}
+/** The score's system: the gauges once a second, a point of the timeline when one is due. Only in a game that counts */
+export declare function scoreSystem(world: World): System;
+/**
+ * The stats `presetScore` has, by id, those of each resource made of the game (`gathered.gold`, `spent.gold`...)
+ *
+ * @beta
+ */
+export declare function engineStats(game: GameModule): ScoreStatDef[];
+/**
+ * What `presetScore` is given: which of the engine's stats (`only`, or all but `without`), stats of the game's own
+ * after them, and the score's other rules
+ *
+ * @beta
+ */
+export interface PresetScoreOptions extends Omit<ScoreRules, 'stats'> {
+    /** Only these of the engine's stats, by id (`gathered` for every `gathered.<resource>`) */
+    only?: readonly string[];
+    /** The engine's stats but these, by id or as `only` */
+    without?: readonly string[];
+    /** Stats of the game's own, after the engine's */
+    stats?: readonly ScoreStatDef[];
+}
+/**
+ * The engine's score, for `GameRules.score`: a classic RTS score screen. Units produced, killed and lost, buildings
+ * built, razed and lost, the army and the largest, heroes killed and lost, the highest hero level, experience, creeps
+ * killed, items obtained, abilities cast, damage dealt and taken, healing, and of each resource what was gathered,
+ * spent and lost to upkeep, the bounty and what went between allies
+ *
+ * @beta
+ */
+export declare function presetScore(options?: PresetScoreOptions): ScoreRules;
+/** The score the player is told (`Snapshot.score`) */
+export declare const scorePart: import("./replication").SnapshotPart<keyof import(".").Snapshot>;
+/** The score's line over time the player is told (`Snapshot.scoreLine`) */
+export declare const scoreLinePart: import("./replication").SnapshotPart<keyof import(".").Snapshot>;

package/dist/sequences.d.ts

@@ -0,0 +1,132 @@
+import { type EventKey, type ListenerDef } from './events';
+import type { System } from './registry';
+import { type TimerDef } from './timers';
+import type { World } from './world';
+/** An event a step can wait for: one of the engine's by name, or a game's own */
+type AnyEvent = EventKey<any>;
+/** Doing something: runs, and the sequence goes on to the next step at once. `run` is the id of the sequence running it */
+type Act<D> = (world: World, data: D, run: number) => void;
+/** Waiting a number of seconds */
+interface Wait {
+    kind: 'wait';
+    seconds: number;
+}
+/** Waiting for an event, and for what it says to pass a test when there is one */
+interface WaitFor<D> {
+    kind: 'waitFor';
+    event: AnyEvent;
+    /**
+     * `run` is the id of the sequence waiting, as an `Act` has it. Not called `test`, as `WaitUntil`'s is: a step's type
+     * would be inferred from the other's then (`waitFor` in a sequence of data had its data typed `never`)
+     */
+    passes?: (world: World, payload: any, data: D, run: number) => boolean;
+}
+/** Waiting until something holds. Asked every tick, so keep it cheap */
+interface WaitUntil<D> {
+    kind: 'waitUntil';
+    /** `run` is the id of the sequence waiting, as an `Act` has it */
+    test: (world: World, data: D, run: number) => boolean;
+}
+/**
+ * One step of a sequence
+ *
+ * @beta
+ */
+export type Step<D> = Act<D> | Wait | WaitFor<D> | WaitUntil<D>;
+/**
+ * Waits `seconds` before the next step
+ *
+ * @beta
+ */
+export declare const wait: (seconds: number) => Wait;
+/**
+ * Waits for an event, the engine's (`'constructionFinished'`) or a game's own, and for `test` to pass on what it
+ * says when there is one. Heard at the end of the tick, like listeners hear events
+ *
+ * @beta
+ */
+export declare function waitFor<T, D = any>(event: EventKey<T>, test?: (world: World, payload: T, data: D, run: number) => boolean): WaitFor<D>;
+/**
+ * Waits until `test` holds: asked at the end of every tick
+ *
+ * @beta
+ */
+export declare const waitUntil: <D = any>(test: (world: World, data: D, run: number) => boolean) => WaitUntil<D>;
+/**
+ * What a mission or a cutscene is mostly made of: do this, wait two seconds, then that, then wait until the gate
+ * holds five invaders. Made with `defineSequence` and given in `GameModule.sequences`, so that a save finds the steps
+ * by id: what is kept in the world of a running sequence is which one, which step, and its data, never a function.
+ * That is why it is not an `async` function: one of those cannot be saved halfway through
+ *
+ * @beta
+ */
+export interface SequenceDef<D = any> {
+    /** Shared by every game, like other ids: give it a prefix of the game's (`'td.briefing'`) */
+    readonly id: string;
+    readonly steps: readonly Step<D>[];
+}
+/**
+ * Typed help: `defineSequence<{ hero: number }>('td.briefing', [(world) => ..., wait(3), waitFor(constructionFinished)])`.
+ * A helper that is several steps (`talk`, `cinematic(id, { wait })`) may be given as its list, spread or not
+ *
+ * @beta
+ */
+export declare function defineSequence<D = undefined>(id: string, steps: (Step<D> | readonly Step<D>[])[]): SequenceDef<D>;
+/** A sequence as it runs in the world. Plain data: it goes into a save */
+interface Running {
+    id: number;
+    sequence: string;
+    /** The step it is at: the one it waits on, while it waits */
+    step: number;
+    data: unknown;
+    /** The timer it waits for, on a `wait` step */
+    timer?: number;
+}
+export declare const running: import("./components").Component<{
+    next: number;
+    list: Running[];
+}, {
+    next: number;
+    list: Running[];
+}>;
+/** The sequences running in the state of a save, by the id of their definition: what a game must still have to load it */
+export declare const runningSequences: (state: Record<string, unknown>) => string[];
+/** The engine's timers, which every world has next to its game's */
+export declare const coreTimers: TimerDef[];
+/**
+ * The sequences of a world
+ *
+ * @beta
+ */
+export declare class Sequences {
+    private readonly world;
+    private readonly defs;
+    constructor(world: World, defs: readonly SequenceDef[]);
+    /**
+     * Listeners for the events the sequences of a game wait for, one for each event: the world subscribes them with
+     * the game's own
+     */
+    static listenersFor(defs: readonly SequenceDef[]): ListenerDef[];
+    /** Starts a sequence: its first steps run at once, up to the first that waits. Returns its id, for `stop` */
+    start<D>(sequence: SequenceDef<D>, ...data: D extends undefined ? [] : [D]): number;
+    /** Stops a sequence where it is. Whether it was running */
+    stop(id: number): boolean;
+    /** Whether a sequence is still running */
+    running(id: number): boolean;
+    /** Cuts the `wait` a sequence is on short, and takes it on at once: a line of dialog skipped. Whether it was waiting */
+    hurry(id: number): boolean;
+    /** Takes a sequence whose `wait` is over on. For the engine's timer */
+    resume(id: number): void;
+    /** An event that sequences may wait for went off. For the engine's listeners */
+    heard(event: string, payload: unknown): void;
+    /** Asks the sequences waiting until something holds whether it does. The `sequences` system does, every tick */
+    update(): void;
+    /** Runs the steps from where the sequence is, up to the next one that waits, or the end */
+    private advance;
+    private stepOf;
+    private defOf;
+    private state;
+}
+/** Asks the sequences that wait until something holds, at the end of every tick */
+export declare const sequenceSystem: System;
+export {};

package/dist/server/doorman.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Where one who joins a server's game goes (`Doorman`): their seat again, a free seat, a seat the game decides
+ * (`GameServerOptions.seat`), watching, or away with why (design review E12). It decides and says so; the server seats,
+ * tells and closes
+ */
+import { type Logger } from '#engine/log';
+import type { ServerSeat } from '#engine/game';
+import type { GameServerOptions } from './gameServer';
+/** A join, its fields checked */
+export type Join = Extract<LobbyPlayerMessage, {
+    type: 'join';
+}>;
+/** What the doorman reads of the server it keeps the door of */
+export interface DoorContext {
+    readonly phase: 'lobby' | 'game' | 'ended';
+    readonly seats: readonly Seat[];
+    readonly draining: boolean;
+    readonly options: Pick<GameServerOptions, 'seat' | 'watch'>;
+    readonly logger: Logger;
+    publicSeat(seat: Seat): ServerSeat;
+}