@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/systems/production.d.ts

@@ -0,0 +1,49 @@
+import type { Entity } from '#engine/entity';
+import { type PlayerFacts } from '#engine/shared';
+import { type Cost } from '#engine/defs';
+import type { ProductionKind } from '#engine/hooks';
+import type { System } from '#engine/registry';
+import type { World } from '#engine/world';
+/**
+ * Lets the `beforeProduce` hook have its say about something about to be made, then has the player pay for it.
+ * What it ends up costing and how long it takes, or undefined when it is not made (and the player was told why).
+ * `producer` is the building it is made in, or the worker putting down a structure
+ */
+export declare function startProducing(world: World, producer: Entity, kind: ProductionKind, id: string, cost: Cost | undefined, time: number): {
+    cost: Cost;
+    time: number;
+} | undefined;
+/** Queues a unit for training. Returns false (and tells the player why) when that is not possible. */
+export declare function enqueueProduction(world: World, building: Entity, unitType: string): boolean;
+/**
+ * What there is to know about a player for whether they can make something, see `trainRefusal`
+ *
+ * @beta
+ */
+export declare function playerFacts(world: World, playerId: number): PlayerFacts;
+/**
+ * Levels of an upgrade a player has, counting the one being researched
+ *
+ * @beta
+ */
+export declare function upgradeLevel(world: World, playerId: number, upgrade: string): {
+    level: number;
+    researching: boolean;
+};
+/** Queues an upgrade. One level at a time, and only in one building at once. */
+export declare function enqueueResearch(world: World, building: Entity, upgrade: string): boolean;
+/** Queues bringing a fallen hero back */
+export declare function enqueueRevive(world: World, building: Entity, heroId: number): boolean;
+/**
+ * Queues upgrading a building into a type it can become (`UnitTypeDef.upgradesTo`): `into`, one of them, or the first
+ * where none is named. One at a time
+ */
+export declare function enqueueMorph(world: World, building: Entity, into?: string): boolean;
+export declare function cancelProduction(world: World, building: Entity, index: number): boolean;
+export declare const productionSystem: System;
+/** A unit made, to those who see it */
+export declare const toldTrained: import("..").ReplicatedEvent;
+/** Research done: to its side */
+export declare const toldResearched: import("..").ReplicatedEvent;
+/** A building starting to become another, to those who see it */
+export declare const toldUpgradeStarted: import("..").ReplicatedEvent;

package/dist/systems/productionQueue.d.ts

@@ -0,0 +1,40 @@
+import type { Entity, ProductionItem, ProductionState } from '#engine/entity';
+import type { World } from '#engine/world';
+import type { EntityState, ProductionInfo, QueueItemState } from '#engine/session/protocol';
+/**
+ * What a building makes (`UnitTypeDef.trains`, `researches`, `upgradesTo`, `revives`): its queue, and where what comes
+ * out goes. Set as it is spawned (and as its type changes), for a type that makes anything. Its owner and their allies
+ * are told the queue and the rally point; everyone who sees it how far it is in turning into another type
+ * (`ProductionInfo`)
+ *
+ * @beta
+ */
+export declare const productionQueue: import("#engine/components").Component<ProductionState, ProductionInfo>;
+/**
+ * What a building makes, and where it goes: none for a type that makes nothing (`productionQueue`)
+ *
+ * @beta
+ */
+export declare const productionOf: (entity: Entity) => ProductionState | undefined;
+/**
+ * What a building in a snapshot makes, the first being made: empty for one that makes nothing, or another's (a
+ * screen's, a computer player's view)
+ *
+ * @beta
+ */
+export declare const queueOf: (state: EntityState) => readonly QueueItemState[];
+/**
+ * The type a building in a snapshot is turning into, and how far, 0..1: undefined for one that is not
+ *
+ * @beta
+ */
+export declare function upgradeOf(state: EntityState): {
+    to: string;
+    progress: number;
+} | undefined;
+/** What a building had queued, given back: the money paid, a hero no longer coming back, research no longer under way */
+export declare function giveBack(world: World, building: Entity, item: ProductionItem): void;
+/** Gives back everything a building had queued, for when it is destroyed */
+export declare function cancelAllProduction(world: World, building: Entity): void;
+/** A building's becoming another called off, to those who see it */
+export declare const toldUpgradeCancelled: import("..").ReplicatedEvent;

