@kingdomsconnected/types 1.6.1 → 1.6.3

package/generated/server-api.d.ts

@@ -18,18 +18,18 @@ declare global {
     /**
      * Dispatched once per accepted death report. Call player.revive() to request revival; there is no automatic respawn.
      * 
-     * `killer` is the player whose blow took the last of the health, as the dying player's own client saw it -- null for a fall, a bleed-out, or anything that was not a player. `reason` is the game's own for that last write: `combat` for a blade or a bow, `fall`, `bleeding`, `poison` and so on.
+     * `killer` is the player or server NPC whose blow took the last of the health, as the dying player's own client saw it -- null for a fall, a bleed-out, or anything without an identified attacker. `reason` is the game's own for that last write: `combat` for a blade or a bow, `fall`, `bleeding`, `poison` and so on.
      */
-    playerDied: [player: Player, killer: Player | null, reason: "unknown" | "combat" | "gunshot" | "starvation" | "collision" | "scripted" | "disintegrate" | "fall" | "poison" | "bleeding" | "selfHarm"];
+    playerDied: [player: Player, killer: Player | Npc | null, reason: "unknown" | "combat" | "gunshot" | "starvation" | "collision" | "scripted" | "disintegrate" | "fall" | "poison" | "bleeding" | "selfHarm"];
 
     /**
-     * Dispatched when something takes health off a player: a weapon, an arrow, a fall, a collision, a scripted hit. Another player's blow is raised by the server as it rules on it, after `playerHit` had its say, so `amount` is what the ruling takes; anything else is reported by the hit player's own client, which resolved it against its armour and its skills. It arrives ahead of the `playerDied` a killing blow causes.
+     * Dispatched when something takes health off a player: a weapon, an arrow, a fall, a collision, a scripted hit. Player combat and server NPC melee are raised by the server as it rules on them, after `playerHit` had its say, so `amount` is what the ruling takes; anything else is reported by the hit player's own client, which resolved it against its armour and its skills. It arrives ahead of the `playerDied` a killing blow causes.
      * 
-     * `attacker` is the player who dealt it, or null. `bodyPart` is where it landed, or null for damage that lands nowhere in particular. The weapon is the attacker's own `rightHandItem` or `leftHandItem`.
+     * `attacker` is the player or server NPC who dealt it, or null. `bodyPart` is where it landed, or null for damage that lands nowhere in particular. A player attacker's weapon is available through `rightHandItem` or `leftHandItem`; an NPC's equipped items are in `wearing`.
      * 
      * Bleeding, poison and hunger wear health down a tick at a time without raising this -- `bleeding`, `poisoning` and `hunger` are live numbers already. The tick that kills does arrive, with its own reason, just before the `playerDied` it causes.
      */
-    playerDamage: [player: Player, attacker: Player | null, amount: number, bodyPart: "head" | "torso" | "leftArm" | "rightArm" | "leftLeg" | "rightLeg" | null, reason: "unknown" | "combat" | "gunshot" | "starvation" | "collision" | "scripted" | "disintegrate" | "fall" | "poison" | "bleeding" | "selfHarm"];
+    playerDamage: [player: Player, attacker: Player | Npc | null, amount: number, bodyPart: "head" | "torso" | "leftArm" | "rightArm" | "leftLeg" | "rightLeg" | null, reason: "unknown" | "combat" | "gunshot" | "starvation" | "collision" | "scripted" | "disintegrate" | "fall" | "poison" | "bleeding" | "selfHarm"];
 
     /**
      * A melee swing aimed at another player was admitted by the server, including a miss. Raised once per attack generation, after presentation admission. Use it to track combat inactivity in your resource.
@@ -42,11 +42,11 @@ declare global {
     playerCombatCancelled: [first: Player, second: Player];
 
     /**
-     * Dispatched when another player's blade or arrow lands on a player, before anything is taken -- the place for teams, safe zones, friendly fire and damage rules. The game resolved the blow against the guard the victim really held -- whether it was blocked, perfectly or not, and where it landed -- and the server works out what a swing takes from there; it has checked that the swing was one it relayed and could still land, or that the arrow was one whose impact it accepted, and that the two stood within reach. Only what is ruled here comes off the victim's health, on every client at once.
+     * Dispatched when another player's blade or arrow, or a server NPC's melee attack, lands on a player, before anything is taken -- the place for teams, safe zones, friendly fire and damage rules. The game resolved the blow against the guard the victim really held -- whether it was blocked, perfectly or not, and where it landed -- and the server works out what a swing takes from there; it has checked that the swing was one it relayed and could still land, or that the arrow was one whose impact it accepted, and that the two stood within reach. Only what is ruled here comes off the victim's health, on every client at once.
      * 
-     * Return `false` from a handler to refuse the blow: no health is taken and no `playerDamage` follows. Scale `hit.modifiers` to change how a swing is worked out -- a stronger attack, weaker armour -- or set `hit.damage` to say outright what it takes: `0` for a blow that lands harmlessly, more for a heavier one. Either way the blow is still seen and heard: the blades met. Handlers run synchronously, so the decision cannot wait on anything awaited.
+     * Return `false` from a handler to refuse the blow: no health is taken and no `playerDamage` follows. NPC melee uses the victim client's native damage with `priced: false`; set `hit.damage` to change it. For priced player swings, scale `hit.modifiers` to change how a swing is worked out -- a stronger attack, weaker armour -- or set `hit.damage` to say outright what it takes: `0` for a blow that lands harmlessly, more for a heavier one. Either way the blow is still seen and heard: the blades met. Handlers run synchronously, so the decision cannot wait on anything awaited.
      */
-    playerHit: [player: Player, attacker: Player, hit: PlayerHit];
+    playerHit: [player: Player, attacker: Player | Npc, hit: PlayerHit];
 
     /**
      * Dispatched when a limb becomes injured -- usually a blow landing there, sometimes a fall on both legs. `player.injuries` already says so. A limb hit again while injured stays injured and raises nothing new.
@@ -137,6 +137,11 @@ declare global {
      */
     playerInventoryReady: [player: Player];
 
+    /**
+     * A move or patrol leg reached its destination, was blocked, or failed. Intermediate path corners do not emit this event.
+     */
+    horseIntentDone: [horse: Horse, status: string];
+
     /**
      * Dispatched immediately after a horse is created and replicated, whether by `Horse.spawn`, the `/horse` command, or anything else.
      */
@@ -367,14 +372,14 @@ declare global {
     npcIntentDone: [npc: Npc, status: string];
 
     /**
-     * Dispatched after health came off the ledger. The attacker's own client resolved the hit and the server agreed to it, so `amount` is what was actually taken, not what was claimed.
+     * Dispatched after health came off the ledger. For melee, the victim's simulator resolves the native hit and the server checks the accepted swing before changing health. `amount` is what was actually taken.
      */
-    npcDamage: [npc: Npc, attacker: Player | null, amount: number];
+    npcDamage: [npc: Npc, attacker: Player | Npc | null, amount: number];
 
     /**
      * Dispatched when the last of an NPC's health goes. The body stays as a corpse and the handle keeps resolving.
      */
-    npcDeath: [npc: Npc, attacker: Player | null];
+    npcDeath: [npc: Npc, attacker: Player | Npc | null];
 
     /**
      * Dispatched when a dead NPC is brought back. Every client makes a new body for it.
@@ -396,6 +401,16 @@ declare global {
      */
     npcSimulatorChange: [npc: Npc, player: Player | null];
 
+    /**
+     * One accepted waypoint outcome; intermediate path corners do not emit it.
+     */
+    patrolWaypoint: [actor: Npc, info: PatrolState & { status: 'reached' | 'blocked' | 'failed' }];
+
+    /**
+     * A patrol ended, failed, or was replaced. Edits to its definition do not replace its snapshot.
+     */
+    patrolFinished: [actor: Npc, info: PatrolState & { status: 'completed' | 'failed' | 'cancelled' }];
+
     /**
      * Dispatched when a player starts or stops following a quest in the game's journal, whichever way it happened: the track button, the game auto-tracking a quest that turns active, or the untrack that follows finishing or failing one. The client reports it -- following a quest is decided there and cannot be refused here -- so a handler reacts rather than vetoes. It fires only on an actual change, and only for a quest that player was given.
      */
@@ -449,9 +464,9 @@ declare global {
     siegeEngineReady: [engine: SiegeEngine];
 
     /**
-     * Dispatched when a player presses a `usable` engine's native prompt, standing at it, on the step the prompt was offered for. Return false to refuse; otherwise the engine loads, or fires along the player's facing at `range` with the player as the attacker. A handler that works the engine itself should refuse, so it is not worked twice.
+     * Dispatched when a player asks something of a `usable` engine, standing at it: to take its place (`operate`) or a free winch (`winch`) from the game's own prompt, or -- in its place -- to `load` it or `fire` it where they laid it, with the player as the attacker. Return false to refuse. `leave` reports a player stepping away from either and cannot be refused. A handler that works the engine itself should refuse, so it is not worked twice.
      */
-    siegeEngineUse: [player: Player, engine: SiegeEngine, action: "load" | "fire"];
+    siegeEngineUse: [player: Player, engine: SiegeEngine, action: "operate" | "winch" | "leave" | "load" | "fire"];
 
     /**
      * Dispatched the moment an engine lets its projectile go, partway through the shot `fire` started.
@@ -604,11 +619,221 @@ declare global {
      * Dispatched when a player asks to join, before the connection exists: they hold no player slot, are not counted as online, and are sent nothing -- no resource list, no download, no body. The request waits until every handler has returned and every Promise a handler returned has settled, then it is let in if a player slot is free (otherwise it is refused as full). `connection.reject()` turns it away instead, and so does a handler that throws or rejects, or handlers that have not settled within the server's admission timeout (30 seconds by default, restarted by every `connection.update()`). With no handler at all, every request is let in at once.
      */
     playerConnecting: [connection: PendingConnection];
+
+    /**
+     * Dispatched when a blast takes `amount` off an engine with a `maxHealth`, before it is wrecked by it. `health` already reads what is left.
+     */
+    siegeEngineDamage: [engine: SiegeEngine, amount: number, attacker: Player | null];
+
+    /**
+     * Dispatched when an engine's health runs out. Its operator and crew have been let go, and a stone still in its sling went down with it.
+     */
+    siegeEngineWreck: [engine: SiegeEngine, attacker: Player | null];
+
+    /**
+     * Dispatched immediately after a siege ladder is placed.
+     */
+    siegeLadderSpawn: [ladder: SiegeLadder];
+
+    /**
+     * Dispatched while a siege ladder is being removed. The handle still resolves.
+     */
+    siegeLadderDestroy: [ladder: SiegeLadder];
+
+    /**
+     * Dispatched when a player asks to push a `usable` ladder from the walk at its top, or to raise a fallen one from beside its foot. Return false to refuse.
+     */
+    siegeLadderUse: [player: Player, ladder: SiegeLadder, action: "push" | "raise"];
+
+    /**
+     * Dispatched when a pushed ladder hits the ground. Anyone who was on it was thrown off as it began to fall, and took the game's own fall.
+     */
+    siegeLadderFall: [ladder: SiegeLadder, pusher: Player | null];
+
+    /**
+     * Dispatched when a raised ladder leans on its wall again and can be climbed.
+     */
+    siegeLadderRaise: [ladder: SiegeLadder];
+
+    /**
+     * Dispatched immediately after a stone pile is placed.
+     */
+    stonePileSpawn: [pile: StonePile];
+
+    /**
+     * Dispatched while a stone pile is being removed. The handle still resolves.
+     */
+    stonePileDestroy: [pile: StonePile];
+
+    /**
+     * Dispatched when a player takes a stone off a pile. The game's own stone throwing has already lifted it and heaves it over the wall at once, so it cannot be refused; make the pile not `usable` to stop the next one.
+     */
+    stonePileThrow: [player: Player, pile: StonePile];
+
+    /**
+     * Dispatched where a thrown stone first met something, as its thrower saw it, checked to lie within 30 m of its pile. Players within the pile's `damageRadius` have been told to take their share, and NPCs have taken theirs.
+     */
+    stoneImpact: [pile: StonePile | null, position: Vector3, attacker: Player];
   }
 
   /** Names of native events available in this scripting environment. */
   type EventName = keyof EventMap;
 
+  /**
+   * Writable player stats, in native units. Use getStat and the server's setStat.
+   */
+  const PlayerStat: {
+    /**
+     * Current health, in native units. Zero can kill.
+     */
+    readonly Health: "health";
+
+    /**
+     * Current stamina; the game continues spending and regenerating it.
+     */
+    readonly Stamina: "stamina";
+
+    /**
+     * Current energy reserve; higher means better rested.
+     */
+    readonly Exhaust: "exhaust";
+
+    /**
+     * Current nourishment; higher means better fed.
+     */
+    readonly Hunger: "hunger";
+  };
+
+  /**
+   * Read-only computed player stats. Use getDerivedStat; these values cannot be passed to setStat.
+   */
+  const DerivedPlayerStat: {
+    /**
+     * Total bleeding strength.
+     */
+    readonly Bleeding: "bleeding";
+
+    /**
+     * Sleepiness; above zero means asleep.
+     */
+    readonly Sleeping: "sleeping";
+
+    /**
+     * Consciousness; zero means knocked out.
+     */
+    readonly Consciousness: "consciousness";
+
+    /**
+     * Native drunkenness value.
+     */
+    readonly Drunkenness: "drunkenness";
+
+    /**
+     * Native poisoning value; not every named poison changes this value.
+     */
+    readonly Poisoning: "poisoning";
+
+    /**
+     * Effective charisma.
+     */
+    readonly Charisma: "charisma";
+
+    /**
+     * Effective visibility.
+     */
+    readonly Visibility: "visibility";
+
+    /**
+     * Effective conspicuousness.
+     */
+    readonly Conspicuousness: "conspicuousness";
+
+    /**
+     * Effective noise.
+     */
+    readonly Noise: "noise";
+
+    /**
+     * Native dirtiness reading; reading it does not clean the body or equipment.
+     */
+    readonly Dirtiness: "dirtiness";
+
+    /**
+     * Native bloodiness reading.
+     */
+    readonly Bloodiness: "bloodiness";
+
+    /**
+     * Native smell reading.
+     */
+    readonly Smell: "smell";
+
+    /**
+     * Native smell intensity.
+     */
+    readonly SmellIntensity: "smellIntensity";
+
+    /**
+     * Native fragrance reading.
+     */
+    readonly Fragrance: "fragrance";
+
+    /**
+     * Carried weight in the same units as InventoryCapacity.
+     */
+    readonly CarriedWeight: "carriedWeight";
+
+    /**
+     * Native carrying capacity, including applicable equipment effects.
+     */
+    readonly InventoryCapacity: "inventoryCapacity";
+
+    /**
+     * Native encumbrance reading.
+     */
+    readonly Encumbrance: "encumbrance";
+
+    /**
+     * Native hangover reading.
+     */
+    readonly Hangover: "hangover";
+
+    /**
+     * Computed alcoholism reading, not the persistent soul resource.
+     */
+    readonly Alcoholism: "alcoholism";
+
+    /**
+     * Effective armor rating.
+     */
+    readonly ArmorRating: "armorRating";
+
+    /**
+     * Overall armor defense.
+     */
+    readonly OverallArmorDefense: "overallArmorDefense";
+
+    /**
+     * Overall weapon attack.
+     */
+    readonly OverallWeaponAttack: "overallWeaponAttack";
+
+    /**
+     * Normalized run speed; not world-space velocity.
+     */
+    readonly NormalizedRunSpeed: "normalizedRunSpeed";
+
+    /**
+     * Native base run speed.
+     */
+    readonly RunSpeedBase: "runSpeedBase";
+
+    /**
+     * Native morale reading.
+     */
+    readonly Morale: "morale";
+  };
+
   /**
    * How a player's body looks: four of the game's own character-component names, and the gender whose catalog they come from.
    * 
@@ -1024,11 +1249,11 @@ declare global {
   }
 
   /**
-   * Another player's blow, as `playerHit` shows it before the referee rules. `damage` is what the blow will take and `modifiers` scale how the server works it out; a handler may change either. Every other field describes what happened and is read-only in effect.
+   * A player or NPC blow, as `playerHit` shows it before the referee rules. `damage` is what the blow will take and `modifiers` scale how the server works it out; a handler may change either. Every other field describes what happened and is read-only in effect.
    */
   interface PlayerHit {
     /**
-     * Health the blow takes. For a swing the server works it out itself, the way the game does, from the attacker's weapon and its wear, both players' strength and skills, the armour the victim wears where it landed, the block and the perks and buffs it can vouch for; for an arrow it is what the victim's own game worked out. Set it and it stands as set: `modifiers` are then ignored. Never negative.
+     * Health the blow takes. For melee between players the server works it out itself, the way the game does, from the attacker's weapon and its wear, both players' strength and skills, the armour the victim wears where it landed, the block and the perks and buffs it can vouch for; for NPC melee or an arrow it is what the victim's own game worked out. Set it and it stands as set: `modifiers` are then ignored. Never negative.
      */
     damage: number;
 
@@ -1221,12 +1446,12 @@ declare global {
     readonly healthyStamina: number;
 
     /**
-     * Current tiredness, in the game's own units.
+     * Current energy reserve, in the game's own units. Higher means better rested.
      */
     readonly exhaust: number;
 
     /**
-     * Tiredness capacity, in the game's own units.
+     * Maximum energy reserve, in the game's own units.
      */
     readonly maxExhaust: number;
 
@@ -1296,7 +1521,7 @@ declare global {
     readonly relativeSkills: SoulSkills;
 
     /**
-     * The velocity the body's own animation was driven by this frame, not the one its physics settled on.
+     * On the owning machine, the velocity the body's own animation was driven by this frame, not the one its physics settled on. Everywhere else, measured from successive replicated positions.
      */
     readonly velocity: Vector3;
 
@@ -1310,21 +1535,6 @@ declare global {
      */
     readonly inAir: boolean;
 
-    /**
-     * The engine's own locomotion pace tag -- walk, jog, sprint -- as its animation system picked it. Raw Mannequin tag ids; 255 means nothing is set.
-     */
-    readonly moveSpeedTag: number;
-
-    /**
-     * The engine's own movement direction tag. Raw Mannequin tag ids; 255 means nothing is set.
-     */
-    readonly moveDirTag: number;
-
-    /**
-     * The engine's own stance tag -- upright, sneaking, sitting, lying. Raw Mannequin tag ids; 255 means nothing is set.
-     */
-    readonly stanceTag: number;
-
     /**
      * Whether this player is crouched, as their own game's crouch action reports it. False once their body is gone.
      */
@@ -1437,6 +1647,18 @@ declare global {
      */
     toString(): string;
 
+    /**
+     * Reads the latest reported stat in native units. Returns zero when no valid body snapshot exists; check player.ready to distinguish that from a real zero. Throws for an unknown stat or invalid arguments.
+     * @param stat A PlayerStat value.
+     */
+    getStat(stat: "health" | "stamina" | "exhaust" | "hunger"): number;
+
+    /**
+     * Reads a computed stat from the latest body snapshot. Bleeding, Sleeping, Consciousness, Drunkenness and Poisoning follow the body as it changes; the others are sampled about every 250 ms to a hundredth of a native unit, then replicated. Values use native units and can be negative; they are not universally percentages. Returns zero without a valid snapshot. Throws for an unknown stat or invalid arguments. These readings do not override another player's native calculations.
+     * @param stat A DerivedPlayerStat value.
+     */
+    getDerivedStat(stat: "bleeding" | "sleeping" | "consciousness" | "drunkenness" | "poisoning" | "charisma" | "visibility" | "conspicuousness" | "noise" | "dirtiness" | "bloodiness" | "smell" | "smellIntensity" | "fragrance" | "carriedWeight" | "inventoryCapacity" | "encumbrance" | "hangover" | "alcoholism" | "armorRating" | "overallArmorDefense" | "overallWeaponAttack" | "normalizedRunSpeed" | "runSpeedBase" | "morale"): number;
+
     /**
      * Where this player stands on one track: level, XP towards the next one, and unspent perk points.
      * @param track A track name, from `Progression.tracks()`.
@@ -1636,6 +1858,13 @@ declare global {
      */
     dropInventory(options?: { keepEquipped?: boolean }): Stash | null;
 
+    /**
+     * Dresses this player in one of the game's own outfits. Every piece of clothing they wear comes off and stays in their inventory, and a new set of the outfit's clothes is added and worn; weapons and everything else are left as they are. Their game dresses them a moment later, as it does after `Inventory.set`.
+     * @param preset One of the game's own outfits for this player's gender, by a name from `Player.outfitPresets(player.appearance.gender)` or its GUID.
+     * @returns True when the inventory was changed; false for a preset that is not in the catalog or is the other gender's, a player with no inventory, or an inventory with no room.
+     */
+    setOutfit(preset: string): boolean;
+
     /**
      * Reads this player's inventory; the same as `Inventory.get(player)`.
      * @returns A copy of it, or null for a player who is not connected.
@@ -1672,6 +1901,28 @@ declare global {
      */
     hasBuff(buff: string): boolean;
 
+    /**
+     * Sets health, stamina, energy or nourishment on the living body. Call once player.ready is true. Lowering health raises playerDamage with a null attacker; a fatal change also raises playerDied with a null killer. Zero health can kill. Does not clear buffs or revive; normal regeneration and consumption continue.
+     * @param stat Writable PlayerStat; derived stats are rejected.
+     * @param value Finite native value from 0 to 1000000, clamped to the native maximum. Positive health must exceed 0.00001; positive values must not underflow to zero.
+     * @returns True when sent, not confirmation of application; false for a missing, unready or dead body. Throws for invalid arguments or a read-only stat. Requests for a previous life are discarded. Read getStat after the client's next report to observe the result.
+     */
+    setStat(stat: "health" | "stamina" | "exhaust" | "hunger", value: number): boolean;
+
+    /**
+     * Sets this living player's health, raising or lowering it. Lowering raises playerDamage with a null attacker and the amount removed; a fatal change also raises playerDied with a null killer. This includes restoring a lower saved value. Zero can kill; this never revives a dead player. Leaves injuries, poison and bleeding in place. Call after playerSpawned or playerReady when restoring a saved value. The client applies the request asynchronously; health continues to show its last report until a new one arrives.
+     * @param value Health in the same units as player.health. Clamped to maxHealth on the player's client.
+     * @returns True when sent; false when the body is missing, not ready or dead. Throws unless value is a finite number from 0 to 1000000, with positive health greater than 0.00001 after conversion to native float units. A request for a life that has since ended is ignored.
+     */
+    setHealth(value: number): boolean;
+
+    /**
+     * Sets this living player's nourishment, raising or lowering it. Call after playerSpawned or playerReady when restoring a saved value. The client applies the request asynchronously; hunger continues to show its last report until a new one arrives.
+     * @param value Nourishment in the same units as player.hunger. Higher means better fed. Clamped to maxHunger on the player's client.
+     * @returns True when sent; false when the body is missing, not ready or dead. Throws unless value is a finite number from 0 to 1000000 that does not round from positive to zero in native float units. A request for a life that has since ended is ignored.
+     */
+    setHunger(value: number): boolean;
+
     /**
      * Nurses this player back, on their own client and with the game's own recipe -- the one its quests use for a full heal: the `remove_injuries` and `remove_all_posions` cures, which each wipe their whole kind of effect as they land, then health raised through the soul's own setter, the way a potion raises it. What comes off raises `playerInjuryHealed` and `playerBuffRemoved` as usual.
      * 
@@ -1725,11 +1976,19 @@ declare global {
     putDownItem(options?: { immediate?: boolean }): boolean;
 
     /**
-     * Puts this player in a horse's saddle, the way the game's own forced mount does -- their client plays the climb. It is an instruction to their client, so the seat is reported back like any other mount: `horseMounting` can still refuse it, and `horseMount` and `player.horse` follow once it lands. The player has to be standing near the horse; teleport them beside it first.
-     * @param horse The horse to climb onto.
+     * Puts this player in a horse's saddle. Everyone near enough to watch sees it the way it was asked for -- the get-on, or the instant seat -- while a client that only streams the rider in later finds them already seated. It is an instruction to their client, so the seat is reported back like any other mount: `horseMounting` can still refuse it, and `horseMount` and `player.horse` follow once it lands. The player has to be standing near the horse; teleport them beside it first.
+     * @param horse The horse to get on.
+     * @param options `instant` puts them straight into the seat, as the game's own forced mount does; by default they play the get-on a player plays at a horse.
      * @returns True when the order went out; false when the horse is dead or somebody else is riding it, or the player has no connection.
      */
-    mount(horse: Horse): boolean;
+    mount(horse: Horse, options?: { instant?: boolean }): boolean;
+
+    /**
+     * The game's own outfits, from its clothing presets: what `player.setOutfit` and `Npc.setOutfit` dress a body in. Many belong to one named character.
+     * @param gender Only the outfits authored for this gender. The game will not put a man's clothes on a woman or the reverse, so `player.setOutfit` takes only the presets of the player's own `appearance.gender`.
+     * @returns Preset names, men's first, each gender's in name order.
+     */
+    static outfitPresets(gender?: "male" | "female"): string[];
 
     /**
      * Lists every player currently connected, including those whose body has no pose yet.
@@ -1938,6 +2197,11 @@ declare global {
      */
     constructor(id: number);
 
+    /**
+     * The current route's status: idle, running, reached, blocked, or failed.
+     */
+    readonly navigationStatus: string;
+
     /**
      * What this horse wears, by slot: `saddle` (the saddlebags are part of it, and so is the carrying capacity they add), `head` (a bridle or chanfron), `torso` (a caparison), `shoe`. Item class names, null for an empty slot. A spawned horse wears the game's own tack for it unless `Horse.spawn` said otherwise. The gear changes the horse's stats as well as its look.
      */
@@ -2029,6 +2293,25 @@ declare global {
      */
     destroy(): void;
 
+    /**
+     * Routes an unridden horse over the server navigation mesh. Mounting cancels the order. Returns false without a mesh, for a dead or mounted horse, or invalid input.
+     * @param position Destination in world coordinates.
+     * @param options Defaults to walking and a 1.5 metre arrival radius.
+     */
+    moveTo(position: Vector3, options?: { speed?: 'walk' | 'jog' | 'run'; radius?: number }): boolean;
+
+    /**
+     * Patrols using the NPC route state machine. Requires a loaded mesh and an alive, unridden horse. Mounting cancels the patrol.
+     * @param points One to 256 waypoints.
+     * @param options Defaults to walking, looping, and no wait.
+     */
+    patrol(points: Vector3[], options?: { speed?: 'walk' | 'jog' | 'run'; loop?: boolean; waitSeconds?: number }): boolean;
+
+    /**
+     * Cancels navigation and holds an unridden horse where it stands. Does not take control from a rider.
+     */
+    hold(): void;
+
     /**
      * Makes this horse another player's. Every client makes it that player's horse in the game's own terms -- theirs is never a stolen horse -- and `horseOwnerChanged` follows. Ownership decides nothing about who may ride it: that is `horseMounting`'s to refuse. Throws when `player` is not a connected player.
      * @param player The horse's new owner, or null to leave it ownerless.
@@ -3824,7 +4107,7 @@ declare global {
     readonly soul: string;
 
     /**
-     * Entity class the body is spawned as -- `NPC` or `NPC_Female`.
+     * Native entity class, including `NPC`, `NPC_Female`, or the matching animal class from `Npc.animals()`.
      */
     readonly actorClass: string;
 
@@ -3844,7 +4127,7 @@ declare global {
     faction: number;
 
     /**
-     * The server's ledger of this body's health, clamped to `maxHealth`. Damage from players arrives here after the server has agreed to it.
+     * The server's ledger of this body's health, clamped to `maxHealth`. Combat damage arrives here after the server has agreed to it.
      */
     health: number;
 
@@ -3889,10 +4172,15 @@ declare global {
     locomotion: string;
 
     /**
-     * What the NPC has been told to do: `hold`, `moveTo`, `follow`, `flee`, `lookAt`, `playAnim` or `talk`.
+     * What the NPC has been told to do: `hold`, `moveTo`, `follow`, `flee`, `lookAt`, `playAnim`, `talk` or `attack`.
      */
     readonly intent: string;
 
+    /**
+     * Current patrol snapshot and progress, or null when not patrolling. Updating a route does not change a running patrol.
+     */
+    readonly patrolState: PatrolState | null;
+
     /**
      * What has become of the current order: `idle`, `running`, `reached`, `blocked` or `failed`. A move reads `running` from the moment it is given -- while its route is planned and while it walks the route's corners -- until it ends, and then the outcome `npcIntentDone` announced, which stays until the next order. A follow reads `reached` while it is within its radius. Dormant moves in `auto` or `server` mode are carried out and decided by the server; dormant `game` moves wait for a client simulator.
      */
@@ -3995,11 +4283,19 @@ declare global {
      * Walks the waypoints in order. The server stores the route and replicates the current target. `npcIntentDone` fires once per leg, after its final mesh corner or a movement failure.
      * 
      * A leg that ends `blocked` or `failed` is skipped after at least 2 seconds. When every leg of a lap has failed in a row, the patrol is abandoned and that last leg reports `failed` instead.
-     * @param points The waypoints, in order.
-     * @param options `loop` defaults to true; `waitSeconds` is the wait at each waypoint, 0 to 3600 (default 0); `speed` defaults to `walk`. `pathfinding` uses the modes documented for `moveTo` and applies to every leg.
+     * @param points Waypoints, a named route handle, or its stable id. Named routes are copied at start.
+     * @param options Point arrays retain their defaults: loop, walk, zero wait. Named routes use their authored defaults. Call options override route defaults; waypoint overrides take priority. Use mode for once, loop or pingPong; do not combine mode and loop. radius is the arrival distance. pathfinding uses the moveTo modes for every leg.
      * @returns True when the route was accepted; false for an empty route, more than 256 waypoints, a waypoint that is not finite or lies outside the world, or a `waitSeconds` that is not a number. Throws if server mode has no loaded mesh, leaving the previous order intact.
      */
-    patrol(points: (Vector3 | Partial<Vector3>)[], options?: { speed?: 'walk' | 'jog' | 'run'; loop?: boolean; waitSeconds?: number; pathfinding?: 'auto' | 'game' | 'server' }): boolean;
+    patrol(points: (Vector3 | Partial<Vector3>)[] | PatrolRoute | string, options?: { speed?: 'walk' | 'jog' | 'run'; loop?: boolean; mode?: 'once' | 'loop' | 'pingPong'; radius?: number; waitSeconds?: number; pathfinding?: 'auto' | 'game' | 'server' }): boolean;
+
+    /**
+     * Orders native combat against a live player or NPC in the same visible world within 128 metres. Another order stops it. The order fails when its target dies, disappears or leaves that range. It waits while dormant; no offline damage is simulated. Bow attacks stop within 18 metres and use native projectiles. Equipped NPC arrows are replenished while shooting.
+     * @param target The combatant to pursue and attack.
+     * @param options Defaults to melee. Bow requires an equipped bow and compatible arrows.
+     * @returns True when accepted. Invalid targets leave the previous order unchanged.
+     */
+    attack(target: Player | Npc | number, options?: { weapon?: "melee" | "bow" }): boolean;
 
     /**
      * Keeps the NPC near somebody as they move, steering straight at them. `npcIntentDone` reports `reached` the first time it catches up, and the follow carries on. If the body reports `blocked`, a loaded mesh lets the server route to the target's current position before reporting it. After recovery it resumes following the moving target.
@@ -4125,7 +4421,7 @@ declare global {
      * Spawns an NPC and replicates it. It exists on the server from this moment: every client near enough makes a body for it, one of them is elected to run it, and the rest draw what that one reports.
      * 
      * The body is not simulated until somebody is close enough to run it, which is not a failure -- a guard on the other side of the map has nothing to do that anybody can see. Read `simulator` to tell.
-     * @param options `soul` is a role name from `Npc.roles()` or a soul GUID; `position` is where to put it. Everything else has a default.
+     * @param options `soul` is a role from `Npc.roles()`, an animal name from `Npc.animals()`, or a soul GUID; `position` is where to put it. Everything else has a default.
      * @returns The new NPC's handle.
      */
     static create(options: { soul?: string; class?: string; name?: string; outfit?: string; wearing?: string[]; appearance?: Partial<Appearance>; position?: Vector3 | Partial<Vector3>; rotation?: Quaternion | Vector3 | Partial<Vector3>; faction?: number; health?: number; maxHealth?: number; locomotion?: 'kinematic' | 'native'; invulnerable?: boolean; frozen?: boolean; interactable?: boolean; nametag?: boolean; lootable?: boolean; virtualWorld?: number }): Npc;
@@ -4160,114 +4456,275 @@ declare global {
     static removeAll(virtualWorld?: number): number;
 
     /**
-     * The named kinds of NPC this build ships -- `guard`, `bandit`, `townswoman` and the rest. Each is a real soul out of the game's own tables, so a role spawns a body that already looks the part. Anything not in this list is taken as a soul GUID.
+     * The named kinds of NPC this build ships -- `guard`, `bandit`, `townswoman` and the rest. Each is a real soul out of the game's own tables, so a role spawns a body that already looks the part. Animal names are listed separately by `Npc.animals()`. Other values are taken as soul GUIDs.
      * @returns The role names.
      */
     static roles(): string[];
+
+    /**
+     * Animal souls with matching native classes. Pass a name or soul to Npc.create. Chickens use flock entities and are excluded.
+     */
+    static animals(): { name: string; soul: string; actorClass: string }[];
+
+    /**
+     * Level-authored animal spawners. Positions are markers and must be projected onto navigation. GUIDs are hex strings. Counts and respawn days describe the original game; scripts decide their population and respawn policy.
+     * @param level Defaults to the running server's level. Pass * for all levels.
+     */
+    static animalSpawnpoints(level?: string): { level: string; guid: string; name: string; layer: string; soul: string; actorClass: string; position: Vector3; count: number; respawnDays: number; spawnInFlock: boolean; spawnAreaGuid: string }[];
   }
 
   interface Npc extends Entity {}
 
   /**
-   * Replicated journal quest handle.
+   * One authored stop, independent of actor type.
    */
-  class Quest {
+  interface PatrolPoint {
     /**
-     * Creates a script wrapper for an existing quest with this ID; use Quest.give() to write one.
-     * @param id Network entity identifier.
+     * World-space waypoint.
      */
-    constructor(id: number);
+    position: Vector3;
 
     /**
-     * The key the quest is filed under, and the name the game knows the quest node by. Read-only: it is the quest's identity.
+     * Overrides the route and call speed for this leg.
      */
-    readonly key: string;
+    speed?: 'walk' | 'jog' | 'run' | undefined;
 
     /**
-     * The line the journal row and the quest toast show. Assignment is silent; it does not raise a toast.
+     * Wait after arrival, 0 to 3600 seconds.
      */
-    title: string;
+    waitSeconds?: number | undefined;
 
     /**
-     * The body of the journal's diary page for this quest. Assignment is silent.
+     * Arrival radius in metres.
      */
-    description: string;
+    radius?: number | undefined;
+  }
 
+  /**
+   * The format saved by World Builder and accepted by PatrolRoute.create.
+   */
+  interface PatrolRouteDefinition {
     /**
-     * Which section of the journal the quest files under. Read-only: it is decided when the quest is given.
+     * Stable globally unique id, up to 128 bytes. Use a namespace such as town.guard-loop.
      */
-    readonly type: string;
+    id: string;
 
     /**
-     * `active`, `done` or `failed`. Assignment announces the change; `setProgress` can do it quietly.
+     * Display name, up to 256 bytes.
      */
-    progress: string;
+    name?: string | undefined;
 
     /**
-     * Network id of the one player this quest was written for, or 0 when it went to everyone in the world. Read-only: who a quest belongs to is decided when it is given.
+     * 1 to 256 ordered waypoints.
      */
-    readonly player: number;
+    points: PatrolPoint[];
 
     /**
-     * How many objectives the quest carries, up to eight.
+     * Defaults to loop. Ping-pong visits each endpoint once per turn.
      */
-    readonly objectiveCount: number;
+    mode?: 'once' | 'loop' | 'pingPong' | undefined;
 
     /**
-     * Formats this quest handle for logging and debugging.
-     * @returns The quest ID, its key, its state and how many objectives it carries.
+     * Default leg speed; walk when omitted.
      */
-    toString(): string;
+    speed?: 'walk' | 'jog' | 'run' | undefined;
 
     /**
-     * Takes this quest out of every journal it was written into.
+     * Default arrival wait, 0 to 3600; defaults to zero.
      */
-    remove(): void;
+    waitSeconds?: number | undefined;
 
     /**
-     * Moves the quest on. There is no way back to unstarted: a quest nobody should see any more is removed.
-     * @param progress Where the quest now stands.
-     * @param announce Whether to raise the game's quest-updated toast; defaults to true. Pass false for a correction the player should not be told about.
+     * Default arrival radius; 1.5 metres when omitted.
      */
-    setProgress(progress: 'active' | 'done' | 'failed', announce?: boolean): void;
+    radius?: number | undefined;
+  }
 
+  /**
+   * A running patrol's snapshot. Indices and laps start at zero.
+   */
+  interface PatrolState {
     /**
-     * Rewrites one line of the quest in place.
-     * @param index Which objective to rewrite, counting from zero. An index past the end is ignored.
-     * @param objective The line, as text or as an object carrying its state.
-     * @param announce Whether to raise the quest-updated toast; defaults to true.
+     * Stable route id; null for an anonymous point-array patrol.
      */
-    setObjective(index: number, objective: string | { text: string; progress?: 'active' | 'done' | 'failed'; optional?: boolean; position?: Vector3 }, announce?: boolean): void;
+    routeId: string | null;
 
     /**
-     * Replaces the quest's objective list.
-     * @param objectives The whole list, at most eight entries; anything past that is dropped.
-     * @param announce Whether to raise the quest-updated toast; defaults to true.
+     * Target waypoint index.
      */
-    setObjectives(objectives: (string | { text: string; progress?: 'active' | 'done' | 'failed'; optional?: boolean; position?: Vector3 })[], announce?: boolean): void;
+    waypointIndex: number;
 
     /**
-     * Reads the quest's objectives back.
-     * @returns One entry per objective, in journal order. `position` is present only on an objective that has one.
+     * Completed loops or round trips.
      */
-    objectives(): { text: string; progress: 'active' | 'done' | 'failed' | 'none'; optional: boolean; position?: Vector3 }[];
+    lap: number;
 
     /**
-     * Makes the game follow this quest, exactly as the journal's track button does: it is listed in the HUD tracker, and every active objective that has a `position` is drawn as the game's own quest marker on the map and the compass. It is an instruction, not a lock -- the player can untrack it from the journal -- and the outcome arrives as `questTrackingChanged` like any other change. A quest given a moment ago can be tracked at once; the client waits for it to arrive.
-     * @param player Network id of the player who should follow the quest. Omitted, everyone who has the quest follows it: its one owner, or every player in its world.
-     * @returns How many clients were told. Zero when the player does not have this quest.
+     * 1 forward, -1 backward.
      */
-    track(player?: number): number;
+    direction: number;
 
     /**
-     * Makes the game stop following this quest, which takes its markers off the map and the compass. The outcome arrives as `questTrackingChanged`.
-     * @param player Network id of the player who should stop following the quest. Omitted, everyone who has the quest stops.
-     * @returns How many clients were told.
+     * Whether the actor is approaching or waiting at the waypoint.
      */
-    untrack(player?: number): number;
+    phase: 'moving' | 'waiting';
+  }
+
+  /**
+   * Named patrol definition. Actors snapshot it when ordered; update or destroy affects future starts.
+   */
+  class PatrolRoute {
+    private constructor();
 
     /**
-     * Writes a quest into the game's own journal. It is a replicated entity, so a player who joins late, reloads or walks away still finds it in their log -- which is what a quest needs and what a one-shot notification cannot do. What the player sees is the game's quest UI: its journal row, its diary page, its objective tracker and its quest-updated toast, all reading a quest node the client builds with the game's own constructor.
+     * False after destruction.
+     */
+    readonly exists: boolean;
+
+    /**
+     * Stable id; empty after destruction.
+     */
+    readonly id: string;
+
+    /**
+     * Display name.
+     */
+    readonly name: string;
+
+    /**
+     * Returns an independent definition, or null after destruction.
+     */
+    toJSON(): PatrolRouteDefinition | null;
+
+    /**
+     * Removes the definition. Active patrols keep their snapshots.
+     */
+    destroy(): boolean;
+
+    /**
+     * Updates defaults or waypoints atomically. Invalid input throws; a destroyed handle returns false.
+     * @param changes Fields to replace; id cannot change.
+     */
+    update(changes: Partial<PatrolRouteDefinition>): boolean;
+
+    /**
+     * Registers a route. Invalid data or a duplicate id throws.
+     * @param definition The route to register.
+     */
+    static create(definition: PatrolRouteDefinition): PatrolRoute;
+
+    /**
+     * Looks up a registered route.
+     * @param id Exact route id.
+     */
+    static getById(id: string): PatrolRoute | null;
+
+    /**
+     * Lists registered routes in creation order.
+     */
+    static all(): PatrolRoute[];
+  }
+
+  /**
+   * Replicated journal quest handle.
+   */
+  class Quest {
+    /**
+     * Creates a script wrapper for an existing quest with this ID; use Quest.give() to write one.
+     * @param id Network entity identifier.
+     */
+    constructor(id: number);
+
+    /**
+     * The key the quest is filed under, and the name the game knows the quest node by. Read-only: it is the quest's identity.
+     */
+    readonly key: string;
+
+    /**
+     * The line the journal row and the quest toast show. Assignment is silent; it does not raise a toast.
+     */
+    title: string;
+
+    /**
+     * The body of the journal's diary page for this quest. Assignment is silent.
+     */
+    description: string;
+
+    /**
+     * Which section of the journal the quest files under. Read-only: it is decided when the quest is given.
+     */
+    readonly type: string;
+
+    /**
+     * `active`, `done` or `failed`. Assignment announces the change; `setProgress` can do it quietly.
+     */
+    progress: string;
+
+    /**
+     * Network id of the one player this quest was written for, or 0 when it went to everyone in the world. Read-only: who a quest belongs to is decided when it is given.
+     */
+    readonly player: number;
+
+    /**
+     * How many objectives the quest carries, up to eight.
+     */
+    readonly objectiveCount: number;
+
+    /**
+     * Formats this quest handle for logging and debugging.
+     * @returns The quest ID, its key, its state and how many objectives it carries.
+     */
+    toString(): string;
+
+    /**
+     * Takes this quest out of every journal it was written into.
+     */
+    remove(): void;
+
+    /**
+     * Moves the quest on. There is no way back to unstarted: a quest nobody should see any more is removed.
+     * @param progress Where the quest now stands.
+     * @param announce Whether to raise the game's quest-updated toast; defaults to true. Pass false for a correction the player should not be told about.
+     */
+    setProgress(progress: 'active' | 'done' | 'failed', announce?: boolean): void;
+
+    /**
+     * Rewrites one line of the quest in place.
+     * @param index Which objective to rewrite, counting from zero. An index past the end is ignored.
+     * @param objective The line, as text or as an object carrying its state.
+     * @param announce Whether to raise the quest-updated toast; defaults to true.
+     */
+    setObjective(index: number, objective: string | { text: string; progress?: 'active' | 'done' | 'failed'; optional?: boolean; position?: Vector3 }, announce?: boolean): void;
+
+    /**
+     * Replaces the quest's objective list.
+     * @param objectives The whole list, at most eight entries; anything past that is dropped.
+     * @param announce Whether to raise the quest-updated toast; defaults to true.
+     */
+    setObjectives(objectives: (string | { text: string; progress?: 'active' | 'done' | 'failed'; optional?: boolean; position?: Vector3 })[], announce?: boolean): void;
+
+    /**
+     * Reads the quest's objectives back.
+     * @returns One entry per objective, in journal order. `position` is present only on an objective that has one.
+     */
+    objectives(): { text: string; progress: 'active' | 'done' | 'failed' | 'none'; optional: boolean; position?: Vector3 }[];
+
+    /**
+     * Makes the game follow this quest, exactly as the journal's track button does: it is listed in the HUD tracker, and every active objective that has a `position` is drawn as the game's own quest marker on the map and the compass. It is an instruction, not a lock -- the player can untrack it from the journal -- and the outcome arrives as `questTrackingChanged` like any other change. A quest given a moment ago can be tracked at once; the client waits for it to arrive.
+     * @param player Network id of the player who should follow the quest. Omitted, everyone who has the quest follows it: its one owner, or every player in its world.
+     * @returns How many clients were told. Zero when the player does not have this quest.
+     */
+    track(player?: number): number;
+
+    /**
+     * Makes the game stop following this quest, which takes its markers off the map and the compass. The outcome arrives as `questTrackingChanged`.
+     * @param player Network id of the player who should stop following the quest. Omitted, everyone who has the quest stops.
+     * @returns How many clients were told.
+     */
+    untrack(player?: number): number;
+
+    /**
+     * Writes a quest into the game's own journal. It is a replicated entity, so a player who joins late, reloads or walks away still finds it in their log -- which is what a quest needs and what a one-shot notification cannot do. What the player sees is the game's quest UI: its journal row, its diary page, its objective tracker and its quest-updated toast, all reading a quest node the client builds with the game's own constructor.
      * @param key What the quest is filed under: up to 64 letters, digits, underscores or dashes, unique within its virtual world.
      * @param title The line the journal row shows.
      * @param options `description` is the diary page, `type` the journal section, `objectives` the lines under it -- each with an optional world `position` the game marks on the map and compass while the quest is followed -- `player` the network id of the one player it belongs to, `announce` whether to raise the toast, and `track` whether its recipients start following it.
@@ -4529,6 +4986,88 @@ declare global {
     items: InventoryUnit[];
   }
 
+  /**
+   * A frozen snapshot of one stew pot in one virtual world.
+   */
+  interface CookPotSnapshot {
+    /**
+     * The fireplace's level GUID.
+     */
+    guid: string;
+
+    /**
+     * Position of the eating trigger.
+     */
+    position: { readonly x: number; readonly y: number; readonly z: number };
+
+    /**
+     * Unreserved meals remaining.
+     */
+    portions: number;
+
+    /**
+     * Portions in the most recent refill; sets the halfway point.
+     */
+    capacity: number;
+
+    /**
+     * Whether eating is allowed. Disabling preserves the contents.
+     */
+    enabled: boolean;
+
+    /**
+     * Visible food level, derived from remaining portions.
+     */
+    state: "empty" | "half" | "full";
+
+    /**
+     * Virtual world that owns this stock.
+     */
+    virtualWorld: number;
+  }
+
+  /**
+   * Server-owned stew pots. Stocked pots begin with four shared meals, with no automatic refill. State lasts until the server stops.
+   */
+  const CookPot: {
+    /**
+     * Lists every catalogued pot on the server's level in one virtual world; empty for a world no player or write has used yet.
+     * @param virtualWorld Virtual world id; defaults to 0. The global visibility sentinel is not a stock world.
+     */
+    all(virtualWorld?: number): CookPotSnapshot[];
+
+    /**
+     * Returns a snapshot, or null for an unknown pot.
+     * @param guid Fireplace level GUID from CookPot.all().
+     * @param virtualWorld Virtual world id; defaults to 0. The global visibility sentinel is not a stock world.
+     */
+    get(guid: string, virtualWorld?: number): CookPotSnapshot | null;
+
+    /**
+     * Replaces remaining stock and capacity, preserving enabled. Returns false for an unknown pot.
+     * @param guid Fireplace level GUID from CookPot.all().
+     * @param portions Integer from 0 to 1000; defaults to four.
+     * @param virtualWorld Virtual world id; defaults to 0. The global visibility sentinel is not a stock world.
+     */
+    refill(guid: string, portions?: number, virtualWorld?: number): boolean;
+
+    /**
+     * Allows or blocks eating. Returns false for an unknown pot.
+     * @param guid Fireplace level GUID from CookPot.all().
+     * @param enabled False blocks eating without changing stock or its appearance.
+     * @param virtualWorld Virtual world id; defaults to 0. The global visibility sentinel is not a stock world.
+     */
+    setEnabled(guid: string, enabled: boolean, virtualWorld?: number): boolean;
+
+    /**
+     * Changes food level and stock together, preserving enabled. Returns false for an unknown pot.
+     * @param guid Fireplace level GUID from CookPot.all().
+     * @param state Empty, two portions, or four portions; resets capacity to four.
+     * @param virtualWorld Virtual world id; defaults to 0. The global visibility sentinel is not a stock world.
+     */
+    setState(guid: string, state: "empty" | "half" | "full", virtualWorld?: number): boolean;
+  };
+
   /** */
   interface NearestDoor {
     /**
@@ -4864,12 +5403,12 @@ declare global {
     damageRadius: number;
 
     /**
-     * Whether players within 12 m of the engine get the game's own action hint for it on the use key: Load while it is idle, Fire while it is loaded. A press raises `siegeEngineUse`, and unless a handler refuses it the engine loads, or fires along the player's facing at `range`. Off by default.
+     * Whether players may work the engine. A player within 2 m of an empty one gets the game's own action hint on the use key to take its place, and becomes its `operator`; near a trebuchet with a `crewRequired`, a free winch is offered too. Each ask raises `siegeEngineUse` first, which may refuse it. Off by default.
      */
     usable: boolean;
 
     /**
-     * How far a shot fired from the native prompt goes along the player's facing, in metres; kept between `minRange` and `maxRange`. 150 for a trebuchet and 120 for a cannon to start with.
+     * How far a shot goes along the operator's facing when they fire before laying the engine anywhere, in metres; kept between `minRange` and `maxRange`. 150 for a trebuchet and 120 for a cannon to start with.
      */
     range: number;
 
@@ -4888,6 +5427,46 @@ declare global {
      */
     readonly loadDuration: number;
 
+    /**
+     * What the engine can take before it is wrecked; 0, the default, means nothing harms it. Setting it heals the engine to the new maximum and repairs a wreck. A blast within `damageRadius` of an engine -- any engine's, its own included -- takes its share of that shot's `damage` off it, raising `siegeEngineDamage`.
+     */
+    maxHealth: number;
+
+    /**
+     * What is left of `maxHealth`. Setting it to 0 wrecks the engine and raising it from 0 repairs one; ignored while `maxHealth` is 0.
+     */
+    health: number;
+
+    /**
+     * Whether the engine's health ran out. A wrecked cannon shows the game's broken gun and a wrecked trebuchet leans and settles; nothing loads, aims or fires it, and its operator and crew are let go, until `repair` or a new `maxHealth`.
+     */
+    readonly wrecked: boolean;
+
+    /**
+     * Shots left to load; each `load` takes one, and an engine with none refuses to load. -1, the default, never runs out; any negative value means the same.
+     */
+    ammo: number;
+
+    /**
+     * How many of the engine's winches must be manned for its arm to be winched down; 0, the default, winds it by itself. With fewer hands than this the winding holds where it is, and goes on when they come back. Players near a usable engine that needs them are offered its winches, and each one there plays the game's own pull. Kept to `crewPlaces`.
+     */
+    crewRequired: number;
+
+    /**
+     * How many winches the engine has: 2 on a trebuchet, 0 on a cannon.
+     */
+    readonly crewPlaces: number;
+
+    /**
+     * The player in the engine's place, or null. They lay it where they look while they hold the block key, load it with the torch key, fire it with the attack key and step away with the use key; walking off lets go of it too. `setOperator` puts somebody there.
+     */
+    readonly operator: Player | null;
+
+    /**
+     * Who mans each winch, in place order, with null for an empty one.
+     */
+    readonly crew: (Player | null)[];
+
     /**
      * Formats this engine handle for logging and debugging.
      * @returns The engine ID, its kind and where it is in its cycle.
@@ -4922,6 +5501,30 @@ declare global {
      */
     canHit(target: Vector3 | Partial<Vector3>): string;
 
+    /**
+     * Shows or hides the operator's aim guide: a translucent red beam along the shot's path -- out of a trebuchet's sling and along its arc, or straight from a cannon's muzzle -- to where it would come down, with a ball there. Off by default, which leaves laying the engine to the eye; the Fire hint says how far the shot goes either way.
+     * @param enabled Whether the operator sees the beam.
+     */
+    setAimGuide(enabled: boolean): void;
+
+    /**
+     * Whether the operator sees the aim guide; see `setAimGuide`.
+     * @returns True when the beam is shown.
+     */
+    getAimGuide(): boolean;
+
+    /**
+     * Makes the engine whole again: `health` back to `maxHealth`, and a wreck idle and unloaded.
+     */
+    repair(): void;
+
+    /**
+     * Puts a player in the engine's place without asking them, or takes whoever is there out of it. A player holds one place at a time, so they leave any other engine or winch first. Raises no `siegeEngineUse`.
+     * @param player Who takes the engine's place, or null to empty it.
+     * @returns False for a player who is no longer connected.
+     */
+    setOperator(player: Player | null): boolean;
+
     /**
      * Removes the engine on every client after emitting `siegeEngineDestroy`. A projectile already in the air still lands.
      */
@@ -5250,7 +5853,7 @@ declare global {
   }
 
   /**
-   * A named world export loaded from mod.world_resources. Server-owned, with live access to its surviving props, effects, level edits and areas. Obtain handles through all or find; runtime loading, reloading and unloading are not exposed.
+   * A named world export loaded from mod.world_resources. Server-owned, with live access to its surviving props, effects, level edits, areas and patrol routes. Obtain handles through all or find; runtime loading, reloading and unloading are not exposed.
    */
   class WorldResource {
     private constructor();
@@ -5295,6 +5898,11 @@ declare global {
      */
     readonly areas: Area[];
 
+    /**
+     * Surviving exported patrol definitions, in export order.
+     */
+    readonly patrolRoutes: PatrolRoute[];
+
     /**
      * True after every configured export has loaded successfully, even when the config list is empty. Check this before subscribing to worldResourcesReady when a script may start later.
      */
@@ -5847,7 +6455,7 @@ declare global {
   /**
    * Queries the level's navigation mesh on the server. The mesh includes walkable floors, bridges and stairs.
    * 
-   * Copy the game's `Data/Levels/<level>/recast.pak` to the server's `files/<level>/` directory. The server searches `files/` recursively at startup. An optional `mod.navmesh` in `server.json` takes priority and can name a game install, level folder or pak file. The game data must be supplied separately. Without a mesh, `ready` is false and geometry queries return null or false. Points are world-space metres, Z up. Every query takes an optional options object. `searchRadius` and `searchHeight` limit how far a point may be from the mesh, across the ground and up or down: 2 metres by default, up to 64, and 4 by default, up to 128. Keep `searchHeight` under a storey's height, or a point on one floor snaps to the floor above. `doors` picks which doors a query walks through: `unlocked`, the default, is how an NPC treats a door -- open or shut, it goes through unless the door is locked; `open` only through doors that stand open; `any` ignores locks; `none` treats every doorway as a wall. A door's state is read off the door in the global world. A field given with the wrong type or out of range throws.
+   * Copy the game's `Data/Levels/<level>/recast.pak` to the server's `files/<level>/` directory. The server searches `files/` recursively at startup. An optional `mod.navmesh` in `server.json` takes priority and can name a game install, level folder or pak file. The game data must be supplied separately. Without a mesh, `ready` is false and geometry queries return null or false. Points are world-space metres, Z up. Every query takes an optional options object. `searchRadius` and `searchHeight` limit how far a point may be from the mesh, across the ground and up or down: 2 metres by default, up to 64, and 4 by default, up to 128. Keep `searchHeight` under a storey's height, or a point on one floor snaps to the floor above. `doors` picks which doors a query walks through: `unlocked`, the default, is how an NPC treats a door -- open or shut, it goes through unless the door is locked; `open` only through doors that stand open; `any` ignores locks; `none` treats every doorway as a wall. Door states are read in the global world, except validatePatrol with an actor, which uses that actor's world. A field given with the wrong type or out of range throws.
    */
   const Navigation: {
     /**
@@ -5865,6 +6473,13 @@ declare global {
      */
     readonly activeOverlays: string[];
 
+    /**
+     * Checks all legs, including the closing leg of a loop and reverse legs of ping-pong. Uses the patrol runner's search budget. A single waypoint is checked against itself. Missing mesh reports available false; partial paths are incomplete. This does not start or change an actor's order.
+     * @param route A registered route or its id.
+     * @param options Optional actor chooses door policy in its virtual world: unlocked doors for humanoids, no doorways for horses and animals.
+     */
+    validatePatrol(route: PatrolRoute | string, options?: { actor?: Npc | Horse }): { available: boolean; complete: boolean; legs: { fromIndex: number; toIndex: number; complete: boolean; path: NavigationPath | null }[] };
+
     /**
      * Snaps a point to the nearest walkable surface.
      * @param point The point to snap; omitted components default to zero.
@@ -7250,6 +7865,16 @@ declare global {
      * True in the authoritative server scripting runtime.
      */
     readonly isServer: boolean;
+
+    /**
+     * Local Framework release version.
+     */
+    readonly frameworkVersion: string;
+
+    /**
+     * Local mod version from InstanceOptions.modVersion; empty when unset.
+     */
+    readonly modVersion: string;
   };
 
   /**
@@ -7663,7 +8288,7 @@ declare global {
 
     /**
      * Overrides the text drawn on this player's nametag.
-     * @param text Text to show instead of the player's name; empty or omitted restores the name.
+     * @param text Text to show instead of the player's name, cut to 64 bytes; empty or omitted restores the name.
      */
     setNametagText(text?: string): void;
 
@@ -7676,6 +8301,219 @@ declare global {
 
   interface BasePlayer extends Entity {}
 
+  /** */
+  interface SiegeLadderKind {
+    /**
+     * Its name: `siege`, `tall`, `short` or `low`.
+     */
+    kind: string;
+
+    /**
+     * The mesh it stands as, a path from the shared prop catalog.
+     */
+    model: string;
+
+    /**
+     * How far up its rungs go, in metres.
+     */
+    height: number;
+
+    /**
+     * How far it leans towards the wall standing, in degrees about its own X; it leans towards its forward.
+     */
+    lean: number;
+  }
+
+  /**
+   * Replicated handle for a siege ladder leaning on a wall.
+   */
+  class SiegeLadder {
+    /**
+     * Creates a script wrapper for an existing siege ladder with this ID; use SiegeLadder.spawn() to place one.
+     * @param id Network entity identifier.
+     */
+    constructor(id: number);
+
+    /**
+     * Which of the game's ladders it is: `siege` (the Suchdol siege ladder, 9.75 m), `tall` (5.5 m), `short` (3.25 m) or `low` (2 m).
+     */
+    readonly kind: string;
+
+    /**
+     * `standing` against its wall, `pushed` (a defender's swing, then its fall), `down`, `raising` or `broken`. Named `pose` because every entity already has a `state`, which is its state bag.
+     */
+    readonly pose: string;
+
+    /**
+     * How far up its rungs go, in metres: its top rests this high above its foot on the wall's top. Pick the kind whose height meets the walk.
+     */
+    readonly height: number;
+
+    /**
+     * Whether the game's own climb is offered on it: while it stands and nobody has started to push it.
+     */
+    readonly climbable: boolean;
+
+    /**
+     * Whether players are offered the push at its top and the raise at the foot of a fallen one, each raising `siegeLadderUse` first. On by default. The climb is the game's and is offered whenever the ladder stands.
+     */
+    usable: boolean;
+
+    /**
+     * Who last pushed it, or null.
+     */
+    readonly pusher: Player | null;
+
+    /**
+     * Formats this ladder handle for logging and debugging.
+     * @returns The ladder ID, its kind and its pose.
+     */
+    toString(): string;
+
+    /**
+     * Pushes a standing ladder off its wall. It stands through the swing, falls away from the wall as the blade meets it -- throwing off anyone climbing it -- and lies where it lands, about 4.5 seconds later.
+     * @param player Who pushes it: they play the game's own halberd push, and are credited with it in `siegeLadderFall`.
+     * @returns What happened, and the phrase to explain it with when nothing did.
+     */
+    push(player?: Player | number | null): SiegeResult;
+
+    /**
+     * Lays a fallen ladder back against its wall, over the lift's 5.7 seconds.
+     * @param player Who raises it: they play the game's own ladder lift.
+     * @returns What happened, and the phrase to explain it with when nothing did.
+     */
+    raise(player?: Player | number | null): SiegeResult;
+
+    /**
+     * Breaks the ladder: it lies in pieces where it stands, anyone on it falls, and nothing raises it until `repair`.
+     */
+    break(): void;
+
+    /**
+     * Puts a fallen or broken ladder back against its wall at once.
+     */
+    repair(): void;
+
+    /**
+     * Removes the ladder on every client after emitting `siegeLadderDestroy`.
+     */
+    destroy(): void;
+
+    /**
+     * Places one of the game's own ladders leaning on a wall, the way the Suchdol and Nebakov sieges stand theirs: the game's climb, and the game's step off over the palisade at its top, which wants the top a little over the walk.
+     * @param kind `siege`, `tall`, `short` or `low`.
+     * @param position Where its foot stands, on the ground below the wall.
+     * @param rotation Its facing: forward is the way to the wall it leans on. A Quaternion, or a Vector3 of Euler angles in degrees.
+     * @param virtualWorld Optional virtual world the ladder belongs to; omitted puts it in the global one.
+     * @returns The new ladder's handle.
+     */
+    static spawn(kind: string, position: Vector3 | Partial<Vector3>, rotation?: Vector3 | Quaternion, virtualWorld?: number): SiegeLadder;
+
+    /**
+     * What one kind of ladder is: its mesh, its climb and its lean -- what a placement preview needs to show it as it will stand.
+     * @param kind `siege`, `tall`, `short` or `low`.
+     * @returns The kind, or null for a name that is not one.
+     */
+    static describe(kind: string): SiegeLadderKind | null;
+
+    /**
+     * Lists the siege ladders the server has.
+     * @param virtualWorld Optional virtual world to list; omitted lists every one.
+     * @returns One handle per ladder, in no particular order.
+     */
+    static all(virtualWorld?: number): SiegeLadder[];
+
+    /**
+     * Looks a ladder up by its network entity ID.
+     * @param id Network entity identifier.
+     * @returns The ladder's handle, or null when no live ladder has that ID.
+     */
+    static getById(id: number): SiegeLadder | null;
+
+    /**
+     * Removes siege ladders, emitting `siegeLadderDestroy` for each one.
+     * @param virtualWorld Optional virtual world to clear; omitted clears every one.
+     * @returns How many were removed.
+     */
+    static destroyAll(virtualWorld?: number): number;
+  }
+
+  interface SiegeLadder extends Entity {}
+
+  /**
+   * Replicated handle for a pile of hurling stones on a battlement.
+   */
+  class StonePile {
+    /**
+     * Creates a script wrapper for an existing stone pile with this ID; use StonePile.spawn() to place one.
+     * @param id Network entity identifier.
+     */
+    constructor(id: number);
+
+    /**
+     * Stones left to throw; each throw takes one, and a pile with none offers nothing. Players see at most nine in the heap. -1, the default, never runs out; any negative value means the same.
+     */
+    stones: number;
+
+    /**
+     * Whether players are offered the game's own prompt at the pile. On by default.
+     */
+    usable: boolean;
+
+    /**
+     * Health taken from anyone at the point a stone comes down, up to 1000; a quarter of it reaches the edge of `damageRadius`. 60 to start with; a player has 100.
+     */
+    damage: number;
+
+    /**
+     * How far from where a stone comes down anyone is hurt, in metres, up to 10. 1.5 to start with.
+     */
+    damageRadius: number;
+
+    /**
+     * Formats this pile handle for logging and debugging.
+     * @returns The pile ID and the stones it has left.
+     */
+    toString(): string;
+
+    /**
+     * Removes the pile on every client after emitting `stonePileDestroy`. A stone already thrown still lands.
+     */
+    destroy(): void;
+
+    /**
+     * Places the game's own battlement pile of hurling stones, the Nebakov and Suchdol defenders' heap. Its prompt, the lift and the heave over the wall are the game's stone throwing; each stone is a real rigid body that falls where it falls.
+     * @param position Where the thrower stands on the walk, behind the parapet.
+     * @param rotation Its facing: forward is the way the stones go, over the wall. A Quaternion, or a Vector3 of Euler angles in degrees.
+     * @param virtualWorld Optional virtual world the pile belongs to; omitted puts it in the global one.
+     * @returns The new pile's handle.
+     */
+    static spawn(position: Vector3 | Partial<Vector3>, rotation?: Vector3 | Quaternion, virtualWorld?: number): StonePile;
+
+    /**
+     * Lists the stone piles the server has.
+     * @param virtualWorld Optional virtual world to list; omitted lists every one.
+     * @returns One handle per pile, in no particular order.
+     */
+    static all(virtualWorld?: number): StonePile[];
+
+    /**
+     * Looks a pile up by its network entity ID.
+     * @param id Network entity identifier.
+     * @returns The pile's handle, or null when no live pile has that ID.
+     */
+    static getById(id: number): StonePile | null;
+
+    /**
+     * Removes stone piles, emitting `stonePileDestroy` for each one.
+     * @param virtualWorld Optional virtual world to clear; omitted clears every one.
+     * @returns How many were removed.
+     */
+    static destroyAll(virtualWorld?: number): number;
+  }
+
+  interface StonePile extends Entity {}
+
   /**
    * Calls a function once after a delay.
    * @param handler Function to call.