@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/defs.d.ts

@@ -0,0 +1,1162 @@
+import type { AbilityAiView } from './ai/micro';
+import type { AiHints } from './ai/roles';
+import type { AbilityTextContext, AbilityValueDef, TextSegment } from './abilities/text';
+import type { EntityState } from './session/protocol';
+/**
+ * Static game data. Everything a game module (melee, custom map, mod) defines about
+ * its units lives in plain objects like these, the engine never hardcodes a unit.
+ */
+import type { GameRules } from './rules';
+import type { AbilityState, BuffInstance, Entity } from './entity';
+import type { Vec2 } from './math';
+import type { World } from './world';
+/**
+ * A value that can grow with the level of an ability: one number, or one per level
+ *
+ * @beta
+ */
+export type Scaled = number | number[];
+/**
+ * The value at a level. Levels past the end of the list get the last one
+ *
+ * @beta
+ */
+export declare function at(value: Scaled | undefined, level: number, fallback?: number): number;
+/**
+ * The stats the engine reads: what a unit has of health, mana and their regeneration, how it moves, sees and attacks,
+ * and its armor and magic resist (the two kinds of damage there are besides true). Levels, items, buffs and research
+ * change them. A game adds stats of its own with `GameModule.stats`, a pack its own (`GamePack.stats`: the MOBA
+ * stats of `withMobaStats`).
+ *
+ * @beta
+ */
+export interface CoreStats {
+    /** What a basic attack deals, before the armor of the target */
+    attackDamage: number;
+    /** Attacks per second */
+    attackSpeed: number;
+    /** Measured between the edges of attacker and target */
+    attackRange: number;
+    health: number;
+    /** Against physical damage: 100 of it halve what arrives */
+    armor: number;
+    /** The same against magic damage */
+    magicResist: number;
+    /** Per second */
+    healthRegen: number;
+    mana: number;
+    /** Per second */
+    manaRegen: number;
+    /** Units per second. Who has none cannot move */
+    moveSpeed: number;
+    /** How far it sees. At night the unit type says how far that is */
+    sight: number;
+}
+/**
+ * All of a unit's stats: the engine's, and the game's own by their ids
+ *
+ * @beta
+ */
+export type Stats = CoreStats & Record<string, number>;
+/**
+ * A stat: one of the engine's (`CoreStatKey`), or one a game defined. Checked when the game is built
+ *
+ * @beta
+ */
+export type StatKey = string;
+/**
+ * A stat of a game's own, next to the engine's
+ *
+ * @beta
+ */
+export interface StatDef {
+    id: string;
+    name: string;
+    /** Shown when the pointer is over it */
+    description?: string;
+    /** What every unit has of it unless its type says. 0 when left out */
+    default?: number;
+    /** It never goes below or above these, whatever changes it */
+    min?: number;
+    max?: number;
+    /** How it is shown: a whole number, a decimal, or a part of one as a percentage. A whole number when left out */
+    format?: 'number' | 'decimal' | 'percent';
+}
+/** @beta */
+export declare const noStats: () => CoreStats;
+/**
+ * How the days go by. Hours run from 0 to 24
+ *
+ * @beta
+ */
+export interface DayCycle {
+    /** Seconds a whole day and night take */
+    length: number;
+    /** Hour of the day the game starts at */
+    start: number;
+    /** Hour the sun comes up */
+    dawn: number;
+    /** Hour it goes down */
+    dusk: number;
+}
+/**
+ * Hour of the day after so many seconds of play. Noon in a game without days
+ *
+ * @beta
+ */
+export declare function hourOf(day: DayCycle | null, seconds: number): number;
+/** @beta */
+export declare const isNight: (day: DayCycle | null, hour: number) => boolean;
+/**
+ * Something that changes stats: `stats` is added, `percent` makes them bigger or smaller by a part of what
+ * they are with everything added. Parts from different places add up: two times +10% are +20%.
+ *
+ * @beta
+ */
+export interface StatChange {
+    stats?: Partial<Stats>;
+    percent?: Partial<Stats>;
+}
+/**
+ * A change that grows with the level of the ability it comes from
+ *
+ * @beta
+ */
+export interface ScaledStatChange {
+    stats?: Partial<Record<StatKey, Scaled>>;
+    percent?: Partial<Record<StatKey, Scaled>>;
+}
+/**
+ * Physical damage is held off by armor, magic damage by magic resist, true damage by nothing
+ *
+ * @beta
+ */
+export type DamageType = 'physical' | 'magic' | 'true';
+/**
+ * What makes a unit a hero: it gains levels, grows with them and learns abilities
+ *
+ * @beta
+ */
+export interface HeroDef {
+    /** What every level after the first adds */
+    growth: StatChange;
+    /** Abilities the hero can put points into */
+    learns: string[];
+    /** Abilities it has from the start and does not learn: the two spells every hero brings along. No mana, and nothing shortens their cooldown */
+    spells?: string[];
+    /** The level it stops at. 10 when left out */
+    maxLevel?: number;
+    /** A buff whose stacks are shown next to its health and mana, as so many points out of as many as it can have */
+    meter?: string;
+    /**
+     * Its primary attribute, in a game with the attributes pack (`withAttributes`): each point of it adds to its attack
+     * as well. `AttributesOptions.primaryOf` says it in code
+     */
+    primary?: 'strength' | 'agility' | 'intelligence';
+}
+/** @beta */
+export type EntityKind = 'unit' | 'building' | 'resource';
+/**
+ * Where something is: on the ground, or above it
+ *
+ * @beta
+ */
+export type Layer = 'ground' | 'air';
+/**
+ * The stats an attack reads how hard, how fast and how far it hits from (`AttackDef.stats`): the unit's
+ * `attackDamage`, `attackSpeed` and `attackRange` for what is left out
+ *
+ * @beta
+ */
+export interface AttackStats {
+    /** What a hit deals, before the armour of the target. `attackDamage` when left out */
+    damage?: StatKey;
+    /** Hits a second. `attackSpeed` when left out */
+    speed?: StatKey;
+    /** How far it reaches, between the edges. `attackRange` when left out */
+    range?: StatKey;
+}
+/**
+ * One of the ways a unit attacks (`UnitTypeDef.attacks`): what it hits, how its blow lands. How hard, how fast and how
+ * far are stats: the unit's `attackDamage`, `attackSpeed` and `attackRange`, or stats of the game's own that the attack
+ * names (`stats`: a second weapon's)
+ *
+ * @beta
+ */
+export interface AttackDef {
+    /**
+     * The stats its numbers are, by id: a stat of the game's (`GameModule.stats`) for a weapon whose damage, speed or
+     * range is not the unit's first's. What changes those stats (research, items, buffs) changes this attack alone
+     */
+    stats?: AttackStats;
+    /** Physical when left out */
+    damageType?: DamageType;
+    /** Seconds from the start of the swing until damage lands (or the projectile leaves), at the attack speed the unit starts with */
+    damagePoint: number;
+    /** Enemies closer than this are attacked automatically */
+    acquisitionRange: number;
+    /**
+     * How near is too near, edge to edge: what is closer than this the attack does not hit (a siege weapon's dead zone).
+     * Another of the unit's attacks takes over there where one reaches (`GameRules.combat.pickAttack`); with none, a unit
+     * told to attack steps back out of it first, and one left to itself does not pick what is that near. None when left out
+     */
+    minRange?: number;
+    /**
+     * Fires as the unit walks (a horse archer, a tank's turret): told to move, it hits what it passes within the attack's
+     * range without stopping or turning to it, at the attack's speed. Every other order fights as any attack does
+     * (it stops to). Not when left out
+     */
+    onTheMove?: boolean;
+    /** Set for ranged attacks */
+    projectileSpeed?: number;
+    /**
+     * What this attack can hit: kinds of things, and where they are. Everything on the ground when left out.
+     * What flies is only hit by attacks that name `air`, and an attack that names `air` alone does not hit the ground
+     */
+    targets?: (EntityKind | Layer)[];
+    /**
+     * Radius around the point of impact in which everyone is hit, friends too: in full in the inner half, by half further out.
+     * Shots of such an attack land where they were aimed, they do not follow their target
+     */
+    splash?: number;
+    /** Can be told to attack a spot on the ground */
+    ground?: boolean;
+    /** Brings down what is `fellable` in the area it hits */
+    fells?: boolean;
+    /**
+     * How what this attack kills dies, for the screen (`'shot'`, `'crushed'`, `'burnt'`): the death's `how`, which the
+     * view shows its way (`UnitLook.death`). A word, or one decided for each blow. The `death` hook has the last say
+     */
+    how?: string | ((hit: {
+        attacker: Entity;
+        target?: Entity;
+        damage: number;
+        type: DamageType;
+        crit: boolean;
+        tags?: readonly string[];
+    }) => string | undefined);
+    /**
+     * The attack's type against the target's armour type, by the game's damage table (`GameRules.combat.damageTable`): `pierce`,
+     * `siege`… Left out, the attack is multiplied by nothing
+     */
+    attackType?: string;
+}
+/**
+ * The id of a resource, as its game module defines it (`ResourceDef`)
+ *
+ * @beta
+ */
+export type ResourceKind = string;
+/**
+ * Something players have amounts of and pay with, like gold, lumber or crystals. A game module lists its own
+ *
+ * @beta
+ */
+export interface ResourceDef {
+    id: ResourceKind;
+    name: string;
+    /** What every player starts a game with. Nothing when left out */
+    start?: number;
+    /** What workers gather of it is cut by the upkeep of the army, see `UpkeepTier` */
+    upkeep?: boolean;
+}
+/**
+ * What something costs: an amount of each resource it takes, by resource id. What is left out costs nothing
+ *
+ * @beta
+ */
+export type Cost = Record<ResourceKind, number>;
+/** @beta */
+export interface UnitTypeDef {
+    id: string;
+    name: string;
+    /**
+     * The definition this one is a copy of, made from the data (`copyOf` in a `data.json`, the editor's Copy as new):
+     * what it is drawn, heard and pictured as where the game gives it no look of its own
+     */
+    basedOn?: string;
+    kind: EntityKind;
+    /** Collision radius */
+    radius: number;
+    /** Size in grid cells. Required for buildings and resources */
+    footprint?: {
+        w: number;
+        d: number;
+    };
+    /** What it starts with. What is left out is 0, a critical strike is worth 175% */
+    stats: Partial<Stats> & {
+        health: number;
+    };
+    /** Mana it comes into the world with. All of it when left out */
+    initialMana?: number;
+    /** Vision radius by day */
+    sight: number;
+    /** Vision radius at night. A part of the one by day when left out */
+    sightNight?: number;
+    /** Flies: over cliffs, trees and buildings, out of reach of whatever cannot hit the air */
+    flying?: boolean;
+    /**
+     * Goes on deep water and nowhere else: a boat. Sent onto land, it goes to the water nearest where it was sent. On
+     * the ground, as far as what can hit it goes
+     */
+    naval?: boolean;
+    /**
+     * A waygate, in a game with the portals pack (`withPortals`): a unit told to it walks in and is at once where it
+     * leads (its `waygate` field, a point of the map; `setWaygate` in code)
+     */
+    waygate?: boolean;
+    /**
+     * Rocks, a barricade, a gate to break down, in a game with the destructibles pack (`withDestructibles`): it stands in
+     * the way as any building does until it is brought down, and any unit whose attack reaches it attacks it when told
+     * to, never of its own accord
+     */
+    destructible?: boolean;
+    /**
+     * Carries others: a boat, a wagon. Units of its side get in by being told to (right-clicking it), are out of the
+     * world while in, and get out on the land nearest it (the `unload` order). It takes `capacity` of them, of the
+     * kinds `takes` says (every unit that walks when left out). What it carries dies with it
+     */
+    /**
+     * Carries others: a boat, or a building they go into (a garrison). `takes` says who may get in; `armed`, for a
+     * building with an attack, is the attack damage each one inside adds, and it attacks only while someone is inside,
+     * as an orc burrow does. What a building holds comes out when it falls; what a boat holds goes down with it
+     */
+    transport?: {
+        capacity: number;
+        takes?: (def: UnitTypeDef) => boolean;
+        /** Attack damage each one inside adds; or in code, all of what they add, by who is inside (none for nobody) */
+        armed?: number | ((world: World, building: Entity, inside: Entity[]) => number);
+    };
+    /** Radians per second */
+    turnRate?: number;
+    /**
+     * How it attacks, as the classic RTS two weapons: against each target the first that reaches it (its `targets`), or
+     * the one the game picks (`GameRules.combat.pickAttack`). It swings one at a time: a hit's cooldown is that attack's,
+     * whichever swings next. None for what does not attack
+     */
+    attacks?: AttackDef[];
+    hero?: HeroDef;
+    /** How dangerous it is, for creeps. Shown to the player, and added up per camp */
+    level?: number;
+    /** Gold for whoever kills it, rolled between the two */
+    bounty?: [min: number, max: number];
+    /**
+     * Whether it leaves a corpse when it dies, for spells to use (see `raiseDead`). Units do, unless this says no:
+     * machines, spirits. Decided for each death in code: false for none, true or seconds for one (how long it lies)
+     */
+    corpse?: boolean | ((world: World, entity: Entity) => boolean | number);
+    /**
+     * Immune to spells: abilities do not touch it, of friends or enemies, unless they say they get through
+     * (`piercesImmunity`). Decided in code whenever it is asked: while it stands on holy ground. The player's screen only
+     * knows the plain `true` of it, to grey out a target; the simulation goes by the code
+     */
+    spellImmune?: boolean | ((world: World, entity: Entity) => boolean);
+    /** Experience heroes get for killing it. Follows from its cost when left out */
+    xp?: number;
+    /** Building types the player has to have before this can be built or trained */
+    requires?: string[];
+    /**
+     * The race it is of (`GameModule.races`): only its players may build or train it. Everyone's when left out: creeps,
+     * what is shared. What a player may have is the game's to change (the `available` hook)
+     */
+    race?: string;
+    /** Building types this one counts as, for requirements. A keep is a town hall too */
+    provides?: string[];
+    /**
+     * Type this building can be upgraded into, where it stands; or the types, for one that may become one of several (a
+     * keep that turns into a castle or a citadel, `upgradesOf`). The first is what an upgrade is into where none is named
+     */
+    upgradesTo?: string | string[];
+    /** Slots for items. Heroes have six */
+    inventory?: number;
+    /** Items this building sells */
+    sells?: string[];
+    /**
+     * Units it hires out to whoever has one of theirs there, by type: a tavern's heroes, a dock's boats. Their cost,
+     * and a hero only once (see `hire`). Neutral, it hires to everyone
+     */
+    hires?: string[];
+    /**
+     * What it may leave behind when it dies, each with its chance from 0 to 1. Or code: the items it leaves, decided as
+     * it dies (one random level-3 item; more for a stronger killer)
+     */
+    drops?: {
+        item: string;
+        chance: number;
+    }[] | ((world: World, entity: Entity, killer?: Entity) => string[]);
+    /** Brings fallen heroes back */
+    revives?: boolean;
+    /** Ids of the abilities the unit has */
+    abilities?: string[];
+    cost?: Cost;
+    /** Supply (food) it takes up for as long as it lives, and while it is being trained */
+    supply?: number;
+    /** What it takes of the game's other pools of supply, by name (`GameRules.supply.pools`): `{ command: 1 }` */
+    supplies?: Record<string, number>;
+    /** Seconds to build or train */
+    buildTime?: number;
+    supplyProvided?: number;
+    /** What it provides of the game's other pools of supply, by name (`GameRules.supply.pools`), once it stands finished */
+    suppliesProvided?: Record<string, number>;
+    harvester?: {
+        capacity: number;
+        gatherTime: number;
+        /**
+         * The kinds of resource it gathers: all of them when left out. The undead's acolytes gold and nothing else, ghouls
+         * lumber. The `canHarvest` hook has the last word (`canHarvest`)
+         */
+        kinds?: ResourceKind[];
+    };
+    /** Building types this unit can construct */
+    builds?: string[];
+    /** Unit types this building can train */
+    trains?: string[];
+    /** Upgrades that can be researched here */
+    researches?: string[];
+    /** Accepts harvested resources: all of them, or only the ones listed */
+    dropOff?: boolean | ResourceKind[];
+    /**
+     * Goes up on a resource of this kind, over it, of the same footprint: the undead's cursed gold mine. The resource is
+     * its owner's alone from then on (`canHarvest`); one that takes what is gathered there (`dropOff`) has its owner's
+     * workers gather at it from around it, handing in where they stand, as many at once as `gatherers` says. It goes
+     * down with the resource, which stands again where it is destroyed
+     */
+    builtOn?: ResourceKind;
+    /** Workers that gather at once at it, when it stands on a resource (`builtOn`): 5 when left out */
+    gatherers?: number;
+    /**
+     * Goes up on its own once it is put down, as the undead summon theirs: the builder is free at once, and nobody
+     * helps (`GameRules.production.buildRate` of one builder, all the way). The same as `construction: 'self'`
+     */
+    buildsItself?: boolean;
+    /**
+     * How it goes up once it is put down: with builders at it (`builder`, the more the faster, as `buildRate` says), on
+     * its own with the builder free at once (`self`, the undead's), or whole at once (`instant`: a wall piece, a
+     * ward). `builder` when left out (`self` with `buildsItself`)
+     *
+     * @beta
+     */
+    construction?: 'builder' | 'self' | 'instant';
+    /**
+     * How fast it goes up with so many builders at it, 1 being one builder's: the game's rule (`GameRules.production.buildRate`) for
+     * every type when left out
+     *
+     * @beta
+     */
+    buildRate?: (builders: number, world: World, structure: Entity) => number;
+    resource?: {
+        kind: ResourceKind;
+        amount: number;
+        /** Workers that fit inside at once, for resources that are entered */
+        slots: number;
+        /** Workers go inside to gather, like into a gold mine, instead of working on it from next to it */
+        entered?: boolean;
+        /** Seconds a load takes, when that is not what the worker usually needs */
+        gatherTime?: number;
+    };
+    /** Key used in the command card when building or training this type */
+    hotkey?: string;
+    /** Higher values are picked first when acquiring targets */
+    threat?: number;
+    invulnerable?: boolean;
+    /** Takes damage like anything else but never dies of it: it is left with a little health, like something to practise on */
+    undying?: boolean;
+    /** Seconds after it was last hurt that it is whole again, all at once */
+    recovers?: number;
+    /** Nobody picks a fight with it on their own: it is only attacked when someone is told to */
+    ignored?: boolean;
+    /** Destroyed by attacks that fell, like a tree by a catapult, whatever else it withstands */
+    fellable?: boolean;
+    /**
+     * A piece of wall (`withWalls`): it joins with the pieces of its family beside it, and its shape (`single`, `end`,
+     * `straight`, `corner`, `tee`, `cross`) is its look. A gate (`gate`) joins as a piece does, turned along its line,
+     * and its owner opens and shuts it for everyone (`wallGateCommand`): its look `open` or `shut`. Pieces join by their
+     * footprints, so a gate wider than a cell sits in a line of pieces of one: one of a cell lets nobody through, the
+     * ground about a wall being kept off by the radius of what walks (a gatehouse of 3 by 3 lets through what is 1 wide) @beta
+     */
+    wall?: {
+        family: string;
+        gate?: boolean;
+    };
+    /** Seconds it lasts before it is gone by itself, like a ward */
+    lifetime?: number;
+    /** Enemies cannot see it, `after` seconds after it came into the world, unless something reveals it to them */
+    invisible?: {
+        after?: number;
+    };
+    /** Goes down after this many attacks and spells, whatever they deal: its health counts hits */
+    hits?: number;
+    /**
+     * What the computer player takes it for (`AiHints`): its roles (`worker`, `hall`, `soldier`...), the game's words
+     * about it, what it answers. Declared where what the kit infers from the rest of the definition is wrong or cannot
+     * be known; inferred otherwise (`inferRoles` in `@v12-engine/engine/ai`)
+     */
+    ai?: AiHints;
+    /** Its armour type, the column of the game's damage table (`GameRules.combat.damageTable`): `light`, `heavy`, `fortified`… */
+    armourType?: string;
+}
+/**
+ * How an ability is aimed
+ *
+ * @beta
+ */
+export type AbilityTarget = 'none' | 'unit' | 'point' | 'direction' | 'passive';
+/**
+ * What every effect may say, whatever its type: who of what it reaches it applies to (`effectTargets`)
+ *
+ * @beta
+ */
+export interface EffectCommon {
+    /** Only hits what carries this buff */
+    ifBuff?: string;
+    /** Only hits heroes */
+    only?: 'heroes';
+    /** Only hits these kinds of things. Everything but resources when left out */
+    kinds?: EntityKind[];
+    /** Where what it hits has to be: on the ground, in the air. Both when left out */
+    layers?: Layer[];
+    /** Makes the effect hit everything around the point of impact. Required for auras, and the size of a missile */
+    radius?: Scaled;
+    /** Who an effect with a radius applies to. Follows from the kind of effect when left out */
+    affects?: 'enemies' | 'allies' | 'all';
+    /** Applies to the caster, wherever the ability was aimed */
+    on?: 'caster';
+}
+/**
+ * The fields the engine's effects read, by name: each type of effect has those of them it reads (`EffectTypes`, a
+ * `Pick` of these), and a game's own type picks of them or says its own
+ *
+ * @beta
+ */
+export interface EffectFields {
+    /** For `teleport`: where to, however far: the caster's side's home (`homeOf`), where it was aimed, or by its target */
+    to?: 'home' | 'point' | 'target';
+    amount?: Scaled;
+    /** Id of the buff to put on the targets */
+    buff?: string;
+    /** Unit type, for effects that bring one into the world */
+    unit?: string;
+    /** For `onHit`: only while the attacker carries this buff */
+    whileBuff?: string;
+    /** For `charged`: what happens when the ability is not charged */
+    otherwise?: EffectDef[];
+    /** For missiles: buildings and trees in its way stop it, without anything happening to them */
+    blocked?: boolean;
+    /** For `onKill`: only when it was an attack of the carrier that killed */
+    attack?: boolean;
+    /** For `refresh`: the ability that is ready again, when it is not the one the effect belongs to */
+    ability?: string;
+    /** For `dash`: how high the caster rises on the way, which makes it a leap. For whoever draws it */
+    leap?: number;
+    /**
+     * For a leap: how much higher than where it takes off the ground on its way may stand. What stands higher
+     * is a wall to it: it comes down in front of it. Over anything when left out
+     */
+    climb?: number;
+    /** Seconds the buff lasts, when that is different from its usual duration */
+    duration?: Scaled;
+    /**
+     * What the stats of the caster add to the amount: `{ abilityPower: 0.6 }` adds 60% of its ability power.
+     * `level` is for every level of the hero past the first
+     */
+    scaling?: Scaling;
+    /** For damage. Magic when left out */
+    damageType?: DamageType;
+    /** For damage: how what it kills dies, for the screen, over the ability's own `how` */
+    how?: string;
+    /** For missiles: seconds they take shape where they were cast before they set off. The caster is free to go */
+    delay?: Scaled;
+    /** For missiles: how fast they travel, in units per second, and how far */
+    speed?: number;
+    distance?: Scaled;
+    /** For missiles: how many are sent, spread over an angle in radians. What one of them hit the others pass by */
+    count?: Scaled;
+    spread?: number;
+    /** For missiles: flies after the unit the ability was cast on, and only hits that one */
+    homing?: boolean;
+    /** For missiles: flies to the spot the ability was aimed at and stops there, `distance` away at the most */
+    toPoint?: boolean;
+    /** For missiles: how far the team of the caster sees around it */
+    sight?: number;
+    /**
+     * What happens to what is hit. For missiles: everything they pass through. For `onHit`: the target of an attack.
+     * For `dash`: what is around where it ends. For `after`: what is there when the time is up. For `zone`: what is inside, over and over
+     */
+    effects?: EffectDef[];
+    /** For missiles that were not stopped, and for zones: what happens where and when they end */
+    onEnd?: EffectDef[];
+    /**
+     * For `after`: the name its arrival goes by for whoever draws it and plays its sound, where one ability sets off
+     * several that do not look alike: the last of a barrage. The ability's own when left out
+     */
+    impact?: string;
+    /** For missiles: goes on after it hit something. False for the ones that are used up by the first thing in their way */
+    pierce?: boolean;
+    /**
+     * For missiles: thrown, not shot. It goes `height` up in the middle of its way and comes down at its end, `time`
+     * seconds after it set off however far that is (`speed` otherwise). It flies over everything, and what is within
+     * its `radius` where it comes down is what it hits
+     */
+    arc?: {
+        height: number;
+        time?: number;
+    };
+    /**
+     * For missiles: where it would be done (it reached its target, was used up by what it hit, came down, or came to
+     * the end of its way) it springs on to the nearest thing it may hit within `range` that it has not hit yet, and
+     * flies after that one, `count` times. Every spring takes `falloff` of the amounts off what it does (0.25: a
+     * quarter less each time). Its `onEnd` is where it is done for good
+     */
+    bounce?: {
+        count: Scaled;
+        range: number;
+        falloff?: number;
+    };
+    /** For `buff`: adds one to how many of it the target carries instead of renewing it, up to what the buff allows */
+    stack?: boolean;
+    /** For `exchange`: the resource the caster's owner trades away, by id */
+    sell?: string;
+    /** For `exchange`: the resource the caster's owner trades for, by id */
+    buy?: string;
+    /** For `exchange`: how much of `buy` comes for each one of `sell` (0.5: 100 lumber for 50 gold) */
+    rate?: number;
+}
+/**
+ * The types of effect there are, each with the fields it reads: the engine's, and a game's own, added by declaration
+ * merging as it defines them (`declare module '@v12-engine/engine' { interface EffectTypes { arrowStun: { ... } } }`,
+ * with `defineEffect`)
+ *
+ * @beta
+ */
+export interface EffectTypes {
+    /** Hurts what it reaches: `amount`, with what of the caster's stats adds to it (`scaling`), of a type (magic when left out) */
+    damage: Pick<EffectFields, 'amount' | 'scaling' | 'damageType' | 'how'>;
+    /** Heals what it reaches, more for the caster's heal and shield power */
+    heal: Pick<EffectFields, 'amount' | 'scaling'>;
+    /** Gives mana to what it reaches */
+    mana: Pick<EffectFields, 'amount' | 'scaling'>;
+    /** Puts a buff on what it reaches: for its own time or `duration`, one more of it with `stack` */
+    buff: {
+        buff: string;
+    } & Pick<EffectFields, 'duration' | 'stack'>;
+    /** Sends a missile: how fast, how far, how many, and what it does to what it passes through and where it ends */
+    missile: Pick<EffectFields, 'speed' | 'distance' | 'count' | 'spread' | 'homing' | 'toPoint' | 'delay' | 'sight' | 'blocked' | 'pierce' | 'arc' | 'bounce' | 'effects' | 'onEnd'>;
+    /** A passive's buff on what is around the carrier, kept up by the ability system */
+    aura: {
+        buff: string;
+    };
+    /** Brings a unit of the caster's into the world where it landed, for `duration` seconds or for good */
+    spawn: {
+        unit: string;
+    } & Pick<EffectFields, 'duration'>;
+    /** Puts a buff on the caster for as long as it likes, or takes it off */
+    toggle: {
+        buff: string;
+    };
+    /** The caster's team sees the spot for a while */
+    reveal: Pick<EffectFields, 'duration'>;
+    /** A passive's: `effects` happen to the target of every attack of the carrier, while it carries `whileBuff` */
+    onHit: Pick<EffectFields, 'whileBuff' | 'effects'>;
+    /** The caster is ready to strike again at once */
+    resetAttack: object;
+    /** The caster is elsewhere at once, `distance` away at the most */
+    blink: Pick<EffectFields, 'distance'>;
+    /** The caster is elsewhere at once, however far (`to`) */
+    teleport: Pick<EffectFields, 'to'>;
+    /** The caster rushes to the spot (a leap with `leap`), and `effects` happen around where it ends */
+    dash: Pick<EffectFields, 'distance' | 'leap' | 'climb' | 'speed' | 'effects' | 'buff'>;
+    /** Throws what it reaches `distance` away from the caster */
+    knockback: Pick<EffectFields, 'distance' | 'speed' | 'leap'>;
+    /** An ability of the caster is ready again: `ability`, or the one the effect belongs to */
+    refresh: Pick<EffectFields, 'ability'>;
+    /** A passive's: `effects` happen around whoever the carrier kills (by an attack, with `attack`) */
+    onKill: Pick<EffectFields, 'attack' | 'effects'>;
+    /** A passive's: `effects` happen to the carrier whenever it casts */
+    onCast: Pick<EffectFields, 'effects'>;
+    /** `effects` when the ability went off charged, `otherwise` when it did not */
+    charged: Pick<EffectFields, 'effects' | 'otherwise'>;
+    /** `effects` happen at the spot, `delay` seconds from now */
+    after: Pick<EffectFields, 'delay' | 'effects' | 'impact'>;
+    /** For `duration` seconds `effects` happen to what is at the spot, over and over, and `onEnd` at the end */
+    zone: Pick<EffectFields, 'duration' | 'effects' | 'onEnd'>;
+    /** Finds what is invisible around the spot: the caster's team sees it for `duration` seconds */
+    detect: Pick<EffectFields, 'duration'>;
+    /** Raises `count` of the corpses around the spot as units of `unit`, for `duration` seconds or for good */
+    raiseDead: {
+        unit: string;
+    } & Pick<EffectFields, 'duration' | 'count'>;
+    /**
+     * Makes `count` copies of the target, for `duration` seconds: they deal `dealt` of its damage (a third when left out)
+     * and take `taken` times what they are dealt (twice when left out)
+     */
+    illusion: Pick<EffectFields, 'count' | 'duration'> & {
+        dealt?: number;
+        taken?: number;
+    };
+    /** Takes the buffs off what it reaches, and hurts what is summoned by `amount` */
+    dispel: Pick<EffectFields, 'amount'>;
+    /**
+     * Trades `amount` of a resource of the caster's owner (`sell`) for another (`buy`), `rate` of it for each one sold:
+     * a marketplace's (`presetMarket`, `exchange` in code). Nothing of it with less than `amount` to sell
+     */
+    exchange: {
+        sell: string;
+        buy: string;
+        rate: number;
+        amount: Scaled;
+    };
+    /**
+     * A tome's, in a game with the tomes pack (`withTomes`): what it reaches gains `gain` for good (a point of strength),
+     * a hero `xp` experience and `levels` levels
+     */
+    tome: {
+        gain?: StatChange;
+        xp?: number;
+        levels?: number;
+    };
+    /**
+     * Mana burn, in a game with its pack (`withManaBurn`): takes `amount` of the mana of what it reaches, and hurts it by
+     * as much as it took, times `ratio` (1 when left out), magic damage unless `damageType` says
+     */
+    manaBurn: Pick<EffectFields, 'amount' | 'scaling' | 'damageType'> & {
+        ratio?: number;
+    };
+    /**
+     * A town portal, in a game with the portals pack (`withPortals`): the caster and as many as `count` (12 when left out)
+     * of its own units within `radius` (7) of it are at once at its side's home nearest where it was aimed (`homeOf`)
+     */
+    townPortal: Pick<EffectFields, 'count'>;
+}
+/**
+ * One thing an ability does: its `type`, which picks the handler and says which fields it has (`EffectTypes`)
+ *
+ * @beta
+ */
+export type EffectDef = {
+    [K in keyof EffectTypes]: {
+        type: K;
+    } & EffectCommon & EffectTypes[K];
+}[keyof EffectTypes];
+/**
+ * An effect seen as any type may be, every field of the engine's by its name: for what reads effects of every type
+ * alike (an ability's tooltip numbers, the rules' check of what they name). A handler reads its own type's
+ * (`EffectOf`)
+ *
+ * @beta
+ */
+export type AnyEffect = {
+    type: keyof EffectTypes;
+} & EffectCommon & Partial<EffectFields>;
+/**
+ * An effect as any type may be (`AnyEffect`), its fields by name
+ *
+ * @beta
+ */
+export declare const anyEffect: (effect: EffectDef) => AnyEffect;
+/**
+ * An effect of one type
+ *
+ * @beta
+ */
+export type EffectOf<K extends keyof EffectTypes> = {
+    type: K;
+} & EffectCommon & EffectTypes[K];
+/**
+ * The ground an ability covers: what the player aims with, and what is shown when it goes off
+ *
+ * @beta
+ */
+export type AimShape = {
+    shape: 'circle';
+    radius: number;
+} | {
+    shape: 'line';
+    length: number;
+    width: number;
+}
+/** A fan from the caster: `angle` is how wide it opens, in radians */
+ | {
+    shape: 'cone';
+    length: number;
+    angle: number;
+};
+/** @beta */
+export interface AbilityDef {
+    id: string;
+    name: string;
+    /**
+     * How what its damage kills dies, for the screen (`'burnt'`, `'frozen'`, `'blasted'`): the death's `how`, which the
+     * view shows its way. A word, or one decided for each blow: by its level, its caster, what it hit. An effect's own
+     * (`EffectDef.how`) goes over it; the `death` hook has the last say
+     */
+    how?: string | ((hit: {
+        caster: Entity;
+        target: Entity;
+        level: number;
+        amount: number;
+    }) => string | undefined);
+    /**
+     * The definition this one is a copy of, made from the data (`copyOf` in a `data.json`, the editor's Copy as new):
+     * what it is drawn, heard and pictured as where the game gives it no look of its own
+     */
+    basedOn?: string;
+    /**
+     * What it does, in words: a template with values in braces, worked out for the caster as it is now ("Deals {damage}
+     * magic damage" shows "Deals 80 (50 + 60% ability power) magic damage"). The values are its own (`values`), or found
+     * in its effects: `damage`, `heal`, `shield`, `amount`, `duration`, `radius`, `range`, `cooldown`, `charges`, `refill`,
+     * `mana`, `count`, `distance` (see `abilityValues`)
+     */
+    description?: string;
+    /** Values of its own to put in its description, by name: an amount and what of the caster scales it, or worked out in code */
+    values?: Record<string, AbilityValueDef>;
+    /** What it does, said in code instead of `description`: words with `{values}` in them, or words and values already put together */
+    describe?: (context: AbilityTextContext) => string | TextSegment[];
+    hotkey?: string;
+    /**
+     * none: happens at once. unit, point: needs a target, and the caster walks into range of it.
+     * direction: goes off from where the caster stands, towards where it was aimed. passive: always on, cannot be cast
+     */
+    target: AbilityTarget;
+    /** What may be targeted, for abilities cast on a unit */
+    targets?: {
+        allies?: boolean;
+        enemies?: boolean;
+        self?: boolean;
+        kinds?: EntityKind[];
+        layers?: Layer[];
+        heroes?: boolean;
+    };
+    manaCost?: Scaled;
+    /** Health it costs, as a part of all the caster can have. It cannot be cast with less than that left */
+    healthCost?: Scaled;
+    /** Seconds before it can be used again */
+    cooldown?: Scaled;
+    /**
+     * Uses it holds, for one used so many times before it waits: `count` of them at the most, one more back every
+     * `refill` seconds while it holds fewer (shortened as the cooldown is). Each use spends one; with none left it is not
+     * ready. Its `cooldown`, where it has one, is then the time between two uses. Full when it is learned
+     */
+    charges?: {
+        count: Scaled;
+        refill: Scaled;
+    };
+    /** How far away the target may be */
+    range?: Scaled;
+    /** The target may be as far away as the caster's attacks reach, and `range` farther */
+    attackRange?: boolean;
+    /**
+     * What kind of thing it is, for those who can keep out of its way: a buff that `avoids` one of these
+     * lets nothing of the ability happen to who carries it. `ground` is for what comes out of the ground or along it
+     */
+    tags?: string[];
+    /** Levels a hero can put into it. 3 when left out */
+    maxLevel?: number;
+    /** Hero level needed for the first level of the ability. Ultimates ask for 6 */
+    requiresLevel?: number;
+    /** Hero levels between two levels of the ability. 2 when left out */
+    levelStep?: number;
+    /**
+     * Seconds between starting to cast and the effect. The caster stands still for as long and cannot be
+     * called away: what it is told to do in the meantime, it does right after. None when left out
+     */
+    castTime?: number;
+    /** Gets through a unit's immunity to spells (see `UnitTypeDef.spellImmune`), as an ultimate may. Or for the targets its function says */
+    piercesImmunity?: boolean | ((world: World, target: Entity) => boolean);
+    /** The ground it covers, when that is not what its effects say: see `aimOf` */
+    aim?: {
+        shape: 'circle';
+        radius: Scaled;
+    } | {
+        shape: 'line';
+        length: Scaled;
+        width: Scaled;
+    } | {
+        shape: 'cone';
+        length: Scaled;
+        angle: number;
+    };
+    /** Units use it on their own when they have nothing else to do. The player can switch this off */
+    autocast?: boolean;
+    /**
+     * A buff of the caster that charges the ability when it has as many stacks as it can: the ability shows it, its
+     * `charged` effects do their other thing, and casting it takes the buff away
+     */
+    charge?: string;
+    effects: EffectDef[];
+    /** What an ability that is cast does all the time besides, once it is learned: buffs, auras, `onHit` */
+    passive?: EffectDef[];
+    /**
+     * Autocast in code, for any kind of ability: where to use it now, or nothing. Asked when the unit has nothing to
+     * do, the ability is switched to autocast, ready and paid for. Without it, only abilities cast on a unit autocast,
+     * on the worst-off target their core effects would do good to
+     */
+    autoAim?: (world: World, caster: Entity, state: AbilityState) => {
+        target?: number;
+        point?: Vec2;
+    } | null | undefined;
+    /**
+     * How a computer player uses it, from what it sees (see `AiView`): where, or `null` for not now. What the engine
+     * works out from its core effects when it gives nothing; an ability of the game's own effects has to say
+     */
+    ai?: (view: AbilityAiView, caster: EntityState, level: number) => {
+        point: Vec2;
+        target?: number;
+    } | null | undefined;
+    /** How far away the target may be, in code: the range on high ground, say. `range` is what the screen shows */
+    rangeOf?: (world: World, caster: Entity, level: number) => number;
+    /** Seconds of the wind-up, in code: shortened by haste, say. `castTime` when left out */
+    castTimeOf?: (world: World, caster: Entity, level: number) => number;
+    /**
+     * Kept up once it went off: the caster stands, for `duration` seconds, doing it every `every` seconds (effects, or
+     * code), until it is done or interrupted (another order, a stun), when `interrupted` runs. An ice storm
+     */
+    channel?: {
+        duration: number | ((world: World, caster: Entity, level: number) => number);
+        every?: number;
+        effects?: EffectDef[];
+        run?: (world: World, caster: Entity, level: number, target: Entity | undefined, point: Vec2) => void;
+        interrupted?: (world: World, caster: Entity, level: number) => void;
+        /** What it does once kept up to the end, and only then: a recall's teleport home */
+        finished?: EffectDef[];
+        /** Broken off when the caster is hurt, as a recall is: any damage, from anyone */
+        breaksOnDamage?: boolean;
+    };
+}
+/**
+ * What the stats of the caster add to an amount. `level` is for every level of a hero past the first,
+ * `bonusAttackDamage` for the attack damage it has on top of what its type and its levels give it
+ *
+ * @beta
+ */
+export type Scaling = Partial<Record<StatKey | 'level' | 'bonusAttackDamage', Scaled>>;
+/**
+ * Something lasting on a unit that changes what it can do
+ *
+ * @beta
+ */
+export interface BuffDef extends ScaledStatChange {
+    id: string;
+    name: string;
+    /**
+     * The definition this one is a copy of, made from the data (`copyOf` in a `data.json`, the editor's Copy as new):
+     * what it is drawn, heard and pictured as where the game gives it no look of its own
+     */
+    basedOn?: string;
+    description?: string;
+    /** Seconds. Lasts until removed when left out */
+    duration?: number;
+    /** A debuff: by default it goes on enemies */
+    harmful?: boolean;
+    /** The unit cannot do anything. A function says so for one carrier, one moment */
+    stun?: boolean | BuffCheck;
+    /** Thrown into the air for as long as it lasts. Comes with a stun, the rest is for the eye */
+    airborne?: boolean;
+    /** Knocked down: it lies on the ground for as long as it lasts, and gets up at the end. For the eye, like `airborne` */
+    down?: boolean;
+    /** Brings what flies down: it counts as being on the ground, for whatever is aimed at it */
+    grounds?: boolean;
+    /**
+     * Its carrier is invisible to enemies for as long as it lasts, unless they find it (`detect`): a Wind Walk. A function
+     * says so for one carrier, one moment
+     */
+    invisible?: boolean | BuffCheck;
+    /** The unit cannot move from the spot. It can still fight and cast. A function says so for one carrier, one moment */
+    root?: boolean | BuffCheck;
+    /**
+     * The unit cannot use its abilities. What it carries and the spells every hero has still work. A function says
+     * which abilities it keeps it from (`(ability) => ability.tags?.includes('fire')`): the screen asks it too
+     */
+    silence?: boolean | ((ability: AbilityDef) => boolean);
+    /** Damage it takes in place of the unit, for as long as the buff lasts and there is something left of it */
+    shield?: Scaled;
+    /** What the stats of whoever gave the shield add to it */
+    shieldScaling?: Scaling;
+    /** The shield is as good as new once the unit has not been hurt for this many seconds */
+    recharge?: number;
+    /** Tags of abilities that do nothing to who carries it, for as long as it does: `ground` for someone up in the air */
+    avoids?: string[];
+    /** Who carries it does not attack while it lasts: burrowed, or disarmed. Or while its function says */
+    disarm?: boolean | BuffCheck;
+    /** Who carries it is immune to spells while it lasts, as an avatar is (see `UnitTypeDef.spellImmune`). Or while its function says */
+    spellImmune?: boolean | BuffCheck;
+    /**
+     * Whether a dispel takes it off (see the effect `dispel`). Yes when left out: no for what nothing should end early.
+     * Decided in code for each dispel: by who dispels it (`by`), its level
+     */
+    dispellable?: boolean | ((world: World, carrier: Entity, instance: BuffInstance, by: Entity) => boolean);
+    /** How many of it one unit can carry at most. What puts it on says whether it adds one (`stack`) */
+    maxStacks?: number;
+    /** What happens around who carried it when its time is up, in the name of who put it there. Not when it is taken off */
+    onEnd?: EffectDef[];
+    /** Its stats count once for every stack it has (`stacks`), rather than once: "each stack, -5% move speed" */
+    perStack?: boolean;
+    /**
+     * Stats of its own, worked out in code, on top of what it declares: "+2 armor for each ally near". Asked when the
+     * carrier's stats are added up, which is only when something they come from changed: what this depends on beyond
+     * the buff (allies near, the time) calls `invalidateStats` when it changes
+     */
+    change?: (world: World, carrier: Entity, instance: BuffInstance) => StatChange | undefined;
+    /**
+     * What happens when it is put on a unit that has it already. `strongest` (the default): the higher level wins,
+     * the longer among equals. `refresh`: the time starts over, the level the new one's. `perSource`: one of it for
+     * every unit that puts it on, each of its own (two poisons from two casters). `independent`: a new one every time.
+     * A function decides from the one there and the one coming: `replace` it, `renew` its time, `add` another, or `keep`
+     */
+    stacking?: 'strongest' | 'refresh' | 'perSource' | 'independent' | ((existing: BuffInstance, incoming: IncomingBuff) => 'replace' | 'renew' | 'add' | 'keep');
+    /** What happens as it is put on: effects in the name of who put it there (while they live), or code */
+    onApply?: EffectDef[] | BuffHandler;
+    /** What happens every `every` seconds while it lasts: effects in the name of who put it there (while they live), or code, which runs whoever is left */
+    onTick?: {
+        every: number;
+        effects?: EffectDef[];
+        run?: BuffHandler;
+    };
+    /** Code run when it comes off, run out (`expired`) or taken off. Not for the buffs of something that dies */
+    onRemove?: (world: World, carrier: Entity, instance: BuffInstance, expired: boolean) => void;
+}
+/** Whether a buff does what it says (stuns, roots) to one carrier, at this moment */
+export type BuffCheck = (world: World, carrier: Entity, instance: BuffInstance) => boolean;
+/** Code a buff runs on its carrier: as it is put on, or every so often */
+export type BuffHandler = (world: World, carrier: Entity, instance: BuffInstance) => void;
+/** A buff about to be put on, as a `stacking` function sees it */
+export interface IncomingBuff {
+    level: number;
+    /** Seconds */
+    duration: number;
+    /** Who puts it on, by id: 0 for nobody */
+    source: number;
+}
+/**
+ * Where an item is in a shop. The client's tiers, or a game's own (`GameView.shopTiers`)
+ *
+ * @beta
+ */
+export type ItemTier = 'consumable' | 'starter' | 'basic' | 'epic' | 'legendary' | (string & {});
+/** @beta */
+export interface ItemDef {
+    id: string;
+    name: string;
+    /** How good it is, 1 and up (campaign plan GP3): what an item table draws by (`{ level: 3 }`) */
+    level?: number;
+    /** Its kind of item, a word of the game's (`permanent`, `charged`, `powerup`): what an item table draws by too */
+    class?: string;
+    /**
+     * The definition this one is a copy of, made from the data (`copyOf` in a `data.json`, the editor's Copy as new):
+     * what it is drawn, heard and pictured as where the game gives it no look of its own
+     */
+    basedOn?: string;
+    description?: string;
+    cost: Cost;
+    /** Uses before it is gone. Items without charges stay */
+    charges?: number;
+    /** Id of the ability the item gives: using the item casts it, without mana */
+    ability?: string;
+    /** Id of an ability whose passive part works for whoever carries the item */
+    passive?: string;
+    /** Items it is made of. Those the buyer carries are used up and taken off the price, which is for all of it */
+    from?: string[];
+    /** Where it goes in a shop: consumable, starter, basic, epic, legendary */
+    tier?: ItemTier;
+    /** Applies for as long as the item is carried */
+    bonus?: StatChange;
+    /** How many a shop has at most, and the seconds it takes to get one back. As many as anyone wants when left out */
+    stock?: {
+        max: number;
+        restock: number;
+    };
+    hotkey?: string;
+    /**
+     * Used as it is picked up, by walking over it or by the order, and never carried: a rune, a tome. Its ability is cast by
+     * whoever picked it. In a game with the runes pack (`withRunes`, whose `powerUp` says it in code)
+     */
+    powerUp?: boolean;
+}
+/**
+ * A big army is paid for with income: past a certain supply, less arrives of what workers gather of the resources with `upkeep`
+ *
+ * @beta
+ */
+export interface UpkeepTier {
+    /** Applies when the player uses more supply than this */
+    above: number;
+    name: string;
+    /** Part of what is gathered that still arrives, 0..1 */
+    income: number;
+}
+/**
+ * What a level of research changes
+ *
+ * @beta
+ */
+export interface UpgradeEffect extends StatChange {
+    /** Unit types that benefit, or a function of the type. Everything the player owns when left out */
+    units?: string[] | ((def: UnitTypeDef) => boolean);
+}
+/**
+ * Research that improves a player's units for the rest of the game
+ *
+ * @beta
+ */
+export interface UpgradeDef {
+    id: string;
+    name: string;
+    /**
+     * The definition this one is a copy of, made from the data (`copyOf` in a `data.json`, the editor's Copy as new):
+     * what it is drawn, heard and pictured as where the game gives it no look of its own
+     */
+    basedOn?: string;
+    description?: string;
+    /** Paid for every level */
+    cost: Cost;
+    /** Seconds per level */
+    researchTime: number;
+    maxLevel?: number;
+    /** Building types needed, one list per level. Levels past the end of the list need nothing */
+    requires?: string[][];
+    /** The race it is of (`GameModule.races`): only its players may research it. Everyone's when left out */
+    race?: string;
+    hotkey?: string;
+    effects: UpgradeEffect[];
+    /**
+     * What it does besides stats, in code, to each unit of the player's: as a level is researched (to the units there
+     * are), and as a unit comes into the world while the player has it. Gives an ability, lets a unit hit what flies.
+     * Run again for every level: what it does is up to it to not do twice
+     */
+    apply?: (world: World, entity: Entity, level: number) => void;
+}
+/**
+ * The types a building can be upgraded into (`UnitTypeDef.upgradesTo`), as a list: one for most, none for one that
+ * turns into nothing
+ *
+ * @beta
+ */
+export declare const upgradesOf: (def: Pick<UnitTypeDef, 'upgradesTo'>) => readonly string[];
+/** @beta */
+export declare const footprintOf: (def: UnitTypeDef) => {
+    w: number;
+    d: number;
+};
+/**
+ * What base stats are worked out under: the rules of a game, and what its own stats start at. A `Registry` is one
+ *
+ * @beta
+ */
+export interface StatSource {
+    readonly rules: Readonly<GameRules>;
+    /** Every stat of the game at 0, its own at their default */
+    readonly statDefaults: Readonly<Stats>;
+}
+/**
+ * The stats a unit type starts with, all of them, in a game: `world.registry`, or `session.registry` on a player's
+ * screen. By day unless it says otherwise
+ *
+ * @beta
+ */
+export declare function baseStats(def: UnitTypeDef, game: StatSource, night?: boolean): Readonly<Stats>;
+/**
+ * The ground an ability covers at a level: a line for what it sends on its way, a circle for what hits an area.
+ * Undefined for abilities that are about one unit, or about nothing in particular.
+ *
+ * @beta
+ */
+export declare function aimOf(ability: AbilityDef, level: number): AimShape | undefined;