@v12-engine/engine 0.0.0-stage → 0.1.1

package/dist/packs.d.ts

@@ -0,0 +1,84 @@
+import type { AbilityDef, BuffDef, ItemDef, UnitTypeDef, UpgradeDef } from './defs';
+import { type GameData } from './gameData';
+import type { GameModule } from './game';
+import type { ModDef } from './mods';
+import type { RaceDef } from './races';
+import type { RulesInit } from './rules';
+/**
+ * A pack of content as its file has it (`packs/<id>/pack.json`): plain data, checked against the pack's schema
+ * (`@v12-engine/engine/schemas/pack.schema.json`) as it is read. Its definitions are added to the game's, or put in the place of those of the same id;
+ * then its `data` is laid over the whole as a `data.json` is (`withData`), and its `rules` over the game's
+ *
+ * @beta
+ */
+export interface PackFile {
+    /** Letters, digits, dots and dashes: what the game composed of it is called by (`melee+<id>`) */
+    id: string;
+    /** `major.minor.patch` */
+    version: string;
+    name?: string;
+    /** The game and the packs or mods it is made for, as a mod's (`ModDef.requires`) */
+    requires?: string[];
+    units?: UnitTypeDef[];
+    abilities?: AbilityDef[];
+    buffs?: BuffDef[];
+    items?: ItemDef[];
+    upgrades?: UpgradeDef[];
+    races?: RaceDef[];
+    /** The rules it changes, as data (`GameBuilder.rules`) */
+    rules?: RulesInit;
+    /** Values over the definitions, as a `data.json` has them (`GameData`): the editor's Data panel writes here for a pack */
+    data?: GameData;
+    /** What its units look like, as a `looks.json` has them: the client's to lay over the game's view */
+    looks?: Record<string, unknown>;
+}
+/**
+ * A mod made of a pack (`packFromJson`): the mod, and the pack's file it was made of
+ *
+ * @beta
+ */
+export interface PackMod extends ModDef {
+    readonly pack: PackFile;
+    /** The hash of the pack's bytes as they were read: kept with the game's mods, so the game's hash has it */
+    readonly hash: string;
+}
+/**
+ * Why a pack's file is not one, where it is first wrong
+ *
+ * @beta
+ */
+export declare class PackError extends Error {
+}
+/**
+ * Checks a pack's file as it is read (the schema's rules a loader needs: the pack's schema has all of them):
+ * its id and version, and that each list is of definitions with an id, once each. Throws `PackError` saying where
+ *
+ * @beta
+ */
+export declare function checkPack(json: unknown, where?: string): PackFile;
+/**
+ * Checks a pack's file against the pack's schema (`@v12-engine/engine/schemas/pack.schema.json`, made of `PackFile`):
+ * where it is first wrong, in words with its place (`units[2].stats.health: is a string, not a number`), or nothing
+ * for one that is right. A small reader of the schema, as far as it uses JSON Schema: what a page that loads packs
+ * fetches with them, so that a game without packs carries none of it
+ *
+ * @beta
+ */
+export declare function checkPackSchema(json: unknown, schema: object): string | undefined;
+/**
+ * Makes a mod of a pack's file (its text, or what was parsed of it): checked, then applying its definitions (each
+ * list in the order of its ids, a definition the game has put in its place), its `data` over the whole and its
+ * `rules`. Its hash, of the text as given, goes with the game's mods
+ *
+ * @beta
+ */
+export declare function packFromJson(json: string | unknown, where?: string): PackMod;
+/**
+ * Whether a game was made with packs, and which: those of the mods its composition kept a hash of, by id and version
+ *
+ * @beta
+ */
+export declare const packsOf: (game: Pick<GameModule, 'mods'>) => {
+    id: string;
+    version: string;
+}[];

package/dist/paths.d.ts

