@v12-engine/engine 0.1.1 → 0.4.0

package/dist/hooks.d.ts

@@ -1,13 +1,13 @@
 import type { ChatAudience } from './talk';
-import type { AbilityDef, BuffDef, Cost, DamageType, StatChange, Stats, UnitTypeDef } from './defs';
+import type { AbilityDef, BuffDef, Cost, DamageType, EffectDef, 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';
+import { type MessageRef } from './messages';
+import type { DeathCause, DeathReason, Missile, 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
@@ -17,39 +17,31 @@ import type { DeathCause, DeathReason, World } from './world';
  * 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`
+ * Damage about to be dealt, before armor and shields. Change `amount` or `type`, or `cancel()`
  *
  * @beta
  */
 export interface BeforeDamage {
+    /** The entity about to take the damage */
     readonly target: Entity;
+    /** The entity that deals it, left out when nothing does (the rules, a trap) */
     readonly source?: Entity;
+    /** The damage in hit points before armor and shields; a handler may change it */
     amount: number;
+    /** The damage type, which armor and resistance read; a handler may change it */
     type: DamageType;
     /** A basic attack, not an ability */
     readonly attack: boolean;
+    /** Whether the blow is a critical hit */
     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[];
+    /** Whether a handler has called it off; set by `cancel()` */
     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;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
 }
 /**
  * Damage that was dealt. The target may have died of it
@@ -57,36 +49,51 @@ export interface DamageMultiplier {
  * @beta
  */
 export interface AfterDamage {
+    /** The entity that took the damage */
     readonly target: Entity;
+    /** The entity that dealt it, left out when nothing did */
     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;
+    /** The damage type it was dealt as */
     readonly type: DamageType;
+    /** Whether it was a basic attack, not an ability */
     readonly attack: boolean;
+    /** Whether the blow was a critical hit */
     readonly crit: boolean;
+    /** The ability that dealt it, by id; left out for a basic attack */
     readonly ability?: string;
+    /** Words of the game's own about it (`DamageOptions.tags`) */
     readonly tags?: readonly string[];
 }
 /**
- * Health about to be given back. Change `amount`, or set `cancelled`
+ * Health about to be given back. Change `amount`, or `cancel()`
  *
  * @beta
  */
 export interface BeforeHeal {
+    /** The entity about to be healed */
     readonly target: Entity;
+    /** The entity that heals it, left out when nothing does */
     readonly source?: Entity;
+    /** How much health is given; a handler may change it */
     amount: number;
+    /** Whether a handler has called it off; set by `cancel()` */
     cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
 }
 /**
- * Something is about to die. Set `prevented` to keep it alive: it is then up to the handler what health it has
+ * Something is about to die. `cancel()` keeps it alive: it is then up to the handler what health it has
  *
  * @beta
  */
 export interface BeforeDeath {
+    /** The entity about to die */
     readonly entity: Entity;
+    /** The entity that killed it, left out when nothing did */
     readonly killer?: Entity;
     /** An attack of the killer did it */
     readonly attack: boolean;
@@ -96,7 +103,10 @@ export interface BeforeDeath {
     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;
+    /** Whether a handler has called it off; set by `cancel()` */
+    cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
 }
 /**
  * Something dies. In `death` it still stands where it was; in `afterDeath` it is gone from the world
@@ -104,8 +114,11 @@ export interface BeforeDeath {
  * @beta
  */
 export interface Death {
+    /** The entity that died */
     readonly entity: Entity;
+    /** The entity that killed it, left out when nothing did */
     readonly killer?: Entity;
+    /** Whether an attack of the killer did it */
     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;
@@ -117,17 +130,26 @@ export interface Death {
      * (`SessionEvent` `death`) to show it its way (`UnitLook.death`). Nothing when left out
      */
     how?: string;
+    /**
+     * The buffs it carried as it fell, in `afterDeath` (where they are taken off it already): an `onKill`'s effects ask
+     * them of the one killed (B44). Left out when it carried none
+     */
+    readonly carried?: readonly BuffInstance[];
 }
 /**
- * An order about to be given to a unit. Set `rejected` to refuse it
+ * An order about to be given to a unit. Set `rejected` to refuse it. A cast that goes off at once, in the middle of
+ * what the unit is doing (a potion drunk on the way, a leap), is asked here too, as the cast order it stands for
  *
  * @beta
  */
 export interface BeforeOrder {
+    /** The entity the order is for */
     readonly entity: Entity;
+    /** The order about to be given */
     readonly order: Order;
     /** Added to the end of what it does, rather than in place of it */
     readonly queued: boolean;
+    /** Whether a handler refuses the order; it is then not given */
     rejected: boolean;
 }
 /**
@@ -141,12 +163,15 @@ export interface BeforeOrder {
  * @beta
  */
 export interface TargetScore {
+    /** The unit looking for a target */
     attacker: Entity;
+    /** The candidate it is scoring */
     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`) */
+    /** Attackers like this one (its layer, its reach) the target has already, and how many it has room for (`RuleSettings.combat.engageRoom`) */
     engaged: number;
+    /** How many attackers like it the target has already (`RuleSettings.combat.engageRoom`) */
     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;
@@ -161,30 +186,38 @@ export interface Approach {
     point: Vec2;
 }
 /**
- * An ally standing in a unit's way is asked to step aside, to `point` (see `GameRules.movement.makesWay`, `lookAhead`): change
+ * An ally standing in a unit's way is asked to step aside, to `point` (see `RuleSettings.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 {
+    /** The unit that is on its way */
     readonly mover: Entity;
+    /** The ally standing in its way, asked to step aside */
     readonly other: Entity;
     /** Where the mover is heading, a unit long */
     readonly direction: Vec2;
+    /** Where the other unit goes; change it, or null to leave it standing */
     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
+ * than the `straight` way to the next corner of its path (see `RuleSettings.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 {
+    /** The unit about to go round the others */
     readonly entity: Entity;
+    /** The units standing in its way */
     readonly around: readonly Entity[];
+    /** The distance of the straight way to the next corner of its path, in ground units */
     readonly straight: number;
+    /** How many ground units longer the way by `point` is than the straight way */
     readonly longer: number;
+    /** The point it goes by round the others; change it, or null to go straight through */
     point: Vec2 | null;
 }
 /**
@@ -195,23 +228,32 @@ export interface Detour {
  * @beta
  */
 export interface Formation {
+    /** The units ordered, those that walk or those that fly, each laid out apart */
     readonly units: readonly Entity[];
+    /** The point they are ordered to */
     readonly target: Vec2;
+    /** The formation the units are laid out in */
     readonly formation: FormationDef;
+    /** Where each unit goes, by entity id; a handler may change, add or remove places */
     readonly points: Map<EntityId, Vec2>;
 }
 /**
- * Whether a structure may be placed. Set `allowed` to false, with a `reason` the player is told
+ * Whether a structure may be placed. `cancel(reason)` refuses it, with what the player is told
  *
  * @beta
  */
 export interface CanPlace {
+    /** The unit type of the structure to be placed */
     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;
+    /** Whether a handler has refused the placing; set by `cancel()` */
+    cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
+    /** What the player is told of why it was refused */
     reason?: MessageRef;
 }
 /**
@@ -222,17 +264,27 @@ export interface CanPlace {
  * @beta
  */
 export interface BeforeCast {
+    /** The unit that casts */
     readonly caster: Entity;
+    /** The ability being cast */
     readonly ability: AbilityDef;
+    /** The level of the ability it is cast at */
     readonly level: number;
+    /** The unit it is cast on, left out for a point or no target */
     readonly target?: Entity;
+    /** The point it is cast at (the target's place for a unit target) */
     readonly point: Vec2;
     /** What it is cast from, for an item's ability */
     readonly item?: ItemInstance;
+    /** The mana it costs; a handler may change it */
     manaCost: number;
     /** Seconds until it can be used again */
     cooldown: number;
+    /** Whether a handler has called the cast off; set by `cancel()` */
     cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
+    /** What the player is told of why it was called off */
     reason?: MessageRef;
 }
 /**
@@ -241,11 +293,17 @@ export interface BeforeCast {
  * @beta
  */
 export interface AfterCast {
+    /** The unit that cast */
     readonly caster: Entity;
+    /** The ability that went off */
     readonly ability: AbilityDef;
+    /** The level it was cast at */
     readonly level: number;
+    /** The unit it was cast on, left out for a point or no target */
     readonly target?: Entity;
+    /** The point it was cast at */
     readonly point: Vec2;
+    /** The item it was cast from, for an item's ability */
     readonly item?: ItemInstance;
     /** It went off charged, and spent the charge */
     readonly charged: boolean;
@@ -256,13 +314,20 @@ export interface AfterCast {
  * @beta
  */
 export interface BeforeBuff {
+    /** The unit about to get the buff */
     readonly target: Entity;
+    /** The buff to be put on */
     readonly buff: BuffDef;
+    /** The unit that puts it on, left out when nothing does */
     readonly source?: Entity;
+    /** The level the buff is put on at; a handler may change it */
     level: number;
     /** Seconds, after tenacity. Infinity for one that stays */
     duration: number;
+    /** Whether a handler has called it off; set by `cancel()` */
     cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
 }
 /**
  * A buff that came off: it ran out (`expired`), or was taken off. Not called for the buffs of something that dies
@@ -270,11 +335,18 @@ export interface BeforeBuff {
  * @beta
  */
 export interface BuffEnd {
+    /** The entity the buff was on */
     readonly entity: Entity;
+    /** The buff instance that ended, with its level and source */
     readonly buff: BuffInstance;
+    /** Whether the buff ran out its duration; false when it was taken off */
     readonly expired: boolean;
 }
-/** @beta */
+/**
+ * One of the five things that are made: a unit trained, an upgrade researched, a building morphed, a hero revived, a structure put down
+ *
+ * @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,
@@ -283,16 +355,23 @@ export type ProductionKind = 'unit' | 'upgrade' | 'morph' | 'revive' | 'structur
  * @beta
  */
 export interface BeforeProduce {
+    /** The player the production is for */
     readonly player: PlayerId;
     /** The building it is made in, or the worker putting down a structure */
     readonly producer: Entity;
+    /** What is being made: `unit`, `upgrade`, `morph`, `revive` or `structure` */
     readonly kind: ProductionKind;
     /** Unit type, upgrade, the type a building becomes, the id of a hero, or a structure type */
     readonly id: string;
+    /** What it costs the player; a handler may change it */
     cost: Cost;
     /** Seconds it takes */
     time: number;
+    /** Whether a handler has called it off; set by `cancel()` */
     cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
+    /** What the player is told of why it was called off */
     reason?: MessageRef;
 }
 /** Every hook, and what its handlers get */
@@ -304,21 +383,26 @@ export interface BeforeProduce {
  * @beta
  */
 export interface Idle {
+    /** The unit with nothing to do */
     readonly entity: Entity;
+    /** Seconds the tick lasts */
     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;
+    /** Whether a handler took over the idle unit; set it to stop the engine's own idle behaviour */
     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
+ * enemies) is in `cancelled`, 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;
+    cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
     /**
      * 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
@@ -350,6 +434,8 @@ export interface BeforeAttack {
     /** How what it kills dies, for the screen (`AttackDef.how`, worked out for this blow): changed as the game likes */
     how?: string;
     cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
 }
 /**
  * The stats of an entity being added up, once what the engine knows of (its type, levels, research, items, buffs) is
@@ -363,8 +449,8 @@ export interface StatsHook {
     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
+ * Whether an ability can be used now: what the engine makes of it (level, cooldown, mana, silence) is `cancelled` with its
+ * `reason`: `cancelled = false` clears it ("free while Clearcasting"), `cancel(reason)` sets it ("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
  */
@@ -374,10 +460,13 @@ export interface CanCast {
     readonly level: number;
     /** What it is used from, for an item's ability */
     readonly item?: ItemInstance;
-    refusal?: MessageRef;
+    reason?: MessageRef;
+    cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
 }
 /**
- * Whether an ability may be used on a target: what the engine makes of it (the ability's `targets`) in `refusal`, to
+ * Whether an ability may be used on a target: what the engine makes of it (the ability's `targets`) is `cancelled`, with its `reason`: `cancelled = false` 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
  */
@@ -385,7 +474,66 @@ export interface CanTarget {
     readonly caster: Entity;
     readonly ability: AbilityDef;
     readonly target: Entity;
-    refusal?: MessageRef;
+    reason?: MessageRef;
+    cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
+}
+/**
+ * An effect of an ability about to reach one target (`beforeEffect`): who it is from, the effect, whom it reaches, where
+ * it went off from. Cancelled, it does not reach that one, and only that one: the rest of an area are reached, a missile
+ * passes it by (it is in its `hit`, so it is not asked again). Asked wherever any effect reaches any target: who an
+ * effect applies to (`effectTargets`, so a `damage`, `heal`, `buff`, `knockback`, `pull`, `dispel`, a game's own that
+ * asks), a missile's hit (with `missile`: a shield that eats it takes it out with `removeMissile`), what a game's own
+ * effect asks (`mayReach`). Not for an aura's buff, which is kept up rather than landed. Asked only where a handler
+ * is there: a game without one pays nothing
+ *
+ * @beta
+ */
+export interface BeforeEffect {
+    /** Whose the effect is */
+    readonly caster: Entity;
+    /** The ability the effect belongs to */
+    readonly ability: AbilityDef;
+    /** The level it was cast at */
+    readonly level: number;
+    /** The effect, as it runs (a chain lowered: `lowerChain`) */
+    readonly effect: EffectDef;
+    /** Whom it is about to reach */
+    readonly target: Entity;
+    /** What it went off from, when not the caster (`EffectContext.origin`) */
+    readonly origin?: Entity | Vec2;
+    /** Where it landed */
+    readonly point: Vec2;
+    /** The missile that reached the target, for a missile's hit */
+    readonly missile?: Missile;
+    /** Whether a handler has called it off for this target; set by `cancel()` */
+    cancelled: boolean;
+    /** It does not reach this target */
+    cancel(): void;
+}
+/**
+ * An effect of an ability has reached one target (`effectLanded`), after its handler ran: what a game does with each
+ * one an ability reached (a passive's stack for each hit, an execute below a threshold). For every target the
+ * handler's `effectTargets` gave; asked only where a handler is there
+ *
+ * @beta
+ */
+export interface EffectLanded {
+    /** The unit that cast the ability the effect is from */
+    readonly caster: Entity;
+    /** The ability the effect is from */
+    readonly ability: AbilityDef;
+    /** The level the ability was cast at */
+    readonly level: number;
+    /** The effect that reached the target, as it runs */
+    readonly effect: EffectDef;
+    /** Whom it reached: dead now, maybe, of it */
+    readonly target: Entity;
+    /** What it went off from, when not the caster: an entity or a point */
+    readonly origin?: Entity | Vec2;
+    /** Where the effect landed */
+    readonly point: Vec2;
 }
 /**
  * Whether a team sees an entity of someone else's: what the fog and invisibility make of it in `visible`, to change.
@@ -399,7 +547,7 @@ export interface Visible {
 /**
  * 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
+ * `cancelled` with its `reason`, to clear (`cancelled = false`) or set (`cancel(reason)`): "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 {
@@ -410,7 +558,10 @@ export interface Requirement {
     readonly level?: number;
     /** Required building types the player does not have */
     readonly missing: readonly string[];
-    refusal?: MessageRef;
+    reason?: MessageRef;
+    cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
 }
 /**
  * Whether a player may make a unit type or research an upgrade at all, before what it requires (see `isAvailable`):
@@ -421,11 +572,15 @@ export interface Requirement {
  * @beta
  */
 export interface Available {
+    /** The player who would make it */
     readonly player: PlayerId;
+    /** Whether it is for a `unit` type or an `upgrade` */
     readonly kind: 'unit' | 'upgrade';
+    /** The unit type or upgrade being asked about */
     readonly id: string;
     /** The race the player plays, if the game has races */
     readonly race: string | undefined;
+    /** Whether the player may make it at all; the engine sets it from the race, a handler may change it */
     available: boolean;
 }
 /**
@@ -443,6 +598,8 @@ export interface BeforeTalk {
     readonly point?: Vec2;
     readonly pingKind?: string;
     cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
 }
 /**
  * Resources about to be given to an ally (see `give`): change how much arrives (`received`), or call it off with a
@@ -455,6 +612,8 @@ export interface BeforeTrade {
     readonly sent: number;
     received: number;
     cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
     reason?: MessageRef;
 }
 /**
@@ -463,8 +622,13 @@ export interface BeforeTrade {
  * @beta
  */
 export interface BeforeSurrender {
+    /** The player about to give up */
     readonly player: PlayerId;
+    /** Whether a handler has called it off; set by `cancel()` */
     cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
+    /** What the player is told of why they cannot give up */
     reason?: MessageRef;
 }
 /**
@@ -474,36 +638,50 @@ export interface BeforeSurrender {
  * @beta
  */
 export interface BeforePause {
+    /** The player asking for the pause */
     readonly player: PlayerId;
+    /** How many pauses the player has left before this one */
     readonly left: number;
+    /** How long the pause lasts at most, in seconds; a handler may change it */
     seconds: number;
+    /** Whether a handler has called it off; set by `cancel()` */
     cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
+    /** What the player is told of why the pause was refused */
     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
+ * `cap` (a starting amount, an upgrade, a rule of the game's own). The game's most (`RuleSettings.supply.max`, a pool's
  * `max`) still holds after
  *
  * @beta
  */
 export interface SupplyCap {
+    /** The player whose supply cap it is */
     readonly player: PlayerId;
-    /** `supply` for the one there always is, or the name of one of the game's own (`GameRules.supply.pools`) */
+    /** `supply` for the one there always is, or the name of one of the game's own (`RuleSettings.supply.pools`) */
     readonly pool: string;
+    /** The cap of the pool in supply points, once buildings are added up; a handler may change it */
     cap: number;
 }
 /**
- * Whether a worker may gather from a resource: by default, a resource of a kind it gathers (`harvester.kinds`). Refuse
+ * Whether a worker may gather from a resource: by default, a resource of a kind it gathers (`harvester.ids`). 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 {
+    /** The worker that would gather */
     readonly worker: Entity;
+    /** The resource entity it would gather from */
     readonly source: Entity;
-    allowed: boolean;
+    /** Whether a handler has refused it; set by `cancel()` */
+    cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
     /** What the player is told when it is refused */
     reason?: MessageRef;
 }
@@ -514,6 +692,8 @@ export interface BeforeDeposit {
     readonly kind: string;
     amount: number;
     cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
 }
 /** An item about to be bought at a shop: change what it costs, or call it off with a `reason` */
 export interface BeforeBuy {
@@ -522,6 +702,8 @@ export interface BeforeBuy {
     readonly item: string;
     cost: Cost;
     cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
     reason?: MessageRef;
 }
 /** An item about to be picked up off the ground (`ground` its id there): call it off with a `reason` */
@@ -530,6 +712,8 @@ export interface BeforePickUp {
     readonly item: string;
     readonly ground: number;
     cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
     reason?: MessageRef;
 }
 /** An item about to be put down: call it off with a `reason` (a cursed blade) */
@@ -537,6 +721,8 @@ export interface BeforeDrop {
     readonly entity: Entity;
     readonly item: ItemInstance;
     cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
     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 */
@@ -545,11 +731,13 @@ export interface BeforeXp {
     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 */
+/** Whether a hero may put a point into an ability: what the engine makes of it in `cancelled`, to change. The screen hears of it with what the hero can learn */
 export interface CanLearn {
     readonly hero: Entity;
     readonly ability: string;
-    allowed: boolean;
+    cancelled: boolean;
+    /** Stops it. The reason is what the player is told, where this hook tells them (`reason`) */
+    cancel(reason?: MessageRef): void;
 }
 /** Something was made: a unit trained (`unit`), research done (`level`), a building upgraded, a hero brought back */
 export interface Produced {
@@ -579,6 +767,7 @@ export interface Morphed {
  * @beta
  */
 export interface FromMapObject {
+    /** The entity that was placed on the map and has become this entity */
     readonly entity: Entity;
     /** As the map has it: where, whose, its name */
     readonly object: Readonly<MapObject>;
@@ -591,14 +780,16 @@ export interface FromMapObject {
  * @beta
  */
 export interface FromMapCamp {
+    /** The camp in the world that the map's camp has become */
     readonly camp: Camp;
+    /** The camp as the map has it: where, its units */
     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
+ * entities, to be brought back. No when nothing says so; the heroes pack says yes for a hero (`heroesPack`), and a
  * handler after it (a higher `priority`) can say no for a game where heroes fall for good
  *
  * @beta
@@ -617,7 +808,9 @@ export interface FallenHero {
  * @beta
  */
 export interface FromMapRegion {
+    /** The area of the world that the map's region has become */
     readonly area: AreaDef;
+    /** The region as the map has it: its name and shape */
     readonly region: Readonly<MapRegion>;
     /** The game's own fields for regions, see `FromMapObject.data` */
     readonly data: Readonly<Record<string, unknown>>;
@@ -633,14 +826,23 @@ export interface FromMap {
     /** The map it was made from */
     readonly map: Readonly<GameMap>;
 }
-/** @beta */
+/**
+ * The map of hooks the engine runs, by name, to the event each one hands its handlers
+ *
+ * @beta
+ */
 export interface HookEvents {
+    /** Its handlers get a `BeforeDamage`: damage about to be dealt, before armor and shields. Change `amount` or `type`, or `cancel()` */
     beforeDamage: BeforeDamage;
-    damageMultiplier: DamageMultiplier;
+    /** Its handlers get a `AfterDamage`: damage that was dealt. The target may have died of it */
     afterDamage: AfterDamage;
+    /** Its handlers get a `BeforeHeal`: health about to be given back. Change `amount`, or `cancel()` */
     beforeHeal: BeforeHeal;
+    /** Its handlers get a `BeforeDeath`: something is about to die. `cancel()` keeps it alive: it is then up to the handler what health it has */
     beforeDeath: BeforeDeath;
+    /** Its handlers get a `Death`: something dies. In `death` it still stands where it was; in `afterDeath` it is gone from the world */
     death: Death;
+    /** Its handlers get a `Death`: something dies. In `death` it still stands where it was; in `afterDeath` it is gone from the world */
     afterDeath: Death;
     /** Whether what died stays in the world's entities, out of the world, to be brought back (`FallenHero`). @beta */
     fallenHero: FallenHero;
@@ -655,39 +857,77 @@ export interface HookEvents {
     spawn: Entity;
     /** Something left the world for good, at the end of the tick it died in */
     remove: Entity;
+    /** Its handlers get a `BeforeOrder`: an order about to be given to a unit. Set `rejected` to refuse it */
     beforeOrder: BeforeOrder;
+    /** Its handlers get a `TargetScore`: 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... */
     targetScore: TargetScore;
+    /** Its handlers get a `Approach`: 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... */
     approach: Approach;
+    /** Its handlers get a `MakeWay`: an ally standing in a unit's way is asked to step aside, to `point` (see `RuleSettings.movement.makesWay`, `lookAhead`): change where it goes, or make it null to leave it standing.... */
     makeWay: MakeWay;
+    /** Its handlers get a `Detour`: 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 `RuleSettings.movement.goesAround`):... */
     detour: Detour;
+    /** Its handlers get a `Formation`: 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`... */
     formation: Formation;
+    /** Its handlers get a `CanPlace`: whether a structure may be placed. `cancel(reason)` refuses it, with what the player is told */
     canPlace: CanPlace;
+    /** Its handlers get a `BeforeCast`: 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... */
     beforeCast: BeforeCast;
+    /** Its handlers get a `AfterCast`: an ability that went off */
     afterCast: AfterCast;
+    /** Its handlers get a `BeforeBuff`: 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) */
     beforeBuff: BeforeBuff;
+    /** Its handlers get a `BuffEnd`: a buff that came off: it ran out (`expired`), or was taken off. Not called for the buffs of something that dies */
     buffEnd: BuffEnd;
+    /** Its handlers get a `BeforeProduce`: 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,... */
     beforeProduce: BeforeProduce;
+    /** Its handlers get a `Idle`: 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... */
     idle: Idle;
+    /** Its handlers get a `CanAttack`: whether an attacker may attack a target: what the engine makes of it (its attack's targets, whether they are enemies) is in `cancelled`, to change. A buff that lets a unit hit what... */
     canAttack: CanAttack;
+    /** Its handlers get a `BeforeAttack`: 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;... */
     beforeAttack: BeforeAttack;
+    /** Its handlers get a `StatsHook`: 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:... */
     stats: StatsHook;
+    /** Its handlers get a `CanCast`: whether an ability can be used now: what the engine makes of it (level, cooldown, mana, silence) is `cancelled` with its `reason`: `cancelled = false` clears it ("free while Clearcasting"),... */
     canCast: CanCast;
+    /** Its handlers get a `CanTarget`: whether an ability may be used on a target: what the engine makes of it (the ability's `targets`) is `cancelled`, with its `reason`: `cancelled = false` to clear ("can target allied... */
     canTarget: CanTarget;
+    /** An effect about to reach one target: cancel it for that one (`BeforeEffect`). @beta */
+    beforeEffect: BeforeEffect;
+    /** An effect reached one target, its handler done (`EffectLanded`). @beta */
+    effectLanded: EffectLanded;
+    /** Its handlers get a `Visible`: 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 */
     visible: Visible;
+    /** Its handlers get a `Requirement`: 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... */
     requirement: Requirement;
+    /** Its handlers get a `Available`: 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`).... */
     available: Available;
+    /** Its handlers get a `BeforeDeposit`: resources a worker hands in: change `amount` (more from mines near the keep), or call it off */
     beforeDeposit: BeforeDeposit;
+    /** Its handlers get a `CanHarvest`: whether a worker may gather from a resource: by default, a resource of a kind it gathers (`harvester.ids`). Refuse it for a game's own rule: a mine only its owner's cursed mine stands... */
     canHarvest: CanHarvest;
+    /** Its handlers get a `BeforeTalk`: 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... */
     beforeTalk: BeforeTalk;
+    /** Its handlers get a `BeforeTrade`: 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 */
     beforeTrade: BeforeTrade;
+    /** Its handlers get a `BeforeSurrender`: 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 */
     beforeSurrender: BeforeSurrender;
+    /** Its handlers get a `SupplyCap`: 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... */
     supplyCap: SupplyCap;
+    /** Its handlers get a `BeforePause`: 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` */
     beforePause: BeforePause;
+    /** Its handlers get a `BeforeBuy`: an item about to be bought at a shop: change what it costs, or call it off with a `reason` */
     beforeBuy: BeforeBuy;
+    /** Its handlers get a `BeforePickUp`: an item about to be picked up off the ground (`ground` its id there): call it off with a `reason` */
     beforePickUp: BeforePickUp;
+    /** Its handlers get a `BeforeDrop`: an item about to be put down: call it off with a `reason` (a cursed blade) */
     beforeDrop: BeforeDrop;
+    /** Its handlers get a `BeforeXp`: 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 */
     beforeXp: BeforeXp;
+    /** Its handlers get a `CanLearn`: whether a hero may put a point into an ability: what the engine makes of it in `cancelled`, to change. The screen hears of it with what the hero can learn */
     canLearn: CanLearn;
+    /** Its handlers get a `Produced`: something was made: a unit trained (`unit`), research done (`level`), a building upgraded, a hero brought back */
     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;
@@ -698,9 +938,17 @@ export interface HookEvents {
     /** 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 */
+/**
+ * The name of one of the engine's hooks, a key of `HookEvents`
+ *
+ * @beta
+ */
 export type HookName = keyof HookEvents;
-/** @beta */
+/**
+ * The function a handler for the hook `K` is, taking the world and the hook's event
+ *
+ * @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
@@ -709,19 +957,22 @@ export type HookHandler<K extends HookName> = (world: World, event: HookEvents[K
  * @beta
  */
 export interface HookKey<T> {
+    /** The hook's id, shared by every game, which `Hooks` lists it by */
     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')`.
+ * A hook of a game's own: `const lifeLost = defineHookType<{ invader: Entity; lives: number } & Cancellable>({ id: '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>;
+export declare function defineHookType<T>(def: {
+    id: string;
+}): HookKey<T>;
 /**
  * A hook: one of the engine's by name, or a game's own
  *
@@ -729,10 +980,35 @@ export declare function defineHookType<T>(id: string): HookKey<T>;
  */
 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
+ * What a hook that may be stopped carries: `cancel(reason?)` stops it, `cancelled` says whether it was, and `reason` is
+ * what the player is told, for the hooks that tell them (`canPlace`, `canHarvest`, `canCast`, `canTarget`,
+ * `requirement`). The engine's own refusal comes in as `cancelled` already true, with its `reason`: `cancelled = false`
+ * lets it through
  *
  * @beta
  */
+export interface Cancellable {
+    /** Whether a handler has stopped the event; `cancel()` sets it */
+    cancelled: boolean;
+    /** What the player is told of why it was stopped, for the hooks that tell them */
+    reason?: MessageRef;
+    /** Stops the event, with the `reason` the player is told when given */
+    cancel(reason?: MessageRef): void;
+}
+/** An event of a hook that may be stopped, as whoever runs the hook puts it together: `cancel` is given as it runs (`Hooks.run`) @beta */
+export type Uncancelled<T> = T extends Cancellable ? Omit<T, 'cancel'> & {
+    cancel?: Cancellable['cancel'];
+} : T;
+/** What a hook that tells the player refuses with: its reason, or the engine's word where a handler gave none; nothing where it lets through @beta */
+export declare function refusalOf(event: {
+    cancelled: boolean;
+    reason?: MessageRef;
+}): MessageRef | undefined;
+/**
+ * A handler and the hook it is for. Its `id` is how others take it out or put something in its place
+ *
+ * @public
+ */
 export type HookDef = {
     hook: AnyHook;
     id: string;
@@ -743,7 +1019,7 @@ export type HookDef = {
 /**
  * Typed help for writing a hook: `defineHook({ hook: 'death', id: 'bounty', run(world, { entity }) { ... } })`
  *
- * @beta
+ * @public
  */
 export declare function defineHook<K extends HookName>(def: {
     hook: K;
@@ -751,7 +1027,11 @@ export declare function defineHook<K extends HookName>(def: {
     priority?: number;
     run: HookHandler<K>;
 }): HookDef;
-/** @beta */
+/**
+ * Typed help for a handler of a game's own hook (`HookKey`), taking the world and the hook's event
+ *
+ * @public
+ */
 export declare function defineHook<T>(def: {
     hook: HookKey<T>;
     id: string;
@@ -769,12 +1049,14 @@ export declare class Hooks {
     constructor(world: World);
     /** Adds a handler. One with the same id on the same hook is replaced */
     add(def: HookDef): void;
+    /** Takes the handler with the id off the hook; nothing happens when there is none */
     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;
+    run<K extends HookName>(hook: K, event: Uncancelled<HookEvents[K]>): HookEvents[K];
+    /** Runs the handlers of a game's own hook on the event in order and returns the event */
+    run<T>(hook: HookKey<T>, event: Uncancelled<T>): T;
 }