@v12-engine/engine 0.0.0-stage → 0.1.1

package/dist/exactMath.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The maths the simulation does, the same to the last bit in every engine (determinism D3). JavaScript says exactly
+ * what `+`, `-`, `*`, `/` and `Math.sqrt` give, but not `Math.sin`, `Math.cos`, `Math.atan`, `Math.atan2` or
+ * `Math.hypot`: V8, SpiderMonkey and JavaScriptCore each have their own, and two versions of one can differ (Node 22's
+ * `atan2` and Chromium's do, in the last bit). These are fdlibm's (FreeBSD's msun), written with what is exact
+ * everywhere, so a world run in a page, in a worker, on a server or in a replay comes out the same.
+ *
+ * Within a unit in the last place of `Math`'s; they are not faster. What only draws (a view, an effect) has no need of
+ * them: what decides does
+ */
+/**
+ * The sine, the same in every engine (fdlibm's)
+ *
+ * @beta
+ */
+export declare function sin(x: number): number;
+/**
+ * The cosine, the same in every engine (fdlibm's)
+ *
+ * @beta
+ */
+export declare function cos(x: number): number;
+/**
+ * The arctangent, the same in every engine (fdlibm's)
+ *
+ * @beta
+ */
+export declare function atan(x: number): number;
+/**
+ * The angle of a point from the x axis, `atan2(y, x)`, the same in every engine (fdlibm's)
+ *
+ * @beta
+ */
+export declare function atan2(y: number, x: number): number;
+/**
+ * The length of `(x, y)`, `√(x² + y²)`, the same in every engine (`Math.hypot` is not: it scales its arguments as each
+ * engine likes). For the lengths of a game, which are neither near 1e154 nor near 1e-154
+ *
+ * @beta
+ */
+export declare const hypot: (x: number, y: number) => number;
+/**
+ * e^x, the same in every engine (`Math.exp` is not: each has its own): `x` is split into a count of ln 2 and a
+ * remainder under half of one, the remainder's exponential is its Taylor series (adding and multiplying alone, which
+ * are exact everywhere), and the result is that doubled or halved the count of times. Within a few units in the last
+ * place of `Math.exp`'s; the point is sameness, not speed. What a response curve of the computer player's is made of
+ * (`curve.saturate`, AI plan B1)
+ */
+export declare function exp(x: number): number;
+/**
+ * The simulation's maths, the same in every engine: what a game's rules use in the place of `Math`'s, so that its
+ * worlds come out the same in a page, on a server and in a replay (`sin`, `cos`, `atan`, `atan2`, `hypot`, `exp`)
+ *
+ * @beta
+ */
+export declare const exactMath: {
+    readonly sin: typeof sin;
+    readonly cos: typeof cos;
+    readonly atan: typeof atan;
+    readonly atan2: typeof atan2;
+    readonly hypot: typeof hypot;
+    readonly exp: typeof exp;
+};

package/dist/features.d.ts

@@ -0,0 +1,10 @@
+import { type HookDef } from './hooks';
+/**
+ * The rules the engine brings along, written as hook handlers like any game module's. A module can leave any
+ * of them out by id (`GameModule.withoutHooks`), or put its own in place of one by giving a handler the same id.
+ *
+ * @beta
+ */
+export declare const coreHooks: HookDef[];
+/** A bounty, to whoever got it */
+export declare const toldBounty: import("./replication").ReplicatedEvent;

package/dist/fields.d.ts

@@ -0,0 +1,114 @@
+import type { Vec2 } from './math';
+/**
+ * Checkers for what comes in from the outside, like the commands of a player. On a server that is whatever
+ * anyone sends, so nothing is taken on trust: a checker either hands back the value as the type it promises,
+ * or throws `Invalid` saying what is wrong with it, and where (`td.intro.lanes[2].items[0].at is a number`): the
+ * commands of a player, a cinematic's file, a lane's own items and the game's other files are checked by these alike.
+ *
+ * ```ts
+ * const fields = { building: id, unitType: string, queue: optional(bool) }
+ * type Fields = Checked<typeof fields> // { building: number; unitType: string; queue?: boolean }
+ * ```
+ *
+ * @beta
+ */
+export type Check<T> = (value: unknown, path: string) => T;
+/**
+ * A set of named checkers: what an object must have
+ *
+ * @beta
+ */
+export type Fields = Record<string, Check<unknown>>;
+type Out<C> = C extends Check<infer T> ? T : never;
+/** The fields a checker lets be left out: the ones it may hand back `undefined` for */
+type OptionalKeys<F extends Fields> = {
+    [K in keyof F]: undefined extends Out<F[K]> ? K : never;
+}[keyof F];
+/**
+ * The type a set of checkers hands back. Fields that may be left out are optional
+ *
+ * @beta
+ */
+export type Checked<F extends Fields> = {
+    [K in keyof F as K extends OptionalKeys<F> ? never : K]: Out<F[K]>;
+} & {
+    [K in OptionalKeys<F>]?: Exclude<Out<F[K]>, undefined>;
+};
+/** @beta */
+export declare class Invalid extends Error {
+}
+/**
+ * Whether a value is a plain object (not a list, not null): what most of a file's fields are
+ *
+ * @beta
+ */
+export declare const isObject: (value: unknown) => value is Record<string, unknown>;
+/** @beta */
+export declare const bool: Check<boolean>;
+/**
+ * Any finite number
+ *
+ * @beta
+ */
+export declare const number: Check<number>;
+/**
+ * A whole number, 0 or more
+ *
+ * @beta
+ */
+export declare const index: Check<number>;
+/**
+ * The id of an entity or a player
+ *
+ * @beta
+ */
+export declare const id: Check<number>;
+/**
+ * Any number of seconds: a finite number, not below 0
+ *
+ * @beta
+ */
+export declare const seconds: Check<number>;
+/**
+ * Words of any length: what a file says (a line of dialog, a name), not what a player sends (`string`)
+ *
+ * @beta
+ */
+export declare const text: Check<string>;
+/**
+ * A colour as the client draws it: `[r, g, b]`, each a number
+ *
+ * @beta
+ */
+export declare const rgb: Check<[number, number, number]>;
+/**
+ * A list of anything, or none for one left out: each of its values checked by the caller, by its own path
+ *
+ * @beta
+ */
+export declare const list: Check<unknown[]>;
+/** @beta */
+export declare const string: Check<string>;
+/** @beta */
+export declare const ids: Check<number[]>;
+/** @beta */
+export declare const point: Check<Vec2>;
+/**
+ * What may be left out
+ *
+ * @beta
+ */
+export declare function optional<T>(check: Check<T>): Check<T | undefined>;
+/**
+ * One of a few fixed values
+ *
+ * @beta
+ */
+export declare function oneOf<const T extends readonly (string | number)[]>(...values: T): Check<T[number]>;
+/**
+ * An object with these fields. Fields that are not asked for are dropped, so nothing unchecked gets through
+ *
+ * @beta
+ */
+export declare function object<F extends Fields>(fields: F): Check<Checked<F>>;
+export {};

package/dist/fixture.d.ts

@@ -0,0 +1,17 @@
+import type { GameModule } from './game';
+import { type GameMap } from './map';
+/**
+ * The fixture game (see the top of this file): every role of the kit, with round numbers. Gold and lumber, 1000 of each
+ * to start with; a hall and five workers at each start; heroes on (`withHeroes`); no fog explored at the start. A new
+ * one each time, for a test to change
+ *
+ * @beta
+ */
+export declare function fixtureGame(): GameModule;
+/**
+ * A map of the fixture game, 64 cells a side: two players, starting at opposite corners (12, 12 and 52, 52), a gold
+ * mine and a row of trees by each start, and a camp of three creeps in the middle
+ *
+ * @beta
+ */
+export declare function fixtureMap(): GameMap;

package/dist/fog.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Per team visibility of the map, one cell per world unit.
+ *
+ * Each team has two grids. `visible` is what the team sees right now and is cleared and drawn again
+ * on every update. `explored` only ever gets set: ground the team has looked at at least once, which
+ * is drawn as the dimmed "explored" fog and lets players build there.
+ */
+/** The fog in a save, see `FogOfWar.save` */
+export interface FogSave {
+    version: number;
+    revealed: number[];
+    /** Cells of each team, packed */
+    teams: Record<number, {
+        visible: string;
+        explored: string;
+    }>;
+    /**
+     * Each team's bit in the masks entities keep (`Entity.seenBy`): in the order teams first had fog, which a world loaded
+     * from the save would not know otherwise once a player has moved to another team. Saves from before it numbered them
+     * from the teams the world was made with
+     */
+    bits?: Record<number, number>;
+    /** Whether the map is explored from the start, for the teams to come too (`FogOfWar.exploredFromStart`) */
+    exploredFromStart?: true;
+}
+/** @beta */
+export declare class FogOfWar {
+    readonly width: number;
+    readonly depth: number;
+    private readonly visible;
+    private readonly explored;
+    private readonly revealed;
+    /**
+     * One bit per team, for per-entity bitmasks like `Entity.seenBy`. Team ids come from the map and can be
+     * any number (the creeps are team 1000), so they are numbered 0, 1, 2... here instead of being used as
+     * bit positions directly: `1 << 1000` is `1 << 8` in JavaScript and would mix up two teams.
+     */
+    private readonly bits;
+    private readonly levels;
+    /**
+     * What is being lit during an update (`beginUpdate`), a bit a cell, a row of the map `words` of 32 bits: a row of a
+     * circle is a word or two, not hundreds of cells. Written into the grids as the update ends
+     */
+    private readonly lit;
+    private readonly words;
+    private updating;
+    /** The cells at or under each level, as bits: what a viewer on that level sees of what it lights. Made as they are first asked for */
+    private readonly levelMasks;
+    /** The highest level of the ground: a viewer on it or above sees everything it lights. -1 until worked out */
+    private top;
+    /** Bumped every time visibility is recomputed */
+    version: number;
+    constructor(width: number, depth: number, teams: number[], 
+    /** Level of every cell: nobody sees up a cliff. All on the ground floor when left out */
+    levels?: Uint8Array);
+    /** Gives a team that has none yet fog of its own: a player moved to a new team mid-game. Nothing for one there is */
+    addTeam(team: number): void;
+    /**
+     * Whether the whole map is explored from the start (`FogRules.startExplored`, `MapDef.explored`): every team's, and
+     * the teams' made from now on. What stands on it and is no player's is then known to every team from the first moment
+     * (the sessions' `TeamMemory.startKnown`). Set with `exploreFromStart`
+     */
+    exploredFromStart: boolean;
+    /** Grids for a team, and the first bit no other team has */
+    private makeTeam;
+    private freeBit;
+    /** The team's bit in per-entity team masks. 0 for a team without fog (neutral), which then never shows up in one */
+    /** What each team sees and has explored, for a save, with each team's bit */
+    save(): FogSave;
+    restore(save: FogSave): void;
+    teamBit(team: number): number;
+    get teams(): number[];
+    /** Debug switch: the team sees everything */
+    setRevealed(team: number, revealed: boolean): void;
+    isRevealed(team: number): boolean;
+    /**
+     * Starts working out what is seen: what is lit from here to `endUpdate` is collected as bits, and the grids
+     * are written when it ends, so `visible` and `explored` say what they did before until then
+     */
+    beginUpdate(): void;
+    endUpdate(): void;
+    /**
+     * Says the ground's levels changed (`Terrain.levels` written to while the world runs): what a viewer on a level sees
+     * is worked out from them once, and again after this
+     *
+     * @beta
+     */
+    levelsChanged(): void;
+    private highest;
+    private maskOf;
+    /** Lights up what a viewer at the point sees. Ground above the viewer's `level` stays dark, so a flyer passes Infinity */
+    reveal(team: number, x: number, z: number, radius: number, level?: number): void;
+    stateAt(team: number, x: number, z: number): number;
+    isVisible(team: number, x: number, z: number): boolean;
+    isExplored(team: number, x: number, z: number): boolean;
+    /** A team has seen every cell once: the map starts explored for it */
+    exploreAll(team: number): void;
+    /**
+     * The whole map explored from the start, for every team and the teams to come (`exploredFromStart`), or no longer:
+     * then each team has explored what it sees now, and no more (a debug switch, mid-game)
+     *
+     * @beta
+     */
+    exploreFromStart(on: boolean): void;
+    /** Raw per cell state for rendering */
+    cells(team: number): {
+        visible: Uint8Array;
+        explored: Uint8Array;
+    } | null;
+}

package/dist/formation.d.ts

@@ -0,0 +1,111 @@
+import type { Entity, EntityId } from './entity';
+import type { Vec2 } from './math';
+import type { Navigation } from './navigation/navigation';
+import type { World } from './world';
+/**
+ * What a formation lays units out with: the group, where it is sent, the way there, and the room each unit takes.
+ * Points are in the world; `right` and `forward` are the formation's own axes, each a unit long, for a shape that is
+ * drawn facing the way of travel: a place `right * x + forward * z` from the target
+ *
+ * @beta
+ */
+export interface FormationContext {
+    readonly world: World;
+    /** The units laid out: those that walk, or those that fly, apart */
+    readonly units: readonly Entity[];
+    readonly target: Vec2;
+    /** The navigation they go on, to find where they can stand */
+    readonly nav: Navigation;
+    /** The middle of where the units are */
+    readonly centre: Vec2;
+    /** The way from where they are to the target, a unit long (forward, where they face at the end) */
+    readonly forward: Vec2;
+    /** To the right of `forward`, a unit long */
+    readonly right: Vec2;
+    /** Room a unit takes: twice the biggest radius among them, and a gap of `FORMATION_GAP` */
+    readonly spacing: number;
+    /** A point in the world, `x` to the right of the target and `z` forward of it */
+    place(x: number, z: number): Vec2;
+    /** The nearest point a unit can stand on, or the target where there is none within 4 */
+    snap(point: Vec2): Vec2;
+}
+/**
+ * How units ordered to a point together are laid out around it (`OrderInit.formation`, `GameRules.movement.formation`): a
+ * shape, which the engine fits the units to, or the places themselves. The engine's own are `rows`, `circle`,
+ * `square` and `none` (`coreFormations`); a game adds its own (`GameModule.formations`), and changes any laid out
+ * with the `formation` hook
+ *
+ * @beta
+ */
+export interface FormationDef {
+    id: string;
+    /** What the player sees it called */
+    name: string;
+    /**
+     * The shape, as `count` places `spacing` apart, in the formation's own space: `x` to the right, `z` forward, the
+     * first places at the front. Units are fitted to them so that their ways cross as little as can be
+     * (`fitToPlaces`): those ahead to the places at the front
+     */
+    shape?(count: number, spacing: number, context: FormationContext): Vec2[];
+    /**
+     * The places themselves, by the unit's id, when the shape is not enough: one that goes by who the units are, or
+     * where they stand. A unit given none goes to the target itself. Over `shape` where both are given
+     */
+    points?(context: FormationContext): Map<EntityId, Vec2>;
+}
+/**
+ * The gap between two units standing next to each other in a formation
+ *
+ * @beta
+ */
+export declare const FORMATION_GAP = 0.35;
+/**
+ * Fits units to places so that their ways cross as little as can be: the places in order, the front first, each to
+ * the unit nearest it, measured from where the group is to where it goes (the unit's place in the group against the
+ * place's in the formation). A unit left without a place goes to the target
+ *
+ * @beta
+ */
+export declare function fitToPlaces(context: FormationContext, places: readonly Vec2[]): Map<EntityId, Vec2>;
+/**
+ * The engine's usual formation: a tight group keeps its shape as it is, and a scattered one lines up in rows across
+ * the way of travel, as many across as there are rows, the units ahead in the front rows
+ *
+ * @beta
+ */
+export declare const rowsFormation: FormationDef;
+/**
+ * A circle: a ring around the target, the first place at the front, and rings within it where one is not enough for
+ * them all. The rings are a `spacing` apart, the first a `spacing` out: as many as it takes, the outer ones full
+ *
+ * @beta
+ */
+export declare const circleFormation: FormationDef;
+/**
+ * A square: units along the edges of one around the target, the first place at the front's middle, and squares
+ * within it where one is not enough for them all. The squares are a `spacing` apart, the first a `spacing` out: as
+ * many as it takes, the outer ones full
+ *
+ * @beta
+ */
+export declare const squareFormation: FormationDef;
+/**
+ * No formation: every unit to the point itself, as units sent one by one go
+ *
+ * @beta
+ */
+export declare const noneFormation: FormationDef;
+/**
+ * The engine's formations: `rows` (the usual), `circle`, `square` and `none`
+ *
+ * @beta
+ */
+export declare const coreFormations: readonly FormationDef[];
+/**
+ * Individual destinations for a group ordered to the same point, in a formation (`rowsFormation` when none is
+ * given), and what the `formation` hook makes of them. Units that walk and units that fly are laid out apart, each
+ * on their own navigation (`world.navFor`)
+ *
+ * @beta
+ */
+export declare function formationPoints(world: World, units: readonly Entity[], target: Vec2, formation?: FormationDef): Map<EntityId, Vec2>;

package/dist/friendlyFire.d.ts

@@ -0,0 +1,26 @@
+import type { Entity } from './entity';
+import type { GamePack } from './packs/pack';
+import type { World } from './world';
+/**
+ * The friendly fire pack's id
+ *
+ * @beta
+ */
+export declare const FRIENDLY_FIRE = "core.friendlyFire";
+/**
+ * What the friendly fire pack is made with (`withFriendlyFire`)
+ *
+ * @beta
+ */
+export interface FriendlyFireOptions {
+    /** What of its own side's, and its allies', a unit may be told to attack: anything its attack reaches when left out */
+    attacks?: (world: World, attacker: Entity, target: Entity) => boolean;
+}
+/**
+ * Friendly fire, as in classic RTS games: a unit told to attack (the attack command, never a right click) one of its own or
+ * an ally's attacks it. Never of its own accord: units do not pick their own side to attack, nor fight back at it.
+ * Nothing of a neutral player's (a rock, a critter) is made a target by it
+ *
+ * @beta
+ */
+export declare function withFriendlyFire(options?: FriendlyFireOptions): GamePack;