package/dist/systems/victory.d.ts

@@ -0,0 +1,14 @@
+import type { System } from '#engine/registry';
+import type { World } from '#engine/world';
+/** Puts a player out of the game: they are told, and see the whole map from then on */
+export declare function defeat(world: World, playerId: number): void;
+/**
+ * The rule of a melee game: whoever has no building left is out, and the last team in the game wins.
+ * Players only take part once they have had a building, so a world with nothing but a few units
+ * in it, like most tests, has no losers. Game modules with other ways to win bring their own system.
+ *
+ * @beta
+ */
+export declare const lastTeamStanding: System;
+/** Whether the player's team won, lost or plays on (`Snapshot.outcome`): an observer neither wins nor loses */
+export declare const outcomePart: import("..").SnapshotPart<keyof import("..").Snapshot>;

package/dist/talk.d.ts

@@ -0,0 +1,65 @@
+import type { PlayerId } from './entity';
+import type { Registry } from './registry';
+import type { Vec2 } from './math';
+import type { World } from './world';
+/**
+ * When each player's last ones of each kind went out (`ping:1`, the world's times): the world's, and saved with it, so
+ * that a player who used up the limit is still refused in the game loaded from a save, as in the game that went on
+ */
+export declare const sent: import("./components").Component<Record<string, number[]>, Record<string, number[]>>;
+/**
+ * Whether a player may send another of a kind now: and counts it, when they may
+ *
+ * @beta
+ */
+export declare function allowed(world: World, player: PlayerId, kind: string, limit: {
+    most: number;
+    within: number;
+}): boolean;
+/**
+ * The kinds of ping hero arena games have: a game's are its rules' (`GameRules.talk.pings.kinds`), `look` first
+ *
+ * @beta
+ */
+export declare const PING_KINDS: readonly ['look', 'danger', 'assist', 'onMyWay'];
+/**
+ * A kind of ping: one of `GameRules.talk.pings.kinds`
+ *
+ * @beta
+ */
+export type PingKind = string;
+/**
+ * The kinds of ping a game's rules let go (`GameRules.talk.pings.kinds`), as they are now: its list, or what it works
+ * out from the registry (a file of the game's the editor writes)
+ *
+ * @beta
+ */
+export declare function pingKinds(registry: Registry): readonly string[];
+/**
+ * A player marks a spot of the map (`pinged`) for their allies (`to: 'allies'`, when left out) or for everyone
+ * (`'all'`): told to them and to who watches, as sessions do. Of a kind the game's rules have
+ * (`GameRules.talk.pings.kinds`), as many in a while as they let (`GameRules.talk`), and as the `beforeTalk` hook lets it,
+ * which may change who hears it
+ *
+ * @beta
+ */
+export declare function ping(world: World, player: PlayerId, point: Vec2, kind?: string, to?: string, by?: string): void;
+/**
+ * Who a line of chat or a ping is for: the player's side, everyone in the game, or who watches alone (`observers`:
+ * what one who watches says, which no player hears; a host gives every line of theirs this, `SessionHost`)
+ *
+ * @beta
+ */
+export type ChatAudience = 'allies' | 'all' | 'observers';
+/**
+ * A player says a line (`chatted`): to their side, or to everyone, and to who watches either way. Spaces run
+ * together, and cut to the game's length (`GameRules.talk`); nothing for an empty line, a message for too many in a
+ * while; and as the `beforeTalk` hook lets it, which may change the words or who hears them
+ *
+ * @beta
+ */
+export declare function chat(world: World, player: PlayerId, text: string, to?: string, by?: string): void;
+/** A ping: to everyone where it is to all, else to the pinger's side; one who watches pinged, to who watches */
+export declare const toldPing: import("./replication").ReplicatedEvent;
+/** A line of chat: to everyone where it is to all, else to the speaker's side; one who watches said it, to who watches */
+export declare const toldChat: import("./replication").ReplicatedEvent;