@@ -0,0 +1,51 @@
+import { type Vec2 } from './math';
+/**
+ * A spot, and the way it faces: where a wave comes in, where a hero stands, where a camera looks from
+ *
+ * @beta
+ */
+export interface Spot extends Vec2 {
+    /** Radians, the way entities face: 0 is along +z */
+    facing: number;
+}
+/**
+ * A line on the map, through points in order, with a width: a road, a patrol route, the way a wave walks. What the
+ * rules ask of one a game would otherwise write each time: how long it is, where along it something is, how far a
+ * point is from it, whether a point is on it
+ *
+ * @beta
+ */
+export declare class Path {
+    /** Its points, in order. Not to be changed: the path works out its length from them once */
+    readonly points: readonly Vec2[];
+    /** How wide it is: a point is on it when it is no more than half of this from its middle */
+    readonly width: number;
+    /** How far along the path each of its points is */
+    private readonly along;
+    constructor(
+    /** Its points, in order. Not to be changed: the path works out its length from them once */
+    points: readonly Vec2[], 
+    /** How wide it is: a point is on it when it is no more than half of this from its middle */
+    width: number);
+    /** How long it is, from its first point to its last */
+    get length(): number;
+    get start(): Vec2;
+    get end(): Vec2;
+    /**
+     * Where on the path something is that has gone `distance` along it from its start, facing the way it goes. Before
+     * the start is the start, past the end the end
+     */
+    at(distance: number): Spot;
+    /** The nearest point of its middle line to a point, and how far along the path that is */
+    nearest(point: Vec2): {
+        at: Vec2;
+        distance: number;
+        along: number;
+    };
+    /** How far a point is from the middle of the path */
+    distanceTo(point: Vec2): number;
+    /** Whether a point is on the path: no more than half its width from its middle */
+    contains(point: Vec2): boolean;
+    /** Whether the middle of a cell of the map is on the path: what it paints, and keeps clear */
+    containsCell(cx: number, cz: number): boolean;
+}

package/dist/plain.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A copy of a value that is plain data all the way down: numbers, text, lists and plain objects, which is what a
+ * file and a wire can carry. Throws when something in it is not (a `Map`, a class, a function), saying where:
+ * `what` is whose data it is ("Save", "Map"), `where` the path so far, `advice` what to do about it
+ *
+ * @beta
+ */
+export declare function plain(value: unknown, where: string, what: string, advice?: string): unknown;
+/**
+ * The plain data of a value, and the paths of what was left out of it for not being plain (`settings.economy.workersPer`):
+ * a plain object's fields each kept or left out, a list as a whole. For what keeps the data of something that may hold
+ * code beside it (a computer player's options)
+ */
+export declare function plainParts(value: unknown, where?: string): {
+    kept: unknown;
+    dropped: string[];
+};

package/dist/player.d.ts

