@v12-engine/engine 0.0.0-stage → 0.1.0

package/dist/hooks.d.ts

@@ -0,0 +1,780 @@
+import type { ChatAudience } from './talk';
+import type { AbilityDef, BuffDef, Cost, DamageType, StatChange, Stats, UnitTypeDef } from './defs';
+import type { Camp } from './camps';
+import type { BuffInstance, Entity, EntityId, ItemInstance, Order, PlayerId } from './entity';
+import type { FormationDef } from './formation';
+import type { AreaDef } from './areas';
+import type { GameMap, MapCamp, MapObject, MapRegion } from './map';
+import type { Rect, Vec2 } from './math';
+import type { MessageRef } from './messages';
+import type { DeathCause, DeathReason, World } from './world';
+/**
+ * Hooks are how game modules and mods take part in what the engine does, while it does it: make an attack
+ * hit harder, keep a unit from dying, pay for a kill, refuse an order. A hook is a list of handlers that run
+ * in order, each getting the same event object; handlers before damage or death can change it or call it off.
+ *
+ * Events (`World.events`) are different: they tell whoever watches (a player's session, a test) what has
+ * happened, once the tick is over, and cannot change anything. Code that is part of the rules uses hooks.
+ */
+/**
+ * Damage about to be dealt, before armor and shields. Change `amount` or `type`, or set `cancelled`
+ *
+ * @beta
+ */
+export interface BeforeDamage {
+    readonly target: Entity;
+    readonly source?: Entity;
+    amount: number;
+    type: DamageType;
+    /** A basic attack, not an ability */
+    readonly attack: boolean;
+    readonly crit: boolean;
+    /** The ability that deals it, by id. Left out for a basic attack */
+    readonly ability?: string;
+    /** Words of the game's own about it, see `DamageOptions.tags` */
+    readonly tags?: readonly string[];
+    cancelled: boolean;
+}
+/**
+ * What a hit is multiplied by for the attack's type against the target's armour type (`GameRules.combat.damageTable`),
+ * before armour and shields: change `multiplier` to say otherwise. Asked only when the game has a table, or a hook
+ * of its own for it
+ */
+export interface DamageMultiplier {
+    readonly target: Entity;
+    readonly source?: Entity;
+    /** The attack's type, as the attack or the ability said it (`AttackDef.attackType`, `DamageOptions.attackType`) */
+    readonly attackType?: string;
+    /** The target's armour type (`UnitTypeDef.armourType`) */
+    readonly armourType?: string;
+    /** A basic attack, not an ability */
+    readonly attack: boolean;
+    multiplier: number;
+}
+/**
+ * Damage that was dealt. The target may have died of it
+ *
+ * @beta
+ */
+export interface AfterDamage {
+    readonly target: Entity;
+    readonly source?: Entity;
+    /** What came off its health, after armor and shields */
+    readonly dealt: number;
+    /** The part of that it had health for: overkill left out */
+    readonly taken: number;
+    readonly type: DamageType;
+    readonly attack: boolean;
+    readonly crit: boolean;
+    readonly ability?: string;
+    readonly tags?: readonly string[];
+}
+/**
+ * Health about to be given back. Change `amount`, or set `cancelled`
+ *
+ * @beta
+ */
+export interface BeforeHeal {
+    readonly target: Entity;
+    readonly source?: Entity;
+    amount: number;
+    cancelled: boolean;
+}
+/**
+ * Something is about to die. Set `prevented` to keep it alive: it is then up to the handler what health it has
+ *
+ * @beta
+ */
+export interface BeforeDeath {
+    readonly entity: Entity;
+    readonly killer?: Entity;
+    /** An attack of the killer did it */
+    readonly attack: boolean;
+    /** It ran out of health, rather than being removed by the rules (felled, expired, cancelled) */
+    readonly fromDamage: boolean;
+    /** The blow that did it, when it ran out of health */
+    readonly cause?: DeathCause;
+    /** Why it dies (`DeathReason`): `damage`, or what the rules said (`cancelled`, `expired`, a game's own word) */
+    readonly reason: DeathReason;
+    prevented: boolean;
+}
+/**
+ * Something dies. In `death` it still stands where it was; in `afterDeath` it is gone from the world
+ *
+ * @beta
+ */
+export interface Death {
+    readonly entity: Entity;
+    readonly killer?: Entity;
+    readonly attack: boolean;
+    /** The blow that did it, when it ran out of health: its damage type, the ability, how much too much */
+    readonly cause?: DeathCause;
+    /** Why it dies (`DeathReason`): `damage`, or what the rules said (`cancelled`, `expired`, a game's own word) */
+    readonly reason: DeathReason;
+    /**
+     * What the rules make of the death, for the screen (`'exploded'`, `'burned'`): what the blow says (`AttackDef.how`,
+     * `AbilityDef.how`) to start with, changed in the `death` hook as the game likes. The view gets it with the death
+     * (`SessionEvent` `death`) to show it its way (`UnitLook.death`). Nothing when left out
+     */
+    how?: string;
+}
+/**
+ * An order about to be given to a unit. Set `rejected` to refuse it
+ *
+ * @beta
+ */
+export interface BeforeOrder {
+    readonly entity: Entity;
+    readonly order: Order;
+    /** Added to the end of what it does, rather than in place of it */
+    readonly queued: boolean;
+    rejected: boolean;
+}
+/**
+ * How much a unit wants to attack something, as it looks for a target by itself. Higher is picked first:
+ * raise or lower `score`, or make it `-Infinity` to pass the target over. Towers of a tower defense go for
+ * the creep furthest along its way like this; a taunt makes everyone go for one unit.
+ *
+ * Runs for every candidate of every search, which is often: the same object is handed out again and again,
+ * so keep nothing of it.
+ *
+ * @beta
+ */
+export interface TargetScore {
+    attacker: Entity;
+    target: Entity;
+    /** Edge to edge */
+    distance: number;
+    /** Attackers like this one (its layer, its reach) the target has already, and how many it has room for (`GameRules.combat.engageRoom`) */
+    engaged: number;
+    room: number;
+    /** What the engine makes of it: things that fight back first, then the closest, and a full one only when nothing else is near */
+    score: number;
+}
+/**
+ * Where an attacker goes to fight a target from: its spot around it (see `engagement.ts`), or the target itself, in
+ * `point`, to change. A flank for cavalry, behind for assassins. Asked every time the target moves a little: keep it cheap
+ */
+export interface Approach {
+    readonly attacker: Entity;
+    readonly target: Entity;
+    point: Vec2;
+}
+/**
+ * An ally standing in a unit's way is asked to step aside, to `point` (see `GameRules.movement.makesWay`, `lookAhead`): change
+ * where it goes, or make it null to leave it standing. `mover` is on its way, heading the way of `direction`
+ *
+ * @beta
+ */
+export interface MakeWay {
+    readonly mover: Entity;
+    readonly other: Entity;
+    /** Where the mover is heading, a unit long */
+    readonly direction: Vec2;
+    point: Vec2 | null;
+}
+/**
+ * A unit is about to go round units standing in its way (`around`), by `point`, which is `longer` ground units more
+ * than the `straight` way to the next corner of its path (see `GameRules.movement.goesAround`): change the point, or make it
+ * null to have it go straight through, asking them aside. Asked as it comes up to them: keep it cheap
+ *
+ * @beta
+ */
+export interface Detour {
+    readonly entity: Entity;
+    readonly around: readonly Entity[];
+    readonly straight: number;
+    readonly longer: number;
+    point: Vec2 | null;
+}
+/**
+ * Units ordered to a point together have their places in a formation worked out (`FormationDef`, `formationPoints`):
+ * change any in `points`, by the unit's id, or add or remove some. `units` are those that walk, or those that fly:
+ * each is laid out apart
+ *
+ * @beta
+ */
+export interface Formation {
+    readonly units: readonly Entity[];
+    readonly target: Vec2;
+    readonly formation: FormationDef;
+    readonly points: Map<EntityId, Vec2>;
+}
+/**
+ * Whether a structure may be placed. Set `allowed` to false, with a `reason` the player is told
+ *
+ * @beta
+ */
+export interface CanPlace {
+    readonly def: UnitTypeDef;
+    /** The ground it would cover */
+    readonly site: Rect;
+    /** Who would build it. Left out when the engine asks for itself */
+    readonly player?: PlayerId;
+    allowed: boolean;
+    reason?: MessageRef;
+}
+/**
+ * An ability about to go off, before it is paid for. Change what it costs, or call it off with a `reason`.
+ * Whether the caster has the mana was already checked against the ability's own cost before it wound up:
+ * a lower cost here does not let it cast with less than that
+ *
+ * @beta
+ */
+export interface BeforeCast {
+    readonly caster: Entity;
+    readonly ability: AbilityDef;
+    readonly level: number;
+    readonly target?: Entity;
+    readonly point: Vec2;
+    /** What it is cast from, for an item's ability */
+    readonly item?: ItemInstance;
+    manaCost: number;
+    /** Seconds until it can be used again */
+    cooldown: number;
+    cancelled: boolean;
+    reason?: MessageRef;
+}
+/**
+ * An ability that went off
+ *
+ * @beta
+ */
+export interface AfterCast {
+    readonly caster: Entity;
+    readonly ability: AbilityDef;
+    readonly level: number;
+    readonly target?: Entity;
+    readonly point: Vec2;
+    readonly item?: ItemInstance;
+    /** It went off charged, and spent the charge */
+    readonly charged: boolean;
+}
+/**
+ * A buff about to be put on, or put on again. Change how long it lasts or how strong it is, or call it off (immunity)
+ *
+ * @beta
+ */
+export interface BeforeBuff {
+    readonly target: Entity;
+    readonly buff: BuffDef;
+    readonly source?: Entity;
+    level: number;
+    /** Seconds, after tenacity. Infinity for one that stays */
+    duration: number;
+    cancelled: boolean;
+}
+/**
+ * A buff that came off: it ran out (`expired`), or was taken off. Not called for the buffs of something that dies
+ *
+ * @beta
+ */
+export interface BuffEnd {
+    readonly entity: Entity;
+    readonly buff: BuffInstance;
+    readonly expired: boolean;
+}
+/** @beta */
+export type ProductionKind = 'unit' | 'upgrade' | 'morph' | 'revive' | 'structure';
+/**
+ * Something about to be made: a unit trained, an upgrade researched, a building upgraded, a hero brought back,
+ * a structure put down by a worker. Change what it costs and how long it takes, or call it off with a `reason`
+ *
+ * @beta
+ */
+export interface BeforeProduce {
+    readonly player: PlayerId;
+    /** The building it is made in, or the worker putting down a structure */
+    readonly producer: Entity;
+    readonly kind: ProductionKind;
+    /** Unit type, upgrade, the type a building becomes, the id of a hero, or a structure type */
+    readonly id: string;
+    cost: Cost;
+    /** Seconds it takes */
+    time: number;
+    cancelled: boolean;
+    reason?: MessageRef;
+}
+/** Every hook, and what its handlers get */
+/**
+ * A unit with nothing to do, this tick: no orders. Set `handled` and do what it does instead of what idle units do
+ * (fight back, go for enemies that come close, which is only for those that fight): a healer that goes to the
+ * wounded, a worker that goes back to work. Asked often: keep it cheap
+ *
+ * @beta
+ */
+export interface Idle {
+    readonly entity: Entity;
+    readonly dt: number;
+    /** Whether it fights by itself: it has an attack and is not told to stand down. The engine only does that */
+    readonly fights: boolean;
+    handled: boolean;
+}
+/**
+ * Whether an attacker may attack a target: what the engine makes of it (its attack's targets, whether they are
+ * enemies) is in `allowed`, to change. A buff that lets a unit hit what flies; a truce. Asked very often, the same
+ * object handed out again and again: keep nothing of it
+ */
+export interface CanAttack {
+    attacker: Entity;
+    target: Entity;
+    allowed: boolean;
+    /**
+     * Whether a player told the attacker to attack this one (an attack order): what a game lets of its own side, as a
+     * deny (`denying`). Never when a unit picks a target by itself or fights back, so nothing turns on its own side
+     * unless told: a unit looking for a target by itself is not asked about its own side's at all (they are passed over
+     * before the hook, as most of what stands around a unit in a crowd is its own)
+     */
+    ordered: boolean;
+}
+/**
+ * An attack going off, as the engine has it: change what it does, or call it off. `target` is left out for an attack
+ * at the ground. `splash` is the radius of an attack that hits an area; `projectileSpeed` 0 is a blow, more a shot
+ * (`look` what the shot looks like, for the screen). Damage, the critical strike and the miss are already rolled
+ */
+export interface BeforeAttack {
+    readonly attacker: Entity;
+    readonly target?: Entity;
+    readonly point: Vec2;
+    /** Which of the attacker's attacks goes off, by place (`UnitTypeDef.attacks`) */
+    readonly weapon: number;
+    damage: number;
+    type: DamageType;
+    crit: boolean;
+    miss: boolean;
+    splash?: number;
+    projectileSpeed: number;
+    look?: string;
+    /** Words of the game's own about it, which the damage carries, see `DamageOptions.tags` */
+    tags?: string[];
+    /** How what it kills dies, for the screen (`AttackDef.how`, worked out for this blow): changed as the game likes */
+    how?: string;
+    cancelled: boolean;
+}
+/**
+ * The stats of an entity being added up, once what the engine knows of (its type, levels, research, items, buffs) is
+ * in: `add` more, as a stat change (`{ stats: { armor: 2 } }`, `{ percent: { moveSpeed: 0.1 } }`). Asked only when
+ * something they come from changed: call `invalidateStats` when what a handler reads changes
+ */
+export interface StatsHook {
+    readonly entity: Entity;
+    /** What its type starts with */
+    readonly base: Readonly<Stats>;
+    add(change: StatChange, times?: number): void;
+}
+/**
+ * Whether an ability can be used now: what the engine makes of it (level, cooldown, mana, silence) in `refusal`, to
+ * clear ("free while Clearcasting") or to set ("not while carrying the flag"). The cost itself is `beforeCast`'s: one
+ * that is let through for free sets its `manaCost` to 0 there too. The player's screen is told what this decided for
+ * the abilities of their own units
+ */
+export interface CanCast {
+    readonly caster: Entity;
+    readonly ability: AbilityDef;
+    readonly level: number;
+    /** What it is used from, for an item's ability */
+    readonly item?: ItemInstance;
+    refusal?: MessageRef;
+}
+/**
+ * Whether an ability may be used on a target: what the engine makes of it (the ability's `targets`) in `refusal`, to
+ * clear ("can target allied buildings below half health") or to set. The screen only knows the declared targets: what
+ * this changes, the simulation says when the order comes
+ */
+export interface CanTarget {
+    readonly caster: Entity;
+    readonly ability: AbilityDef;
+    readonly target: Entity;
+    refusal?: MessageRef;
+}
+/**
+ * Whether a team sees an entity of someone else's: what the fog and invisibility make of it in `visible`, to change.
+ * Units in brush seen only from up close; a watchtower. Asked very often: keep it cheap
+ */
+export interface Visible {
+    readonly entity: Entity;
+    readonly team: number;
+    visible: boolean;
+}
+/**
+ * Whether a player may make something, as far as what it requires goes: a unit, a level of research (`level`), what a
+ * building upgrades to, a structure. What the engine makes of it (the finished buildings it requires: `missing`) is in
+ * `refusal`, to clear or set: "needs Blacksmith upgrade 2", "needs a level 5 hero", "locked until the objective". The
+ * player's screen is told what this decided, for what they could make
+ */
+export interface Requirement {
+    readonly player: PlayerId;
+    readonly kind: 'unit' | 'upgrade';
+    readonly id: string;
+    /** The level being researched, for an upgrade */
+    readonly level?: number;
+    /** Required building types the player does not have */
+    readonly missing: readonly string[];
+    refusal?: MessageRef;
+}
+/**
+ * Whether a player may make a unit type or research an upgrade at all, before what it requires (see `isAvailable`):
+ * by default (`available`), what is of no race or of theirs (`race`). Set it otherwise for a game's own way: what a
+ * mode takes away, a roster that grows as a campaign goes, a unit only one player may have. What is not available is
+ * not on the player's buttons, and an order for it is refused; their screen is told where this decided otherwise
+ *
+ * @beta
+ */
+export interface Available {
+    readonly player: PlayerId;
+    readonly kind: 'unit' | 'upgrade';
+    readonly id: string;
+    /** The race the player plays, if the game has races */
+    readonly race: string | undefined;
+    available: boolean;
+}
+/**
+ * A player about to ping the map or say a line (see `ping`, `chat`): change the words (`text`) or who hears them (`to`),
+ * or call it off: a muted player, a word filter, no talking in a cinematic. On the rules' side, for every screen alike
+ */
+export interface BeforeTalk {
+    readonly player: PlayerId;
+    readonly kind: 'ping' | 'chat';
+    /** A line's words */
+    text?: string;
+    /** Who a line or a ping is for */
+    to?: ChatAudience;
+    /** Where a ping is, and of what kind */
+    readonly point?: Vec2;
+    readonly pingKind?: string;
+    cancelled: boolean;
+}
+/**
+ * Resources about to be given to an ally (see `give`): change how much arrives (`received`), or call it off with a
+ * `reason`: no trading in the first minutes, a cap on what goes to one player
+ */
+export interface BeforeTrade {
+    readonly from: PlayerId;
+    readonly to: PlayerId;
+    readonly resource: string;
+    readonly sent: number;
+    received: number;
+    cancelled: boolean;
+    reason?: MessageRef;
+}
+/**
+ * A player is about to give up (see `surrender`): call it off with a `reason`, as a game that does not let them before a time
+ *
+ * @beta
+ */
+export interface BeforeSurrender {
+    readonly player: PlayerId;
+    cancelled: boolean;
+    reason?: MessageRef;
+}
+/**
+ * A player asks for a pause (see `askPause`): how many they have left before this one (`left`), and how long it lasts
+ * at most (`seconds`, which can be changed); call it off with a `reason`
+ *
+ * @beta
+ */
+export interface BeforePause {
+    readonly player: PlayerId;
+    readonly left: number;
+    seconds: number;
+    cancelled: boolean;
+    reason?: MessageRef;
+}
+/**
+ * A player's cap of a pool of supply, once what their buildings provide is added up (see the supply system): change
+ * `cap` (a starting amount, an upgrade, a rule of the game's own). The game's most (`GameRules.supply.max`, a pool's
+ * `max`) still holds after
+ *
+ * @beta
+ */
+export interface SupplyCap {
+    readonly player: PlayerId;
+    /** `supply` for the one there always is, or the name of one of the game's own (`GameRules.supply.pools`) */
+    readonly pool: string;
+    cap: number;
+}
+/**
+ * Whether a worker may gather from a resource: by default, a resource of a kind it gathers (`harvester.kinds`). Refuse
+ * it for a game's own rule: a mine only its owner's cursed mine stands on, a tree of a sacred grove. Asked when it is
+ * told to, and of every resource it would go on to by itself
+ *
+ * @beta
+ */
+export interface CanHarvest {
+    readonly worker: Entity;
+    readonly source: Entity;
+    allowed: boolean;
+    /** What the player is told when it is refused */
+    reason?: MessageRef;
+}
+/** Resources a worker hands in: change `amount` (more from mines near the keep), or call it off */
+export interface BeforeDeposit {
+    readonly worker: Entity;
+    readonly player: PlayerId;
+    readonly kind: string;
+    amount: number;
+    cancelled: boolean;
+}
+/** An item about to be bought at a shop: change what it costs, or call it off with a `reason` */
+export interface BeforeBuy {
+    readonly buyer: Entity;
+    readonly shop: Entity;
+    readonly item: string;
+    cost: Cost;
+    cancelled: boolean;
+    reason?: MessageRef;
+}
+/** An item about to be picked up off the ground (`ground` its id there): call it off with a `reason` */
+export interface BeforePickUp {
+    readonly entity: Entity;
+    readonly item: string;
+    readonly ground: number;
+    cancelled: boolean;
+    reason?: MessageRef;
+}
+/** An item about to be put down: call it off with a `reason` (a cursed blade) */
+export interface BeforeDrop {
+    readonly entity: Entity;
+    readonly item: ItemInstance;
+    cancelled: boolean;
+    reason?: MessageRef;
+}
+/** Experience about to go to a hero: change `amount` (the killer gets more), or make it 0. `from` is what was killed, when that is where it comes from */
+export interface BeforeXp {
+    readonly hero: Entity;
+    readonly from?: Entity;
+    amount: number;
+}
+/** Whether a hero may put a point into an ability: what the engine makes of it in `allowed`, to change. The screen hears of it with what the hero can learn */
+export interface CanLearn {
+    readonly hero: Entity;
+    readonly ability: string;
+    allowed: boolean;
+}
+/** Something was made: a unit trained (`unit`), research done (`level`), a building upgraded, a hero brought back */
+export interface Produced {
+    readonly producer: Entity;
+    readonly kind: ProductionKind;
+    readonly id: string;
+    readonly unit?: Entity;
+    readonly level?: number;
+}
+/**
+ * Something that has just become another type where it stands (`morph`): a building upgraded, a unit transformed. Its
+ * new type's parts are set (stats, abilities, slots, and every `Component.onSpawn` of a part it did not have yet): what
+ * a pack gives it of its own for the type it is now, as the heroes pack makes a hero of what became a hero's type and
+ * stocks what became a shop. Run before the `entityMorphed` event
+ *
+ * @beta
+ */
+export interface Morphed {
+    /** What changed type, as it is now */
+    readonly entity: Entity;
+    /** The type it was */
+    readonly from: string;
+}
+/**
+ * What was placed on a map, and the entity it has become
+ *
+ * @beta
+ */
+export interface FromMapObject {
+    readonly entity: Entity;
+    /** As the map has it: where, whose, its name */
+    readonly object: Readonly<MapObject>;
+    /** The game's own fields for it (see `defineMapField`), with what was not set at its default */
+    readonly data: Readonly<Record<string, unknown>>;
+}
+/**
+ * A camp that was placed on a map, and the camp it has become
+ *
+ * @beta
+ */
+export interface FromMapCamp {
+    readonly camp: Camp;
+    readonly from: Readonly<MapCamp>;
+    /** The game's own fields for camps, see `FromMapObject.data` */
+    readonly data: Readonly<Record<string, unknown>>;
+}
+/**
+ * Something that has died, before it leaves the world: whether it stays (`stays`), out of the world, in the world's
+ * entities, to be brought back. No when nothing says so; the heroes pack says yes for a hero (`withHeroes`), and a
+ * handler after it (a higher `priority`) can say no for a game where heroes fall for good
+ *
+ * @beta
+ */
+export interface FallenHero {
+    /** What died */
+    readonly entity: Entity;
+    /** What killed it, when something did */
+    readonly killer?: Entity;
+    /** Whether it stays, out of the world, to be brought back: no, unless a handler says yes */
+    stays: boolean;
+}
+/**
+ * A region of a map, and the area it has become
+ *
+ * @beta
+ */
+export interface FromMapRegion {
+    readonly area: AreaDef;
+    readonly region: Readonly<MapRegion>;
+    /** The game's own fields for regions, see `FromMapObject.data` */
+    readonly data: Readonly<Record<string, unknown>>;
+}
+/**
+ * A world made from a map, everything the map places in it there and every race's start done: what a pack or the game
+ * starts of its own from the map's data, as the map objectives pack gives the objectives a map gives at the start
+ * (`mapObjectives`). Not for a world loaded from a save, which has them already
+ *
+ * @beta
+ */
+export interface FromMap {
+    /** The map it was made from */
+    readonly map: Readonly<GameMap>;
+}
+/** @beta */
+export interface HookEvents {
+    beforeDamage: BeforeDamage;
+    damageMultiplier: DamageMultiplier;
+    afterDamage: AfterDamage;
+    beforeHeal: BeforeHeal;
+    beforeDeath: BeforeDeath;
+    death: Death;
+    afterDeath: Death;
+    /** Whether what died stays in the world's entities, out of the world, to be brought back (`FallenHero`). @beta */
+    fallenHero: FallenHero;
+    /**
+     * Something just made, its type's parts set (abilities, an inventory, an attack), not in the world yet: what a pack
+     * gives it of its own, as the heroes pack makes a hero of a hero's type (`makeHero`) and stocks a shop. @beta
+     */
+    made: Entity;
+    /** Something became another type where it stands (`morph`): what a pack gives it of its own for the new type (`Morphed`). @beta */
+    morphed: Morphed;
+    /** Something came into the world, and is in it now */
+    spawn: Entity;
+    /** Something left the world for good, at the end of the tick it died in */
+    remove: Entity;
+    beforeOrder: BeforeOrder;
+    targetScore: TargetScore;
+    approach: Approach;
+    makeWay: MakeWay;
+    detour: Detour;
+    formation: Formation;
+    canPlace: CanPlace;
+    beforeCast: BeforeCast;
+    afterCast: AfterCast;
+    beforeBuff: BeforeBuff;
+    buffEnd: BuffEnd;
+    beforeProduce: BeforeProduce;
+    idle: Idle;
+    canAttack: CanAttack;
+    beforeAttack: BeforeAttack;
+    stats: StatsHook;
+    canCast: CanCast;
+    canTarget: CanTarget;
+    visible: Visible;
+    requirement: Requirement;
+    available: Available;
+    beforeDeposit: BeforeDeposit;
+    canHarvest: CanHarvest;
+    beforeTalk: BeforeTalk;
+    beforeTrade: BeforeTrade;
+    beforeSurrender: BeforeSurrender;
+    supplyCap: SupplyCap;
+    beforePause: BeforePause;
+    beforeBuy: BeforeBuy;
+    beforePickUp: BeforePickUp;
+    beforeDrop: BeforeDrop;
+    beforeXp: BeforeXp;
+    canLearn: CanLearn;
+    produced: Produced;
+    /** Something placed on a map has become an entity, as the world is made from the map: what the game does with its own fields */
+    mapObject: FromMapObject;
+    /** A camp placed on a map is in the world, see `mapObject` */
+    mapCamp: FromMapCamp;
+    /** A region of a map is an area of the world, see `mapObject` */
+    mapRegion: FromMapRegion;
+    /** The world made from a map is all there, about to start (`FromMap`): what a pack starts from the map's own data. @beta */
+    mapStart: FromMap;
+}
+/** @beta */
+export type HookName = keyof HookEvents;
+/** @beta */
+export type HookHandler<K extends HookName> = (world: World, event: HookEvents[K]) => void;
+/**
+ * A hook of a game's own, made with `defineHookType`: a moment of its rules others can take part in, the way the
+ * engine's hooks are for its own
+ *
+ * @beta
+ */
+export interface HookKey<T> {
+    readonly id: string;
+    /** Only there for the type of the event */
+    readonly event?: T;
+}
+/**
+ * A hook of a game's own: `const lifeLost = defineHookType<{ invader: Entity; lives: number; cancelled: boolean }>('td.lifeLost')`.
+ * The game runs it where the moment is (`world.hooks.run(lifeLost, { ... })`) and reads back what the handlers made
+ * of the event; handlers are written with `defineHook({ hook: lifeLost, ... })`, by the game or by a mod on it.
+ * Ids are shared by every game: give them a prefix of the game's
+ *
+ * @beta
+ */
+export declare function defineHookType<T>(id: string): HookKey<T>;
+/**
+ * A hook: one of the engine's by name, or a game's own
+ *
+ * @beta
+ */
+export type AnyHook = HookName | HookKey<any>;
+/**
+ * A handler and the hook it is for. Its `id` is how others take it out or put something in its place
+ *
+ * @beta
+ */
+export type HookDef = {
+    hook: AnyHook;
+    id: string;
+    /** Lower runs first. 0 when left out; handlers with the same priority run in the order they were added */
+    priority?: number;
+    run: (world: World, event: any) => void;
+};
+/**
+ * Typed help for writing a hook: `defineHook({ hook: 'death', id: 'bounty', run(world, { entity }) { ... } })`
+ *
+ * @beta
+ */
+export declare function defineHook<K extends HookName>(def: {
+    hook: K;
+    id: string;
+    priority?: number;
+    run: HookHandler<K>;
+}): HookDef;
+/** @beta */
+export declare function defineHook<T>(def: {
+    hook: HookKey<T>;
+    id: string;
+    priority?: number;
+    run: (world: World, event: T) => void;
+}): HookDef;
+/**
+ * The handlers of every hook of one world
+ *
+ * @beta
+ */
+export declare class Hooks {
+    private readonly world;
+    private readonly lists;
+    constructor(world: World);
+    /** Adds a handler. One with the same id on the same hook is replaced */
+    add(def: HookDef): void;
+    remove(hook: AnyHook, id: string): void;
+    /** Whether a hook has any handlers. For hooks run very often, to not even put the event together when nobody listens */
+    has(hook: AnyHook): boolean;
+    /** Ids of the handlers of a hook, in the order they run */
+    handlers(hook: AnyHook): string[];
+    /** Runs the handlers of a hook on the event, in order, and hands the event back for the caller to read */
+    run<K extends HookName>(hook: K, event: HookEvents[K]): HookEvents[K];
+    run<T>(hook: HookKey<T>, event: T): T;
+}