package/dist/tech.d.ts

@@ -0,0 +1,62 @@
+import { type Entity, type PlayerId } from './entity';
+import type { World } from './world';
+import { type Message } from './messages';
+/**
+ * Types of the finished buildings a player has, with what those count as
+ *
+ * @beta
+ */
+export declare function techOf(world: World, player: PlayerId): Set<string>;
+/**
+ * What of a list of requirements a player does not have
+ *
+ * @beta
+ */
+export declare function missing(world: World, player: PlayerId, requires: string[] | undefined, tech?: Set<string>): string[];
+/**
+ * Checks requirements and tells the player what is missing. True when there is nothing in the way
+ *
+ * @beta
+ */
+export declare function meets(world: World, player: PlayerId, requires: string[] | undefined): boolean;
+/**
+ * Why a player may not make something as far as what it requires goes, or nothing: the finished buildings it
+ * requires, and then the `requirement` hook (see `Requirement`). For a unit or structure type, or a level of research
+ *
+ * @beta
+ */
+export declare function unlockRefusal(world: World, player: PlayerId, kind: 'unit' | 'upgrade', id: string, requires: string[] | undefined, level?: number): Message | undefined;
+/**
+ * Checks that something is the player's to make at all (`isAvailable`: their race, the `available` hook), then what it
+ * requires, by `unlockRefusal`, and tells the player what stands in the way. True when nothing does
+ *
+ * @beta
+ */
+export declare function unlocked(world: World, player: PlayerId, kind: 'unit' | 'upgrade', id: string, requires: string[] | undefined, level?: number): boolean;
+/**
+ * Turns an entity into another type, where it stands: a building upgraded, a unit transformed (a druid into a bear, a
+ * siege tank set up). Everything of the type is the new one's: stats, how it moves (and on the ground or in the air),
+ * whether it fights, gathers or carries, its abilities (those of the old type it keeps are kept as they were, at their
+ * levels and cooldowns), and what it makes. What it went through stays: health lost, mana, buffs, experience, items.
+ * The parts of the game it had none of are given it as `spawn` gives them (`Component.onSpawn`), and the `morphed` hook
+ * runs: what a pack gives it of its own for its new type (the heroes pack: a hero's level, a shop's wares)
+ *
+ * @beta
+ */
+export declare function morph(world: World, entity: Entity, into: string): void;
+/** What became another, to those who see it */
+export declare const toldMorphed: import("./replication").ReplicatedEvent;
+/**
+ * What the `requirement` hook decided for a player, where it is not what the requirements say: what their screen could
+ * not work out for itself (`PlayerState.own.unlocks`). Nothing where the hook agrees with them all
+ *
+ * @beta
+ */
+export declare function decidedUnlocks(world: World, player: PlayerId): Record<string, Message | null> | undefined;
+/**
+ * What the `available` hook decided for a player, where it is not what their race says: what their screen could not
+ * work out for itself (`PlayerState.own.availability`). Nothing where the hook agrees
+ *
+ * @beta
+ */
+export declare function decidedAvailability(world: World, player: PlayerId): Record<string, boolean> | undefined;

package/dist/techTree.d.ts