@@ -0,0 +1,117 @@
+import { type Component, StateStore } from './components';
+import type { Registry } from './registry';
+import type { Cost, ResourceKind } from './defs';
+import type { PlayerId } from './entity';
+import type { World } from './world';
+/** @beta */
+export interface PlayerInit {
+    id: PlayerId;
+    name: string;
+    /** Players on the same team are allies and share vision */
+    team: number;
+    /** RGB, 0..1 */
+    color: [number, number, number];
+    /** What the player starts with, by resource id */
+    resources?: Purse;
+    /** Neutral players own things like gold mines. Nobody is hostile towards them */
+    neutral?: boolean;
+    /** The player the creeps belong to: hostile to everyone, and not someone who can win or lose */
+    creeps?: boolean;
+    /**
+     * The race they play (`GameModule.races`), or `random` for one drawn as the game starts. The game's first when left
+     * out, in a game with races; none for the neutral players and the creeps
+     */
+    race?: string;
+}
+/** @beta */
+export declare class Player {
+    readonly id: PlayerId;
+    readonly name: string;
+    /** Changed by `world.setTeam`, which the fog and everyone's sight follow */
+    team: number;
+    readonly color: [number, number, number];
+    readonly neutral: boolean;
+    readonly creeps: boolean;
+    /** The race they play (`raceOf`): changed by `setRace` only. None in a game without races */
+    race: string | undefined;
+    /** What the player has of each resource, by resource id */
+    readonly resources: Purse;
+    supplyUsed: number;
+    supplyCap: number;
+    /** The game's other pools of supply, by name (`GameRules.supply.pools`): what is used and the cap of each */
+    supplies: Record<string, {
+        used: number;
+        cap: number;
+    }>;
+    /** Has had a building, and with that something to lose */
+    established: boolean;
+    /** Out of the game */
+    defeated: boolean;
+    private readonly finished;
+    /** Bumped whenever a research finishes. Whatever is worked out from `upgrades` (like the stats of units) can check this to tell whether it still holds */
+    upgradesVersion: number;
+    /** Upgrades in some production queue right now */
+    readonly researching: Set<string>;
+    /** State of game modules and mods for this player, see `state` */
+    readonly states: StateStore;
+    constructor(init: PlayerInit);
+    /** Finished research: upgrade id to level. Changed through `setUpgrade` only, which keeps `upgradesVersion` honest */
+    get upgrades(): ReadonlyMap<string, number>;
+    /** State of a game module or a mod for this player: made from the component's default when first asked for */
+    state<T>(key: Component<T, unknown>): T;
+    setState<T>(key: Component<T, unknown>, value: T): void;
+    setUpgrade(upgrade: string, level: number): void;
+}
+/**
+ * Amounts of resources, by resource id: what a player has. A resource left out is none of it
+ *
+ * @beta
+ */
+export type Purse = Record<ResourceKind, number>;
+/**
+ * The resource a purse is short of for a cost, or undefined when it can afford it
+ *
+ * @beta
+ */
+export declare function shortOf(purse: Readonly<Purse>, cost: Cost | undefined): ResourceKind | undefined;
+/** @beta */
+export declare function pay(purse: Purse, cost: Cost | undefined): void;
+/**
+ * Gives back what something cost, or a part of it
+ *
+ * @beta
+ */
+export declare function refund(purse: Purse, cost: Cost | undefined, part?: number): void;
+/**
+ * Adds an amount of a resource
+ *
+ * @beta
+ */
+export declare function earn(purse: Purse, kind: ResourceKind, amount: number): void;
+/**
+ * What a player pays for, as `resourcesSpent` says it: a unit, an upgrade, a structure, a morph, a revive (production),
+ * an item, a hire, a repair, a trade at a market (`exchange`), or a game's own word
+ *
+ * @beta
+ */
+export type SpentOn = 'unit' | 'upgrade' | 'structure' | 'morph' | 'revive' | 'item' | 'hire' | 'repair' | 'trade' | (string & {});
+/**
+ * Has a player pay a cost, and says so (`resourcesSpent`, what the score counts as spent): `on` what, and its id. For a
+ * game's own purchases too, so that they count as the engine's do. The purse is not checked: `shortOf` first
+ *
+ * @beta
+ */
+export declare function spend(world: World, player: PlayerId, cost: Cost | undefined, on: SpentOn, id?: string): void;
+/**
+ * Gives a player back what something cost, or a part of it (`refund`), and says so (`resourcesSpent` with `refund`):
+ * what the score takes off what was spent
+ *
+ * @beta
+ */
+export declare function giveBack(world: World, player: PlayerId, cost: Cost | undefined, part: number, on: SpentOn, id?: string): void;
+/**
+ * What a cost asks of the game's money, see `Registry.currency`. Shops deal in that alone
+ *
+ * @beta
+ */
+export declare function currencyOf(registry: Registry, cost: Cost | undefined): number;

package/dist/portals.d.ts

@@ -0,0 +1,66 @@
+import { type Entity } from './entity';
+import { type Vec2 } from './math';
+import type { GamePack } from './packs/pack';
+import type { World } from './world';
+/**
+ * The portals pack's id
+ *
+ * @beta
+ */
+export declare const PORTALS = "core.portals";
+/**
+ * Where a waygate leads: a point of the map by its name (as the editor's field keeps it), or a place. A waygate without
+ * it, or with `null`, is shut
+ *
+ * @beta
+ */
+export declare const waygate: import("./components").Component<string | Vec2 | null, string | Vec2 | null>;
+/**
+ * A unit went through a waygate, or a town portal: told to everyone who sees either end, for a sound and a flash
+ *
+ * @beta
+ */
+export declare const portalUsed: import("./events").EventKey<{
+    entity: number;
+    from: Vec2;
+    to: Vec2;
+    gate?: number;
+}>;
+/**
+ * Where a waygate leads, or nothing for one that is shut or leads to a point the map does not have
+ *
+ * @beta
+ */
+export declare function waygateTarget(world: World, gate: Entity): Vec2 | undefined;
+/**
+ * Says where a waygate leads (a point of the map by its name, or a place), or shuts it (`null`): what the editor's
+ * "Leads to" field says of a placed one, in code. Any building can be made a waygate so
+ *
+ * @beta
+ */
+export declare function setWaygate(gate: Entity, to: string | Vec2 | null): void;
+/**
+ * Puts a unit somewhere at once, on the nearest ground it can stand on: what a waygate and a town portal do, for a game's
+ * own rules. Told to everyone (`portalUsed`)
+ *
+ * @beta
+ */
+export declare function portal(world: World, entity: Entity, to: Vec2, gate?: Entity): void;
+/**
+ * Takes a unit and as many as `count` of its owner's units within `radius` of it, nearest first, to its side's home
+ * nearest `near` (`homeOf`), spread around it: what the `townPortal` effect does, in code. Gives back who went, none
+ * when the side has no home
+ *
+ * @beta
+ */
+export declare function townPortal(world: World, caster: Entity, near: Vec2, radius?: number, count?: number): Entity[];
+/**
+ * Portals, as in classic RTS games: waygates (`UnitTypeDef.waygate`), which a unit told to (a right-click, as any building is
+ * walked up to) walks into and comes out of where the gate leads (the "Leads to" field of a placed one, a point of the
+ * map; `setWaygate` in code), and the `townPortal` effect (`EffectTypes.townPortal`), which takes the caster and its
+ * units around it to its side's home nearest where it was aimed (`homeOf`: the map's `home.<team>` point, or the
+ * nearest of its buildings). `portal` and `townPortal` do them in code
+ *
+ * @beta
+ */
+export declare function withPortals(): GamePack;

package/dist/prefabs.d.ts