@@ -0,0 +1,38 @@
+import type { Registry } from './registry';
+/**
+ * A thing of a tech tree: a unit or building type, or an upgrade, on its tier (0: made from the start)
+ *
+ * @beta
+ */
+export interface TechNode {
+    id: string;
+    kind: 'unit' | 'building' | 'upgrade';
+    name: string;
+    tier: number;
+    /** The race it is of, where it says */
+    race?: string;
+}
+/**
+ * How one thing of a tech tree leads to another: `from` makes `to` (trains, builds, hires, researches, upgrades to),
+ * or `to` requires `from`
+ *
+ * @beta
+ */
+export interface TechEdge {
+    from: string;
+    to: string;
+    kind: 'trains' | 'builds' | 'hires' | 'researches' | 'upgradesTo' | 'requires';
+}
+/**
+ * The tech tree of a game's rules: its things that are made or make something (scenery and the map's creeps left
+ * out), the edges between them, and each one's tier. Tiers go by what makes what from what nothing makes and from the
+ * buildings that make the builders, require nothing and are no other's upgrade (a hall; else, where everything is
+ * made of something, the buildings that require nothing, are no upgrade and make something),
+ * each thing after what it requires; a loop of requirements stops at the number of things
+ *
+ * @beta
+ */
+export declare function techTree(registry: Pick<Registry, 'units' | 'upgrades'>): {
+    nodes: TechNode[];
+    edges: TechEdge[];
+};

package/dist/terrain.d.ts