@@ -0,0 +1,139 @@
+import { type Camp } from './camps';
+import { type AreaShape } from './areas';
+import type { Entity, PlayerId } from './entity';
+import { type Vec2 } from './math';
+import type { World } from './world';
+/** A unit or a building of a prefab, where it stands around the prefab's middle *
+ * @beta
+ */
+export interface PrefabObject {
+    type: string;
+    /**
+     * Whose: the player the prefab is spawned for (`'owner'`, the default), neutral, the creeps, or a player of the
+     * map's by id (a file's objects say the id they had; one that is a player's becomes `'owner'` as the file is read)
+     */
+    owner?: 'owner' | 'neutral' | 'creeps' | PlayerId;
+    x: number;
+    z: number;
+    /** Radians, the way entities face */
+    facing?: number;
+    scale?: number;
+    look?: string;
+    /** A name of its own, for the rules to find it by: made free where it is taken (a number added) */
+    name?: string;
+    /** 0..1 of its health, less than whole */
+    health?: number;
+    /** Structures: as a construction site */
+    underConstruction?: boolean;
+}
+/** A camp of creeps of a prefab *
+ * @beta
+ */
+export interface PrefabCamp {
+    x: number;
+    z: number;
+    units: string[];
+    name?: string;
+}
+/** An area the rules watch, of a prefab: its id gets the spawn's own suffix, so that two of one prefab are two areas *
+ * @beta
+ */
+export interface PrefabArea {
+    id: string;
+    shape: AreaShape;
+}
+/** A prefab inside a prefab: spawned with it, its middle where it says from the outer one's, turned and sized with it *
+ * @beta
+ */
+export interface PrefabInside {
+    /** The prefab's id */
+    prefab: string;
+    x: number;
+    z: number;
+    /** Radians, the way facings turn: on top of the outer prefab's turn */
+    facing?: number;
+    scale?: number;
+}
+/** What a prefab is made of, around its middle (0, 0) *
+ * @beta
+ */
+export interface PrefabContents {
+    objects?: PrefabObject[];
+    camps?: PrefabCamp[];
+    areas?: PrefabArea[];
+    /** Prefabs inside it, spawned with it (a prefab that holds itself, at any depth, is not spawned past the first) */
+    prefabs?: PrefabInside[];
+}
+/**
+ * A prefab of a game's own: what `world.spawnPrefab` puts down as one. Its contents as data, or made for the place
+ * and the world (a camp the stronger the farther from the starts)
+ *
+ * @beta
+ */
+export interface PrefabDef {
+    /** Shared by every game: give it a prefix of the game's (`'td.fortress'`) */
+    id: string;
+    name?: string;
+    contents: PrefabContents | ((at: Vec2, world: World) => PrefabContents);
+}
+/**
+ * Typed help for writing a prefab
+ *
+ * @beta
+ */
+export declare const definePrefab: (def: PrefabDef) => PrefabDef;
+/** How a prefab is spawned: where its middle goes, for whom, turned and sized *
+ * @beta
+ */
+export interface SpawnPrefabOptions {
+    at: Vec2;
+    /** The player the prefab's `'owner'` objects are spawned for: neutral when left out */
+    owner?: PlayerId;
+    /** Radians, the way facings turn: the prefab turned around its middle */
+    facing?: number;
+    scale?: number;
+    /** Parts left out, by their index in the prefab's lists: a gate without its towers */
+    without?: {
+        objects?: number[];
+        camps?: number[];
+        areas?: number[];
+        prefabs?: number[];
+    };
+}
+/** What a prefab spawned became *
+ * @beta
+ */
+export interface SpawnedPrefab {
+    entities: Entity[];
+    camps: Camp[];
+    /** The ids of the areas added */
+    areas: string[];
+}
+/**
+ * A prefab put down in the world as one: its objects spawned (`world.spawn`, for the owner given or as each says),
+ * its camps (`spawnCamp`: a world with camps seats the creeps, `PlayerInit.creeps`), its areas added under ids of
+ * their own; turned and sized around its middle as asked
+ *
+ * @beta
+ */
+export declare function spawnPrefab(world: World, prefab: PrefabDef | string, options: SpawnPrefabOptions): SpawnedPrefab;
+/**
+ * The id a part of a prefab inside another has in the outer one's copy, as the editor and `prefabsFrom` number it:
+ * made from the inner prefab's id there and the part's id in it (itself one of these, a level down), the same each
+ * time it is read; below zero, where a prefab's own parts (the map's ids they had) never are
+ *
+ * @beta
+ */
+export declare function nestedPartId(nested: number, id: number): number;
+/**
+ * The prefabs a designer made in the editor (`prefabs/<name>.prefab.json` of the game's folder), as prefabs of the
+ * game's, by their file names: `prefabsFrom(import.meta.glob('./prefabs/*.prefab.json', { eager: true }))`, or any
+ * record of name to file. An object of a player's becomes the owner's; scenery, points and paths are left out. A
+ * variant is read through its source and a prefab with prefabs inside through those, as the editor places them, from
+ * the files given
+ *
+ * @beta
+ */
+export declare function prefabsFrom(files: Record<string, unknown>, options?: {
+    prefix?: string;
+}): PrefabDef[];