@@ -0,0 +1,173 @@
+import { type Vec2 } from './math';
+/** @beta */
+export interface TerrainMesh {
+    positions: Float32Array;
+    indices: Uint32Array;
+}
+/**
+ * What covers a cell: nothing, water that can be waded through, or water nothing on foot crosses
+ *
+ * @beta
+ */
+export declare const WATER_NONE = 0;
+/** @beta */
+export declare const WATER_SHALLOW = 1;
+/** @beta */
+export declare const WATER_DEEP = 2;
+/**
+ * Water and paint of a terrain, next to its shape. Left out for plain ground
+ *
+ * @beta
+ */
+export interface TerrainSurface {
+    /** `WATER_*` per cell, row by row */
+    water?: Uint8Array;
+    /** Height of the surface of the water per vertex, for drawing it. Only means something around wet cells */
+    waterHeights?: Float32Array;
+    /** What the ground is painted with per cell, row by row. 0 is left to the slope, what the rest are is up to the client */
+    tiles?: Uint8Array;
+    /** What scenery keeps off each cell (`BLOCKS_BUILD`, `BLOCKS_WALK`), row by row: see `MapDoodad.blocks` */
+    blocked?: Uint8Array;
+    /** The game's own layers of cells (`CellLayerDef`), by id: a value per cell, row by row */
+    cells?: Record<string, Uint8Array>;
+}
+/**
+ * Heightfield ground. World space spans [0, width] x [0, depth] with one height sample per unit.
+ * Rendering, navigation and the simulation all read from this same data.
+ *
+ * Next to the height, every cell has a level: the ground floor is 0, each cliff up is one more. The height is
+ * what things stand on and where the eye sees a cliff, the level is what the rules go by: who sees whom
+ * and who shoots uphill. Ramps belong to the lower level until halfway up.
+ *
+ * @beta
+ */
+export declare class Terrain {
+    readonly width: number;
+    readonly depth: number;
+    readonly heights: Float32Array;
+    readonly vertsX: number;
+    readonly vertsZ: number;
+    /** Level per cell, row by row. The fog works out what is seen from them once: `world.fog.levelsChanged()` after writing to them in a running world */
+    readonly levels: Uint8Array;
+    /** `WATER_*` per cell, row by row */
+    readonly water: Uint8Array;
+    /** Height of the surface of the water per vertex */
+    readonly waterHeights: Float32Array;
+    /** Paint per cell, row by row */
+    readonly tiles: Uint8Array;
+    /** What scenery keeps off each cell, row by row: 1 building there, 2 walking and building (see `MapDoodad.blocks`) */
+    readonly blocked: Uint8Array;
+    /**
+     * The game's own layers of cells, by id (`CellLayerDef`): where the bushes are, what burns. A value per cell, row by
+     * row; a layer nobody has painted is not there, and reads 0 everywhere (`cellAt`)
+     */
+    readonly cells: Record<string, Uint8Array>;
+    /**
+     * The part of the map play happens in, in cells, when it is not all of it (`GameMap.bounds`): nothing on foot goes
+     * outside it, nothing is built there, and the camera keeps to it. The edge beyond is scenery
+     */
+    bounds?: {
+        x: number;
+        z: number;
+        width: number;
+        depth: number;
+    };
+    constructor(width: number, depth: number, heights: Float32Array, levels?: Uint8Array, surface?: TerrainSurface);
+    /** The value of a layer of cells (`cells`) at a point: 0 off the ground, or where the layer is not there */
+    cellAt(layer: string, x: number, z: number): number;
+    /** A layer of cells, made empty when it is not there yet */
+    cellLayer(layer: string): Uint8Array;
+    /**
+     * Becomes another terrain, of whatever size, in place: what holds on to this one (the camera, what draws the ground)
+     * sees the new one. For the editor, when a map is resized
+     */
+    replace(other: Terrain): void;
+    /** Whether a cell is in the part of the map play happens in (`bounds`) */
+    inPlay(cx: number, cz: number): boolean;
+    /** `WATER_*` of the cell a point is in */
+    waterAt(x: number, z: number): number;
+    vertexHeight(ix: number, iz: number): number;
+    /** Level of the cell a point is in */
+    levelAt(x: number, z: number): number;
+    contains(x: number, z: number): boolean;
+    /** Height at any point, interpolated over the same triangles `buildMesh` produces. */
+    heightAt(x: number, z: number): number;
+    /** Surface normal (unnormalized y is always positive). */
+    normalAt(x: number, z: number, out: {
+        x: number;
+        y: number;
+        z: number;
+    }): void;
+    /** Steepness in radians, 0 = flat. */
+    slopeAt(x: number, z: number): number;
+    /** First intersection of a ray with the ground, or null. */
+    raycast(ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, maxDist?: number): {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
+    /** @param walkable leaves out what nothing on foot may cross, for the navigation */
+    buildMesh(walkable?: boolean): TerrainMesh;
+    /** Whether any cell is deep water: what boats go on */
+    get hasDeepWater(): boolean;
+    /**
+     * The deep water as a mesh, at its surface: where what goes on water can go (`UnitTypeDef.naval`). Under a bridge
+     * too. Empty where the map has no deep water
+     */
+    buildWaterMesh(): TerrainMesh;
+    /** The height of the water's surface at a point, over the same triangles as the ground */
+    waterHeightAt(x: number, z: number): number;
+}
+/**
+ * A way up a plateau
+ *
+ * @beta
+ */
+export interface RampSpec {
+    /** The ramp comes down on the side of the plateau that faces this point */
+    towards: Vec2;
+    /** How wide it is, in world units */
+    width?: number;
+}
+/**
+ * High ground: a roughly round area lifted by whole levels, with cliffs all around except where a ramp leads up
+ *
+ * @beta
+ */
+export interface PlateauSpec {
+    x: number;
+    z: number;
+    radius: number;
+    /** How many levels it rises above what is around it. One when left out */
+    levels?: number;
+    ramps?: RampSpec[];
+}
+/** @beta */
+export interface TerrainGenOptions {
+    width: number;
+    depth: number;
+    seed: number;
+    /** Height of the rolling hills */
+    hillHeight?: number;
+    /** Size of the hills in world units */
+    hillScale?: number;
+    /** Steep unwalkable rock formations */
+    rocks?: {
+        x: number;
+        z: number;
+        radius: number;
+        height: number;
+    }[];
+    /** Areas levelled to a constant height, for bases */
+    flats?: {
+        x: number;
+        z: number;
+        radius: number;
+    }[];
+    /** High ground with cliffs and ramps */
+    plateaus?: PlateauSpec[];
+    /** How much higher one level stands than the one below */
+    cliffHeight?: number;
+}
+/** @beta */
+export declare function generateTerrain(options: TerrainGenOptions): Terrain;

package/dist/terrainSave.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A terrain as plain data: in a save, and sent to a remote player as the game starts
+ *
+ * @beta
+ */
+export interface TerrainSave {
+    width: number;
+    depth: number;
+    /**
+     * Each layer as packed bytes (see `packBytes`), or, where every cell holds the same, that value: a map without water
+     * or cliffs, of one ground, says so in a few characters rather than a few hundred thousand
+     */
+    heights: string | number;
+    levels: string | number;
+    water: string | number;
+    waterHeights: string | number;
+    tiles: string | number;
+    /** What scenery keeps off each cell. Left out by saves from before there was any */
+    blocked?: string | number;
+    /** The game's layers of cells (`Terrain.cells`), by id, as the other layers. Left out when there are none */
+    cells?: Record<string, string | number>;
+    /** The part of the map play happens in, when it is not all of it */
+    bounds?: {
+        x: number;
+        z: number;
+        width: number;
+        depth: number;
+    };
+}

package/dist/testing.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `@v12-engine/engine/testing`: what a game's tests are written with. A world runs in a test as it does in a page, with no
+ * screen: these make one, step it and give its units orders, so that a test says what happens in the game and little
+ * else.
+ *
+ *     const world = await testWorld(myGame.rules)
+ *     const knight = world.spawn('knight', 1, { x: 10, z: 10 })
+ *     order(world, [knight], { type: 'move', point: { x: 30, z: 10 } })
+ *     run(world, 5, () => knight.pos.x > 29)
+ */
+import type { Entity } from './entity';
+import { type GameModule } from './game';
+import type { PlayerInit } from './player';
+import type { Logger } from './log';
+import type { OrderInit } from './registry';
+import { Terrain } from './terrain';
+import type { World } from './world';
+/**
+ * Flat ground, `size` cells a side: 48 when left out
+ *
+ * @beta
+ */
+export declare const flatTerrain: (size?: number) => Terrain;
+/**
+ * The players of a test world, when a test says none: a neutral one, and two who are enemies
+ *
+ * @beta
+ */
+export declare const TEST_PLAYERS: PlayerInit[];
+/**
+ * A small world of a game for a test: flat ground, a neutral player and two enemies (`TEST_PLAYERS`), the same every
+ * time (seed 7). Each of them is the test's to say otherwise
+ *
+ * @beta
+ */
+export declare function testWorld(game: GameModule, options?: {
+    terrain?: Terrain;
+    size?: number;
+    players?: PlayerInit[];
+    seed?: number;
+    log?: Logger;
+}): Promise<World>;
+/**
+ * Steps the world for up to `seconds`, stopping early once `until` holds. Returns the time that went by in it
+ *
+ * @beta
+ */
+export declare function run(world: World, seconds: number, until?: () => boolean): number;
+/**
+ * Gives units an order, as their owner would: taken up at the next tick. `queue` adds it after what they are doing
+ *
+ * @beta
+ */
+export declare const order: (world: World, entities: Entity[], init: OrderInit, queue?: boolean) => void;
+export { fixtureGame, fixtureMap } from './fixture';
+export { type BrainResults, type ComputerMeasures, defineSimulation, playGame, type Counted, type SimulatedGame, type SimulateOptions, simulate, type Simulation, winRates } from './simulate';
+export { brainOf, checkComputerSave, type ComputerWatch, type DecisionRecorder, type DecisionsApart, expectDecision, type FairPlay, fairPlay, type RecordedDecision, recordDecisions, thinkOnce, watchComputer, type WatchOptions } from './aiTesting';
+export { type Apart, checkDeterminism, type DeterminismOptions, type DeterminismReport, type Difference, firstDifference, worldFingerprint, worldHash, worldState } from './determinism';