package/dist/presetBuildings.d.ts

@@ -0,0 +1,52 @@
+import type { AbilityDef, UnitTypeDef } from './defs';
+/**
+ * A fountain: a building that keeps the game's aura on who is around it (`aura`, the id of a passive ability with an
+ * `aura` effect: a fountain of health's regeneration, a fountain of mana's). It cannot be hurt; a map puts it down
+ * for the neutral player, so the aura says `affects: 'all'` to reach everyone (the neutral player is nobody's ally).
+ * What is given over the fountain's own goes over it: `presetFountain('healingWaters', { id: 'fountainOfHealth' })`
+ *
+ * @beta
+ */
+export declare function presetFountain(aura: string, over?: Partial<UnitTypeDef>): UnitTypeDef;
+/**
+ * One trade of a marketplace (`presetMarket`): `amount` of `sell` for `rate` of `buy` for each one sold
+ *
+ * @beta
+ */
+export interface MarketRate {
+    /** The resource traded away, by id */
+    sell: string;
+    /** The resource traded for, by id */
+    buy: string;
+    /** How much of `buy` comes for each one of `sell`: 0.5 is 100 lumber for 50 gold */
+    rate: number;
+    /** How much is sold at a time: 100 when left out */
+    amount?: number;
+    /** The ability's id: `sell-<sell>-for-<buy>` when left out */
+    id?: string;
+    /** The ability's name: `Sell <sell> for <buy>` when left out */
+    name?: string;
+    /** The key the ability's button is pressed with */
+    hotkey?: string;
+}
+/**
+ * What `presetMarket` is given: the trades, and the seconds between two of each (none when left out)
+ *
+ * @beta
+ */
+export interface PresetMarketOptions {
+    /** The trades, an ability each, in the order of the buttons */
+    rates: readonly MarketRate[];
+    /** Seconds between two trades of each: none when left out */
+    cooldown?: number;
+}
+/**
+ * A marketplace's abilities: one for each trade (`MarketRate`), cast at once (`target: 'none'`), with an `exchange`
+ * effect that trades the caster's owner's resources at its rate. A building of the game's lists their ids in its
+ * `abilities` (`abilities: market.map((ability) => ability.id)`), the abilities go in the rules' `abilities`. With
+ * less than the amount to sell, the player is told and nothing goes. The computer player does not cast them in a
+ * fight (their `ai` says not now); its brain's `spells` may
+ *
+ * @beta
+ */
+export declare function presetMarket(options: PresetMarketOptions): AbilityDef[];

package/dist/presetGround.d.ts

@@ -0,0 +1,22 @@
+import { type CellLayerDef } from './cellLayers';
+import { type TileDef } from './tiles';
+/**
+ * Ready-made grounds a game takes or leaves, beside its own: the tiles of an RTS's ground (grass, dark grass, dirt,
+ * road, sand, rock, snow), which the client draws with its `TILE_LOOKS`, and the blight a race spoils ground with,
+ * which the client draws with its `blightLook`. They say only what there is; what they do is the game's
+ */
+/**
+ * The tiles of an RTS's ground, by the ids the client's `TILE_LOOKS` has looks for: `tiles: presetTiles` in the rules,
+ * `tiles: TILE_LOOKS` in the view. A game adds its own beside them, or takes some (`presetTiles.filter(...)`)
+ *
+ * @beta
+ */
+export declare const presetTiles: readonly TileDef[];
+/**
+ * Blight: ground spoiled, a layer of cells a map's maker paints and the rules spread (`world.setCells('blight', …)`),
+ * drawn by the client's `blightLook`. What it does (who builds on it, who heals on it) is the game's: melee's
+ * undead in the example
+ *
+ * @beta
+ */
+export declare const presetBlight: CellLayerDef;