@kingdomsconnected/types 1.5.6 → 1.6.0

package/generated/server-api.d.ts

@@ -74,6 +74,21 @@ declare global {
      */
     playerPutDown: [carrier: Player, carried: Player];
 
+    /**
+     * Dispatched when a player starts a carry of their own, before the server accepts it: they chose the game's pick-up prompt over a carryable `groundItem`, or took an item from one of the world's own piles (`groundItem` null). Return `false` from a handler and the carry is refused -- the prop stays where it is, and a pile's item is let go at once. Handlers run synchronously, so the decision cannot wait on anything awaited. A carry a script ordered with `carryItem` is not asked. `item` is the item's name.
+     */
+    playerCarryingItem: [player: Player, item: string, groundItem: GroundItem | null];
+
+    /**
+     * Dispatched once an item carry is accepted: everybody sees the player pick it up and carry it, and `player.carriedItem` names it. `groundItem` is the prop it was taken up from, still readable here and gone a moment later, or null. It is carried until `playerPutDownItem`.
+     */
+    playerCarryItem: [player: Player, item: string, groundItem: GroundItem | null];
+
+    /**
+     * Dispatched once an item carry is over, however it ended: the player put it down, `putDownItem` asked them to, it went into a pile, or they left. `groundItem` is the carryable prop it became where it fell -- still falling, settling where the game's physics puts it -- or null when it went into a pile or they have no room left on the ground.
+     */
+    playerPutDownItem: [player: Player, item: string, groundItem: GroundItem | null];
+
     /**
      * Dispatched once a joining player is really standing in the world: their level is up, their body is where `playerSpawning` put it, and the ground under it has loaded. Anything that acts on an arriving player -- kit, a welcome line, a marker -- belongs here rather than in `playerConnect`, which fires while they are still loading the level, or in `playerSpawning`, where the body is still mid-placement.
      * 
@@ -204,6 +219,11 @@ declare global {
      */
     diceMatchEnd: [match: number, first: Player | null, second: Player | null, winner: number, reason: string, firstScore: number, secondScore: number];
 
+    /**
+     * Synchronous decision before an unfinished craft settles, including when no native refund is due. Call refund() to request a full refund; return values are ignored. No handler or no call preserves native rules. JavaScript exceptions are logged and do not cancel a call already made. The callback expires on return; delayed calls do nothing. The `cancelled`, `interrupted` and `clientError` reasons are reported by the player's own client: a modified client can send any of them, so refunding on one lets that client keep its materials. Never grants a completed craft twice. craftingEnded follows the actual inventory changes.
+     */
+    craftingRefunding: [player: Player, proposal: CraftRefundProposal, refund: () => void];
+
     /**
      * A player asks to open an alchemy table, or to begin a smithing recipe. Every handler runs; one returning literal `false` refuses it. An async handler cannot refuse.
      */
@@ -275,7 +295,7 @@ declare global {
     cartEntering: [cart: Cart, player: Player, seat: string];
 
     /**
-     * Dispatched after a player is given a seat. `seat` is `driver` or `back`; a driver's client runs the cart from here on.
+     * Dispatched after a player is given a seat, named as in `cart.seats`; the `driver` seat's client runs the cart from here on.
      */
     cartEnter: [cart: Cart, player: Player | null, seat: string];
 
@@ -325,7 +345,7 @@ declare global {
     npcDestroy: [npc: Npc];
 
     /**
-     * Dispatched when an NPC finishes what it was told to do. `status` is `reached` when it arrived, `blocked` when it could not make progress, or `failed` when the order could not be carried out at all. A patrol steps on this event, so a handler that re-orders the NPC here replaces the route rather than racing it.
+     * Dispatched once when an NPC finishes what it was told to do. `status` is `reached` when it arrived, `blocked` when it could not make progress, or `failed` when the order could not be carried out at all, or when a patrol gives up. Server-planned intermediate corners do not raise this event, and neither does a change of simulator: a finished order is not reported twice. A follow, which never finishes, raises `reached` the first time it catches up and again only after a change of simulator. A patrol steps on this event, so a handler that re-orders the NPC here replaces the route rather than racing it.
      */
     npcIntentDone: [npc: Npc, status: string];
 
@@ -396,6 +416,36 @@ declare global {
      */
     doorInteract: [player: Player, door: Door, action: "open" | "close" | "unlock" | "lockpick", keySide: boolean];
 
+    /**
+     * Dispatched immediately after a siege engine is built.
+     */
+    siegeEngineSpawn: [engine: SiegeEngine];
+
+    /**
+     * Dispatched while a siege engine is being removed. The handle still resolves.
+     */
+    siegeEngineDestroy: [engine: SiegeEngine];
+
+    /**
+     * Dispatched when an engine's load cycle finishes and it can fire.
+     */
+    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.
+     */
+    siegeEngineUse: [player: Player, engine: SiegeEngine, action: "load" | "fire"];
+
+    /**
+     * Dispatched the moment an engine lets its projectile go, partway through the shot `fire` started.
+     */
+    siegeFire: [engine: SiegeEngine, attacker: Player | null, target: Vector3];
+
+    /**
+     * Dispatched where a projectile came down: what the player nearest the target saw it hit, checked against the arc it was thrown on, or the target itself when nobody could see it. Players within `damageRadius` have already been told to take their share, and NPCs have taken theirs. `engine` is null when it was destroyed while the stone was in the air.
+     */
+    siegeImpact: [engine: SiegeEngine | null, position: Vector3, attacker: Player | null];
+
     /**
      * Dispatched when a body comes to be inside an enabled area: it walked or rode in, or the area was created, moved, reshaped or enabled around it. The server decides this itself from the pose it already replicates, by the game's own rule for that kind of area, so a client cannot claim it. `matchingVirtualWorld` is false when a script area bound to one world is crossed by a body in another; a level area is in every world.
      */
@@ -407,12 +457,12 @@ declare global {
     areaExit: [area: Area, entity: Player | Horse | Cart | Npc, matchingVirtualWorld: boolean];
 
     /**
-     * A container now exists: one a script spawned, or one the level places, built in a virtual world the first time anything there asked for it. Every container starts empty; restore saved contents here with `setInventory`. The level's containers in the global world are built before any resource runs, so restore those from `resourceStart` by walking `Stash.all()`.
+     * A container now exists: a scripted chest, a virtual stash, or one the level places, built in a virtual world the first time anything there asked for it. Every container starts empty; restore saved contents here with `setInventory`. The level's containers in the global world are built before any resource runs, so restore those from `resourceStart` by walking `Stash.all()`.
      */
     stashSpawn: [stash: Stash];
 
     /**
-     * A player opened a container and sees what it holds.
+     * A player holds a container view. Physical chests report the native opening; virtual stashes report the server grant before requesting the native screen.
      */
     stashOpen: [stash: Stash, player: Player];
 
@@ -432,9 +482,9 @@ declare global {
     stashDestroy: [stash: Stash];
 
     /**
-     * Dispatched when a player presses a container's prompt, before anything happens: the player's client holds the game's own handler until the server answers. `action` is `open`, `unlock` -- a key turned, which opens it in the same use -- or `lockpick`, the minigame starting; a successful pick then opens it without asking again.
+     * Dispatched for a physical chest prompt or virtual stash open(player), before access is granted. For a prompt: the player's client holds the game's own handler until the server answers. `action` is `open`, `unlock` -- a key turned, which opens it in the same use -- or `lockpick`, the minigame starting; a successful pick then opens it without asking again.
      * 
-     * Return false to refuse it: the prompt does nothing, and no transfer screen, key or minigame ever appears. Every handler runs whatever an earlier one returned, and an async handler cannot refuse. The server has already refused what the game's own rules forbid -- a player out of reach, a container another player has open, opening a locked one, picking one that cannot be -- so this only sees what the game would allow. Closing is never asked.
+     * Return false to refuse it: the prompt does nothing, and no transfer screen, key or minigame ever appears. Every handler runs whatever an earlier one returned, and an async handler cannot refuse. The server has already refused what the game's own rules forbid -- a player out of reach, a container another player has open, opening a locked one, picking one that cannot be -- so this only sees what the game would allow. Virtual opening has no distance check; world, player readiness, lock and exclusive access checks still apply. Closing is never asked.
      */
     stashInteract: [player: Player, stash: Stash, action: "open" | "unlock" | "lockpick"];
 
@@ -1198,6 +1248,11 @@ declare global {
      */
     readonly carriedBy: Player | null;
 
+    /**
+     * The item this player carries in their arms, by its item name, or null. Set once `playerCarryItem` has fired, cleared once `playerPutDownItem` has.
+     */
+    readonly carriedItem: string | null;
+
     /**
      * The horse this player is riding, or null when they are on foot.
      */
@@ -1330,10 +1385,10 @@ declare global {
      * 
      * A hand tag is only half of holding something. `r_bucket` makes the body move as if it carried a bucket, but the bucket itself is a `props` entry.
      * @param fragment A Mannequin fragment, as `Animations.list` names it. `""` plays none and only puts the props and tags on, which with a hand tag like `r_bucket` makes the player carry something while they walk.
-     * @param options `tags` pick the variant, `loop` repeats it until stopped, `lockMovement` holds the player still, `props` puts up to two models in their hands.
+     * @param options `clip` plays a clip the server streams instead of a fragment (`animations/kcdc/<resource>/wave.caf`, the fragment left `""`), `tags` pick the variant, `loop` repeats it until stopped, `lockMovement` holds the player still, `props` puts up to two models in their hands.
      * @returns True when the request went out; false for a player with no body yet. Throws for a prop or option it cannot use.
      */
-    playAnimation(fragment: string, options?: { tags?: string; loop?: boolean; lockMovement?: boolean; props?: { item?: string; model?: string; hand?: 'right' | 'left'; joint?: string; position?: Vector3 | Partial<Vector3>; rotation?: Quaternion | Vector3 | Partial<Vector3> } | { item?: string; model?: string; hand?: 'right' | 'left'; joint?: string; position?: Vector3 | Partial<Vector3>; rotation?: Quaternion | Vector3 | Partial<Vector3> }[] }): boolean;
+    playAnimation(fragment: string, options?: { clip?: string; tags?: string; loop?: boolean; lockMovement?: boolean; props?: { item?: string; model?: string; hand?: 'right' | 'left'; joint?: string; position?: Vector3 | Partial<Vector3>; rotation?: Quaternion | Vector3 | Partial<Vector3> } | { item?: string; model?: string; hand?: 'right' | 'left'; joint?: string; position?: Vector3 | Partial<Vector3>; rotation?: Quaternion | Vector3 | Partial<Vector3> }[] }): boolean;
 
     /**
      * Ends what `playAnimation` started at once, takes its props away and hands the body back to the game. A stance tag the animation set goes with it, so without `standUp` a seated player pops upright.
@@ -1468,7 +1523,7 @@ declare global {
      * The game's own camera sits in the head, which the mesh now covers: pair this with the client's `Camera.setThirdPerson` for the disguised player. Nametags are not touched; `setNametagVisible` is the call for that. NPCs still see a person.
      * 
      * The owning client is authoritative for its body, so this is a request that lands on their next frame; `player.disguise` reads what they actually have on.
-     * @param model A mesh from the prop catalog, by its `objects/...cgf` path or its file stem -- anything `Prop.spawn` takes. Null puts the player back in their own body.
+     * @param model A mesh from the prop catalog, by its `objects/...cgf` path or its file stem, or one this server streams by its full path -- anything `Prop.spawn` takes. Null puts the player back in their own body.
      * @returns True when the request went out; false for a player with no connection to ask. Throws for a model the catalog does not carry.
      */
     setDisguise(model: string | null): boolean;
@@ -1485,6 +1540,24 @@ declare global {
      */
     putDown(): boolean;
 
+    /**
+     * Has this player carry an item in their arms, the way the game's own people carry firewood, sacks and baskets: the carrying walk, and the put-down at the end. While it is carried they walk, since the game has no running with a load.
+     * 
+     * It is an instruction to their client, so the carry lands when that client reports it: `playerCarryItem` and `carriedItem` follow. A carry a script ordered is not put to `playerCarryingItem`. The item never enters their inventory. Put down -- with the game's own key or `putDownItem` -- it falls from their hands and becomes a carryable `GroundItem` where it lands, which `playerPutDownItem` hands over and anybody can take up again.
+     * 
+     * Their hands have to be free -- a drawn weapon or a torch makes their game refuse the carry, and nothing is reported.
+     * @param item What to carry. A name from `Animations.props()` whose `hand` the game has a carrying walk for -- the baskets (`basket_full_wood`, `basket_b_apples`, `stonebasket`, `eggbasket`, `shoppingbasket`), `firewoodChipsHand`, the buckets (`waterBucket`, `milkBucket`), and for a man only the sacks (`sack`, `sack_miller`), `barrel` and `crate_with_silver` -- puts a new one straight into their hands. A `GroundItem` of such a class has them pick that one up off the ground with the game's own bend-down; it has to be a single item within their reach.
+     * @returns True when the order went out; false when they cannot act, are riding, already carry an item or a body, the stack is not resting within their reach or somebody else is taking it, or they have no connection. Throws for an item with no carrying walk, or none for this player's body.
+     */
+    carryItem(item: string | GroundItem): boolean;
+
+    /**
+     * Has this player put down the item in their arms, with the game's own put-down. It is an instruction to their client, so the carry ends when that put-down lands: `playerPutDownItem` follows then.
+     * @param options `immediate` lets go at once, without the put-down.
+     * @returns True when the order went out; false when they carry no item or have no connection.
+     */
+    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.
@@ -1911,7 +1984,7 @@ declare global {
     /**
      * Draws the row greyed and unpickable when false. A rendering hint only -- the server re-checks the choice when it arrives, so nothing a row costs may rely on this.
      */
-    enabled: boolean | undefined;
+    enabled?: boolean | undefined;
   }
 
   /**
@@ -1921,12 +1994,12 @@ declare global {
     /**
      * Shown above the options. Omit it for a list with no preamble.
      */
-    line: string | undefined;
+    line?: string | undefined;
 
     /**
      * Draws the list on the right of the screen instead of the left.
      */
-    onRight: boolean | undefined;
+    onRight?: boolean | undefined;
 
     /**
      * The rows, at least one and at most eight. A page with none is refused.
@@ -1978,17 +2051,17 @@ declare global {
     /**
      * Shown in the server's log only. The trade screen names whoever keeps the shop.
      */
-    name: string | undefined;
+    name?: string | undefined;
 
     /**
      * Money units the vendor starts with, and all it can pay out. Omit it for a purse that never runs out.
      */
-    purse: number | undefined;
+    purse?: number | undefined;
 
     /**
      * Whether the vendor takes the player's items at all. On by default; `setBuyPrices` says which ones.
      */
-    buys: boolean | undefined;
+    buys?: boolean | undefined;
   }
 
   /**
@@ -2155,6 +2228,26 @@ declare global {
     amount: number;
   }
 
+  /**
+   * A dice table placed by the current level. The catalog includes quest-layer tables that may not currently be loaded on a client.
+   */
+  interface DiceTableInfo {
+    /**
+     * The table's level GUID as sixteen lowercase hex digits.
+     */
+    id: string;
+
+    /**
+     * The world-space midpoint between the table's two seat alignment points, in metres. The behavior entity itself may be offset from this interaction centre.
+     */
+    position: Vector3;
+
+    /**
+     * The two sitting smart-object GUIDs, in native seat order. Compare with a seated player's seatGuid; these are not the minigame's alignment tagpoints.
+     */
+    seats: [string, string];
+  }
+
   /**
    * How a dice match is played.
    */
@@ -2162,7 +2255,7 @@ declare global {
     /**
      * The score that wins, banked at the end of a turn. 2000 when omitted, at most 100000.
      */
-    targetScore: number | undefined;
+    targetScore?: number | undefined;
   }
 
   /**
@@ -2171,6 +2264,12 @@ declare global {
    * Both players sit down at the dice table nearest them and play it as they would against an NPC, the other player's body opposite. Every throw is dealt and every move checked by the server, by the game's own scoring rules; badges and dice perks are off, so a match is decided by the dice and the decisions alone.
    */
   const Dice: {
+    /**
+     * Lists the current level's dice tables and their seats. The same placements exist in every virtual world; readiness and occupancy belong to the gamemode.
+     * @returns The level's tables, in GUID order.
+     */
+    tables(): DiceTableInfo[];
+
     /**
      * Starts a match. Both players must stand together, within a few metres, at a dice table, and neither may be playing already. Throws an Error saying why when it cannot start.
      * @param first NetworkID of the player on the table's first seat.
@@ -2385,6 +2484,66 @@ declare global {
     knowledge: Record<string, number> | undefined;
   }
 
+  /**
+   * An original ingredient still held by this session, including its original inventory properties.
+   */
+  interface CraftRefundMaterial {
+    /**
+     * Item class GUID.
+     */
+    item: string;
+
+    /**
+     * Units originally removed and not already returned.
+     */
+    amount: number;
+
+    /**
+     * Original canonical inventory properties, preserved by refunds.
+     */
+    metadata: Record<string, unknown>;
+  }
+
+  /**
+   * An unfinished craft before material settlement. Frozen. Call the event's refund callback synchronously to request all its materials back; otherwise the native refund rules apply.
+   */
+  interface CraftRefundProposal {
+    /**
+     * Which craft.
+     */
+    kind: 'alchemy' | 'smithing';
+
+    /**
+     * The session being settled, once only.
+     */
+    session: string;
+
+    /**
+     * Station id.
+     */
+    station: string;
+
+    /**
+     * The session's virtual world.
+     */
+    virtualWorld: number;
+
+    /**
+     * No product was granted for this craft.
+     */
+    outcome: 'failed' | 'cancelled';
+
+    /**
+     * Why it ended: cancelled for normal native or script cancellation; interrupted for native teardown without a normal exit; clientError for an alchemy adapter failure; craftingFailed for a broken smithing workpiece. Server closures also include disconnected, timeout and contextInvalidated; settlement refusals retain their existing reasons. Client exit reasons are observations, not server-verified combat evidence.
+     */
+    reason: string;
+
+    /**
+     * All remaining original ingredients, including processed alchemy ingredients. Station liquids and ingredients already returned are excluded. Do not grant these yourself; call refund().
+     */
+    materials: CraftRefundMaterial[];
+  }
+
   /**
    * A batch or workpiece that is over, for any reason. A table kept for the next batch is not closed by this.
    */
@@ -2415,12 +2574,12 @@ declare global {
     outcome: 'success' | 'failed' | 'cancelled';
 
     /**
-     * Empty for a completed batch or a workpiece the game finished or broke. `craftingCompletingRejected` when a handler refused the result; `cancelled` by the player or a script; `disconnected`; `timeout` after 30 minutes; `contextInvalidated` when the player walked away, died or changed world. Smithing adds `abandoned` (the recipe never reached the anvil), `abandonTooLate`, `invalidQuality` and `inventoryUnavailable`.
+     * Empty for a completed batch or a successful workpiece. `craftingFailed` for a broken workpiece; `cancelled` for normal native or script cancellation; `interrupted` for unexpected native teardown; `clientError` for alchemy adapter errors. Other reasons: `craftingCompletingRejected`, `disconnected`, `timeout`, `contextInvalidated`, and for smithing `abandoned`, `abandonTooLate`, `invalidQuality`, `inventoryUnavailable`. See CraftRefundProposal.
      */
     reason: string;
 
     /**
-     * The inventory rows ingredients went back to. Alchemy: wholly unmilled bowl, mortar and herb groups come back; everything else put on the table was spent. Smithing: a failed workpiece spends half of each divisible material, rounded down, and a coin decides a single unit; the rest comes back.
+     * The inventory rows ingredients went back to. Alchemy: wholly unmilled bowl, mortar and herb groups come back; everything else put on the table was spent. Smithing: a failed workpiece spends half of each divisible material, rounded down, and a coin decides a single unit; the rest comes back. A full refund requested through craftingRefunding returns all remaining original materials instead.
      */
     refunded: InventoryUnit[];
   }
@@ -2820,7 +2979,7 @@ declare global {
     readonly modelName: string;
 
     /**
-     * Browsing bucket the mesh sits in, e.g. `manmade/structures`.
+     * Browsing bucket the mesh sits in, e.g. `manmade/structures`; `kcdc/<resource>` for a mesh the server streams.
      */
     readonly modelGroup: string;
 
@@ -2847,7 +3006,7 @@ declare global {
 
     /**
      * Spawns and replicates a static mesh from the game's own object catalog.
-     * @param model Mesh to build, as either a full catalog path (`objects/manmade/barrels/barrel_a.cgf`) or its file stem (`barrel_a`). A stem several meshes share resolves to the first of them, so pass the path when it matters which.
+     * @param model Mesh to build, as either a full catalog path (`objects/manmade/barrels/barrel_a.cgf`) or its file stem (`barrel_a`). A stem several meshes share resolves to the first of them, so pass the path when it matters which. A mesh this server streams -- a `.cgf` in a resource's `stream/objects/kcdc/<resource>/` folder -- is named by its full path, `objects/kcdc/<resource>/chair.cgf`; a player whose game does not have it yet sees the prop as soon as it does.
      * @param position Optional world-space spawn position; omitted components default to zero.
      * @param rotation Optional initial orientation: a Quaternion, or a Vector3 of Euler angles in degrees.
      * @param scale Optional uniform scale from 0.01 to 100; omitted spawns the mesh at its own size.
@@ -2910,6 +3069,16 @@ declare global {
      */
     readonly pace: string;
 
+    /**
+     * The names of this cart's seats, the reins first: six on a wagon, three on the two-wheeler.
+     */
+    readonly seats: string[];
+
+    /**
+     * The fastest the driver may take it urged on (the trot key held), in metres a second, 0 to 15; 7 by default. Unurged the team trots at 3.6 or this, whichever is less. A value outside the range is ignored.
+     */
+    maxSpeed: number;
+
     /**
      * Formats this cart handle for logging and debugging.
      * @returns The cart ID, its blueprint, its driver and its pace.
@@ -2924,7 +3093,7 @@ declare global {
     /**
      * Puts a player in a seat. They are taken out of any cart they were in, their own game walks them to the seat and climbs in, and `cartEnter` follows; the driver's client runs the cart from then on. `cartEntering` handlers are asked first.
      * @param player The player to seat.
-     * @param seat `driver` (the bench, holding the reins) or `back` (the right rail): the two seats the game animates a player in.
+     * @param seat One of the cart's `seats`. A wagon has `driver` (the reins, on the bench's left), `bench` (beside them), `rightBack`, `leftBack`, `rightFront` and `leftFront` (on the rails); the two-wheeler `driver`, `rightBack` and `leftBack`.
      * @returns Whether the player was seated: false for a taken seat, a player that is not connected, or a handler's refusal.
      */
     putPlayer(player: Player, seat: string): boolean;
@@ -2938,7 +3107,7 @@ declare global {
 
     /**
      * Who sits in a seat.
-     * @param seat `driver` or `back`.
+     * @param seat One of the cart's `seats`.
      * @returns The player in it, or null when it is empty.
      */
     getOccupant(seat: string): Player | null;
@@ -2946,12 +3115,12 @@ declare global {
     /**
      * Where a player sits in this cart.
      * @param player The player to look for.
-     * @returns `driver` or `back`, or null when they are not in it.
+     * @returns The seat's name, one of `seats`, or null when they are not in it.
      */
     seatOf(player: Player): string | null;
 
     /**
-     * Moves the cart outright, with everyone in it: every client rebuilds it on a new short road at the new pose, and a driver carries on from there.
+     * Moves the cart outright, standing, with everyone in it; a driver carries on from there.
      * @param position Where the cart's front axle stands.
      * @param rotation Which way it faces; omitted keeps its heading.
      * @returns False for a pose that is not finite.
@@ -2959,7 +3128,7 @@ declare global {
     teleport(position: Vector3, rotation?: Vector3 | Quaternion): boolean;
 
     /**
-     * Spawns and replicates a cart or wagon from the game's own prefabs, with its horses already in the shafts. It stands on a short straight road until somebody takes the reins.
+     * Spawns and replicates a cart or wagon from the game's own prefabs, with its horses already in the shafts. It stands where it was put until somebody takes the reins.
      * @param blueprint Which of the game's cart prefabs to build; omitted builds `wagon_b_covered`. `Cart.blueprints()` lists them.
      * @param position Where the cart's front axle stands; omitted components default to zero.
      * @param rotation Which way it faces: a Quaternion, or a Vector3 of Euler angles in degrees.
@@ -3319,22 +3488,22 @@ declare global {
     /**
      * What the object is; a brush when omitted. A brush has no identity of its own, so it is found by its mesh and where the level put it; a level entity by its EntityGuid.
      */
-    kind: 'brush' | 'entity' | undefined;
+    kind?: 'brush' | 'entity' | undefined;
 
     /**
      * A brush's mesh path, `objects/...cgf`, as the World Builder shows it; required for a brush. An entity's name, kept for reading only.
      */
-    name: string | undefined;
+    name?: string | undefined;
 
     /**
      * An entity's level EntityGuid as sixteen hex digits; required for an entity.
      */
-    guid: string | undefined;
+    guid?: string | undefined;
 
     /**
      * An entity's class, kept for reading only.
      */
-    class: string | undefined;
+    class?: string | undefined;
 
     /**
      * Where the level put the object: its pivot, matched within 5 cm. A brush's key, with its mesh.
@@ -3344,22 +3513,22 @@ declare global {
     /**
      * Whether it is taken out of the world: not drawn and not solid.
      */
-    hidden: boolean | undefined;
+    hidden?: boolean | undefined;
 
     /**
      * Where it stands instead; present, the edit is a move.
      */
-    position: Vector3 | number[] | undefined;
+    position?: Vector3 | number[] | undefined;
 
     /**
      * A move's orientation: a Quaternion, {x, y, z, w} or [x, y, z, w]. None when omitted.
      */
-    rotation: Quaternion | number[] | undefined;
+    rotation?: Quaternion | number[] | undefined;
 
     /**
      * A move's scale per axis, from 0.01 to 100. None when omitted.
      */
-    scale: Vector3 | number[] | undefined;
+    scale?: Vector3 | number[] | undefined;
   }
 
   /**
@@ -3557,9 +3726,7 @@ declare global {
     lootable: boolean;
 
     /**
-     * How the simulating client moves this body.
-     * 
-     * `kinematic` (the default) advances the pose and lets every client animate it -- predictable, and the same path every remote player's body already runs on. `native` hands the destination to the game's own movement controller, which walks the body with real footfalls and real turns but will walk into whatever the engine does not route around. Pick `native` for bodies in the open and `kinematic` for anything on an authored route.
+     * How the client simulator moves the body. `native` (default) uses the game's movement controller and walk animations. `kinematic` moves the body directly without walk animation. Neither finds a way around anything: the game's movement controller steers straight at the point it is given. Routes come from server pathfinding, which hands either mode mesh corners -- see `moveTo`.
      */
     locomotion: string;
 
@@ -3569,7 +3736,7 @@ declare global {
     readonly intent: string;
 
     /**
-     * What the simulating client last reported about the current intent: `idle`, `running`, `reached`, `blocked` or `failed`. A dormant NPC that is walking an authored route reports through the server's own dead reckoning instead, so a patrol keeps stepping with nobody there to watch it.
+     * 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.
      */
     readonly status: string;
 
@@ -3653,23 +3820,31 @@ declare global {
     hold(): void;
 
     /**
-     * Sends the NPC somewhere and raises `npcIntentDone` when it arrives, cannot get there, or gives up. Cancels any patrol.
+     * Moves to `position`, cancels any patrol, and emits `npcIntentDone` once when the move ends.
+     * 
+     * The game's own movement steers a body straight at the point it is given and finds no way around anything, so routes come from the server's navigation mesh. The server plans the route and hands the simulating client one corner at a time, the next before the body reaches the last, so it walks through bends without stopping; a dormant NPC is walked along the same route by the server. Routes only use doorways whose door stands open.
+     * 
+     * `auto` (the default) routes on the server whenever a mesh is loaded. Without one, a simulating client steers straight at `position` and a dormant NPC moves in a straight line. `game` steers straight at `position` and waits while dormant; if the body reports `blocked` and a mesh is loaded, the server tries a route before emitting `npcIntentDone`. `server` always routes on the server and throws without a loaded mesh, preserving the previous order.
+     * 
+     * A missing or partial route ends with `blocked`, and a blocked route is not retried. Route plans are queued and spread over ticks; the move reads `running` meanwhile.
      * @param position Where to walk to.
-     * @param options `speed` is the pace to walk at; `radius` is how close counts as arrived, in metres.
-     * @returns True when the order went out.
+     * @param options `speed` defaults to `walk`; `radius` is the arrival distance in metres (default 1.5). `pathfinding` defaults to `auto`.
+     * @returns True when the order went out; false for an invalid NPC or destination.
      */
-    moveTo(position: Vector3 | Partial<Vector3>, options?: { speed?: 'walk' | 'jog' | 'run'; radius?: number }): boolean;
+    moveTo(position: Vector3 | Partial<Vector3>, options?: { speed?: 'walk' | 'jog' | 'run'; radius?: number; pathfinding?: 'auto' | 'game' | 'server' }): boolean;
 
     /**
-     * Walks a route, one waypoint at a time. The route stays on the server and only the waypoint being walked to is ever replicated, so a player who joins mid-patrol sees one move rather than a plan to catch up with -- and a patrol nobody is near enough to simulate keeps advancing on the server's own reckoning.
+     * 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` walks the route forever (the default); `waitSeconds` is how long to stand at each waypoint; `speed` is the pace.
-     * @returns True when the route was accepted; false for an empty route or a point that is not finite.
+     * @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.
+     * @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 }): boolean;
+    patrol(points: (Vector3 | Partial<Vector3>)[], options?: { speed?: 'walk' | 'jog' | 'run'; loop?: boolean; waitSeconds?: number; pathfinding?: 'auto' | 'game' | 'server' }): boolean;
 
     /**
-     * Keeps the NPC near somebody as they move.
+     * 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.
      * @param target Who to follow, as a handle or a network ID.
      * @param options `radius` is how close it tries to stay, in metres; `speed` is the pace.
      * @returns True when the order went out.
@@ -3677,7 +3852,7 @@ declare global {
     follow(target: Player | Npc | number, options?: { speed?: 'walk' | 'jog' | 'run'; radius?: number }): boolean;
 
     /**
-     * Sends the NPC away from a place. The one intent that picks its own direction.
+     * Sends the NPC straight away from a place until the requested distance separates them. If the body reports `blocked`, a loaded mesh lets the server try a route to a point past that distance, on the ground at the NPC's own height, before reporting it.
      * @param from What to run away from.
      * @param options `radius` is how far away is far enough; `speed` is the pace, `run` by default.
      * @returns True when the order went out.
@@ -3706,10 +3881,10 @@ declare global {
      * 
      * `npcAnimationEnd` fires once when the animation this request started is over, and says how.
      * @param fragment A Mannequin fragment, as `Animations.list` names it -- or, as before, a row of the shipped emote catalog, which plays that gesture once and is not remembered.
-     * @param options `tags` pick the variant, `loop` repeats it until stopped, `props` puts up to two models in its hands. `lockMovement` does nothing here: an NPC standing still is its intent's business.
+     * @param options `clip` plays a clip the server streams instead of a fragment (`animations/kcdc/<resource>/wave.caf`, the fragment left `""`), `tags` pick the variant, `loop` repeats it until stopped, `props` puts up to two models in its hands. `lockMovement` does nothing here: an NPC standing still is its intent's business.
      * @returns True when the request went out; false for a dead NPC. Throws for a prop or option it cannot use.
      */
-    playAnimation(fragment: string | number, options?: { tags?: string; loop?: boolean; lockMovement?: boolean; props?: { item?: string; model?: string; hand?: 'right' | 'left'; joint?: string; position?: Vector3 | Partial<Vector3>; rotation?: Quaternion | Vector3 | Partial<Vector3> } | { item?: string; model?: string; hand?: 'right' | 'left'; joint?: string; position?: Vector3 | Partial<Vector3>; rotation?: Quaternion | Vector3 | Partial<Vector3> }[] }): boolean;
+    playAnimation(fragment: string | number, options?: { clip?: string; tags?: string; loop?: boolean; lockMovement?: boolean; props?: { item?: string; model?: string; hand?: 'right' | 'left'; joint?: string; position?: Vector3 | Partial<Vector3>; rotation?: Quaternion | Vector3 | Partial<Vector3> } | { item?: string; model?: string; hand?: 'right' | 'left'; joint?: string; position?: Vector3 | Partial<Vector3>; rotation?: Quaternion | Vector3 | Partial<Vector3> }[] }): boolean;
 
     /**
      * Ends what `playAnimation` started at once, takes its props away and hands the body back to its intent. The stand-up `standUp` asks for is an animation of its own and raises its own `npcAnimationEnd`.
@@ -4016,6 +4191,11 @@ declare global {
      */
     readonly resting: boolean;
 
+    /**
+     * Whether this is a prop people carry in their arms -- one a carry put down, or one spawned `carryable` -- rather than stock. Taking it up is a carry: the game's pick-up prompt or `player.carryItem(groundItem)`, never an inventory.
+     */
+    readonly carryable: boolean;
+
     /**
      * Network ID of the player who dropped this stack, or 0 when the server spawned it.
      */
@@ -4044,10 +4224,10 @@ declare global {
      * @param rotation Optional resting orientation: a Quaternion, or a Vector3 of Euler angles in degrees.
      * @param amount Optional number of units in the stack, from 1 to 10000; omitted lays down one. A stack is picked up whole.
      * @param virtualWorld Optional virtual world the stack belongs to; omitted puts it in the global one.
-     * @param properties Optional condition of the item itself: `quality` as the game grades it, `health` and `condition` from 0 to 1. Each defaults to the class's own. Arrows and other missile classes are held to tighter bounds by the receiving client and are given a quality of 1 and full health when these are left out, since a stack outside those bounds is one no client would build.
+     * @param properties Optional condition of the item itself: `quality` as the game grades it, `health` and `condition` from 0 to 1. Each defaults to the class's own. Arrows and other missile classes are held to tighter bounds by the receiving client and are given a quality of 1 and full health when these are left out, since a stack outside those bounds is one no client would build. `carryable` makes it a prop people carry in their arms rather than stock: the game's pick-up prompt over it starts a carry (raising `playerCarryingItem`) and never puts it in an inventory. Only for a single item `player.carryItem` takes by name.
      * @returns The newly spawned ground item handle. Throws when the item is not a class in the game's tables, or when no client could build the stack as described.
      */
-    static spawn(item: string, position?: Vector3 | Partial<Vector3>, rotation?: Vector3 | Quaternion, amount?: number, virtualWorld?: number, properties?: { quality?: number; health?: number; condition?: number }): GroundItem;
+    static spawn(item: string, position?: Vector3 | Partial<Vector3>, rotation?: Vector3 | Quaternion, amount?: number, virtualWorld?: number, properties?: { quality?: number; health?: number; condition?: number; carryable?: boolean }): GroundItem;
 
     /**
      * Lists every stack lying in the world, however it got there.
@@ -4467,6 +4647,162 @@ declare global {
 
   interface Gate extends Entity {}
 
+  /** */
+  interface SiegeResult {
+    /**
+     * Whether the engine did it.
+     */
+    accepted: boolean;
+
+    /**
+     * Why it did not, as a phrase that reads after the engine's name: `is not loaded`, `cannot fire: the target is further than the engine can throw`. Empty when it did.
+     */
+    reason: string;
+
+    /**
+     * How long until the step it started is over: the whole load for `load`, until the projectile is let go for `fire`. 0 when nothing happened.
+     */
+    seconds: number;
+  }
+
+  /**
+   * Replicated handle for a trebuchet or a cannon.
+   */
+  class SiegeEngine {
+    /**
+     * Creates a script wrapper for an existing siege engine with this ID; use SiegeEngine.spawn() to build one.
+     * @param id Network entity identifier.
+     */
+    constructor(id: number);
+
+    /**
+     * What the engine is: `trebuchet` or `cannon`. The game ships no catapult and no ballista.
+     */
+    readonly kind: string;
+
+    /**
+     * Where the engine is in its cycle: `idle` (unloaded), `drawing` (a trebuchet's arm being winched down), `loading` (the crew laying the projectile), `ready` or `firing`. Named `cycle` because every entity already has a `state`, which is its state bag.
+     */
+    readonly cycle: string;
+
+    /**
+     * Whether the engine is ready to fire.
+     */
+    readonly loaded: boolean;
+
+    /**
+     * How fast the cycle runs, from 0.1 to 20; 1 is the game's own pace, which takes a trebuchet's crew nearly two minutes to load and lets the stone go 3.5 seconds into the shot. Changing it mid-step carries on from where the engine has got to.
+     */
+    speed: number;
+
+    /**
+     * Health taken from anything at the point of impact; a player has 100. A quarter of it reaches the edge of `damageRadius`. 0 leaves hits to `siegeImpact`.
+     */
+    damage: number;
+
+    /**
+     * How far from the point of impact anything is hurt, in metres, up to 100.
+     */
+    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.
+     */
+    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.
+     */
+    range: number;
+
+    /**
+     * The closest the engine can be aimed, in metres along the ground.
+     */
+    readonly minRange: number;
+
+    /**
+     * The furthest the engine can be aimed, in metres along the ground.
+     */
+    readonly maxRange: number;
+
+    /**
+     * How long `load` takes at the engine's speed, in seconds.
+     */
+    readonly loadDuration: number;
+
+    /**
+     * Formats this engine handle for logging and debugging.
+     * @returns The engine ID, its kind and where it is in its cycle.
+     */
+    toString(): string;
+
+    /**
+     * Starts the reload cycle of an idle engine. `siegeEngineReady` fires when it can shoot.
+     * @returns What happened, and the phrase to explain it with when nothing did.
+     */
+    load(): SiegeResult;
+
+    /**
+     * Turns a loaded engine to face the target and shoots at it. A trebuchet's arm lets the stone go at one angle, so its speed is solved for the distance; a cannon fires at one speed, so its elevation is. The stone is let go partway through the shot (`seconds`), then every client nearby draws it along the same arc. It comes down where the world stops it, which the player nearest the target is asked to report, or on the target when nobody can.
+     * @param target Where the projectile should come down.
+     * @param attacker The player credited with whatever it hits, in `playerDamage`, `npcDamage` and `siegeImpact`.
+     * @returns What happened, and the phrase to explain it with when nothing did.
+     */
+    fire(target: Vector3 | Partial<Vector3>, attacker?: Player | number | null): SiegeResult;
+
+    /**
+     * Turns the engine to face a point without shooting. `fire` turns it anyway; this is for showing where it will shoot.
+     * @param target The point to turn towards.
+     * @returns What happened, and the phrase to explain it with when nothing did.
+     */
+    aim(target: Vector3 | Partial<Vector3>): SiegeResult;
+
+    /**
+     * Whether the engine can reach a point from where it stands.
+     * @param target The point to test.
+     * @returns Empty when it can; otherwise why not, as a phrase.
+     */
+    canHit(target: Vector3 | Partial<Vector3>): string;
+
+    /**
+     * Removes the engine on every client after emitting `siegeEngineDestroy`. A projectile already in the air still lands.
+     */
+    destroy(): void;
+
+    /**
+     * Builds and replicates a siege engine, unloaded. The trebuchet is the game's own model and plays its own winch, load and fire animations; the cannon is the game's static gun.
+     * @param kind `trebuchet` or `cannon`.
+     * @param position World-space position of the engine's base.
+     * @param rotation Optional initial orientation: a Quaternion, or a Vector3 of Euler angles in degrees. `fire` and `aim` turn it to face their target.
+     * @param virtualWorld Optional virtual world the engine belongs to; omitted puts it in the global one.
+     * @returns The new engine's handle.
+     */
+    static spawn(kind: string, position: Vector3 | Partial<Vector3>, rotation?: Vector3 | Quaternion, virtualWorld?: number): SiegeEngine;
+
+    /**
+     * Lists the siege engines the server has.
+     * @param virtualWorld Optional virtual world to list; omitted lists every one.
+     * @returns One handle per engine, in no particular order.
+     */
+    static all(virtualWorld?: number): SiegeEngine[];
+
+    /**
+     * Looks an engine up by its network entity ID.
+     * @param id Network entity identifier.
+     * @returns The engine's handle, or null when no live engine has that ID.
+     */
+    static getById(id: number): SiegeEngine | null;
+
+    /**
+     * Removes siege engines, emitting `siegeEngineDestroy` 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 SiegeEngine extends Entity {}
+
   /** */
   interface AreaDefinition {
     /**
@@ -4477,7 +4813,7 @@ declare global {
     /**
      * A readable name; the id when omitted.
      */
-    name: string | undefined;
+    name?: string | undefined;
 
     /**
      * CryEngine's own area shapes: `AreaBox`, `AreaShape` (a closed polygon with a height) and `AreaSphere`.
@@ -4487,57 +4823,57 @@ declare global {
     /**
      * Where the shape is placed from; the origin when omitted.
      */
-    position: Vector3 | undefined;
+    position?: Vector3 | undefined;
 
     /**
      * The shape's orientation: a Quaternion or {x, y, z, w}, or Euler angles in degrees.
      */
-    rotation: Quaternion | Vector3 | undefined;
+    rotation?: Quaternion | Vector3 | undefined;
 
     /**
      * box: the corner nearest negative infinity, relative to `position` before rotation.
      */
-    min: Vector3 | undefined;
+    min?: Vector3 | undefined;
 
     /**
      * box: the opposite corner. Every component must be above `min`'s.
      */
-    max: Vector3 | undefined;
+    max?: Vector3 | undefined;
 
     /**
      * shape: 3 to 256 corners relative to `position` before rotation, closed back to the first. As in the engine, the floor is the lowest corner.
      */
-    points: Vector3[] | undefined;
+    points?: Vector3[] | undefined;
 
     /**
      * shape: how far above its lowest corner the area reaches; 0, the default, for no ceiling.
      */
-    height: number | undefined;
+    height?: number | undefined;
 
     /**
      * sphere: its radius around `position`.
      */
-    radius: number | undefined;
+    radius?: number | undefined;
 
     /**
      * Free-form labels, found again with `Area.withLabel`.
      */
-    labels: string[] | undefined;
+    labels?: string[] | undefined;
 
     /**
      * Anything JSON can hold, kept on the area for scripts.
      */
-    metadata: Record<string, unknown> | undefined;
+    metadata?: Record<string, unknown> | undefined;
 
     /**
      * The one virtual world it belongs to; every world when omitted.
      */
-    virtualWorld: number | undefined;
+    virtualWorld?: number | undefined;
 
     /**
      * Whether it starts enabled; true when omitted.
      */
-    enabled: boolean | undefined;
+    enabled?: boolean | undefined;
   }
 
   /** */
@@ -4756,32 +5092,32 @@ declare global {
   }
 
   /**
-   * Replicated container handle: one a script spawned, or one the level places.
+   * Container handle for a spawned chest, a level chest, or virtual stock without a world entity.
    */
   class Stash {
     /**
-     * Creates a script wrapper for an existing container with this ID; use Stash.spawn() to spawn one, or Stash.find() for one the level places.
+     * Creates a script wrapper for an existing container with this ID; use Stash.spawn() for a chest, Stash.createVirtual() for stock without a chest, or Stash.find() for one the level places.
      * @param id Network entity identifier.
      */
     constructor(id: number);
 
     /**
-     * The identity every client turns into the same native container, for one a script spawned. Minted by the server from 1, and not `id`, which is the replication entity's. 0 for a container the level places.
+     * The server-minted identity of a scripted chest or virtual stash, from 1. Distinct from the network entity id. Virtual stashes use it for an inventory GUID without creating a chest. 0 for a level chest.
      */
     readonly stashId: number;
 
     /**
-     * The EntityGuid every client finds this container under, as sixteen lowercase hex digits: the level's own for a container the level places, the one minted when a script spawned it otherwise. Every container has one, and `Stash.find` takes it back.
+     * The EntityGuid every client finds this container under, as sixteen lowercase hex digits: the level's own for a container the level places, the one minted when a script spawned it otherwise. Empty for virtual stock; `Stash.find` takes physical container GUIDs back.
      */
     readonly guid: string;
 
     /**
-     * The level's own EntityGuid for a container the level places, as sixteen lowercase hex digits; empty for one a script spawned. The same on every machine, so it is the identity to store a container under; `Stash.find` takes it back.
+     * The level's own EntityGuid for a container the level places, as sixteen lowercase hex digits; empty for a scripted chest or virtual stock. The same on every machine, so it is the identity to store a container under; `Stash.find` takes it back.
      */
     readonly levelGuid: string;
 
     /**
-     * The entity name the level gives the container, or `spawned_stash_<stashId>` for one a script spawned.
+     * The entity name the level gives the container, or `spawned_stash_<stashId>` for a scripted chest; empty for virtual stock.
      */
     readonly name: string;
 
@@ -4791,10 +5127,15 @@ declare global {
     readonly itemCount: number;
 
     /**
-     * Whether a player has it open. Every client animates the lid by it.
+     * Whether a player holds its view. Physical chests animate their lid by it; virtual stashes have no lid.
      */
     readonly isOpen: boolean;
 
+    /**
+     * Whether this stash has stock without a chest entity. Open it with open(player); its position and rotation do not govern access, and guid is empty.
+     */
+    readonly isVirtual: boolean;
+
     /**
      * The network ID of the player who has its contents open, or 0. While it is held, every other player's open is refused before their transfer screen appears.
      */
@@ -4837,10 +5178,16 @@ declare global {
     toString(): string;
 
     /**
-     * Despawns this container on every client and forgets what was in it. Anything inside goes with it. Does nothing to a container the level places.
+     * Destroys this scripted chest or virtual stash and forgets what was in it. Anything inside goes with it. Does nothing to a container the level places.
      */
     destroy(): void;
 
+    /**
+     * Opens a virtual stash from anywhere in its virtual world. Calls stashInteract before granting exclusive access. Returns false for a physical stash, a locked or busy stash, an unavailable player, or a script refusal. A true result requests the screen; the client releases access if it cannot open.
+     * @param player Player whose native transfer screen should open.
+     */
+    open(player: Player): boolean;
+
     /**
      * Reads what the container holds. A linked child reads its master's.
      * @returns A copy of its rows, or null once the container is gone.
@@ -4862,6 +5209,12 @@ declare global {
      */
     setInventory(request: { items: { id?: string; item: string; amount: number; metadata?: Record<string, unknown> }[]; revision?: number }): InventoryResult;
 
+    /**
+     * Creates empty server-owned stock without spawning a chest on any client. Supports the same inventory methods and events as physical stashes. Use open(player) to show the native transfer screen, and destroy() to discard it. Contents last until destroyed or the server restarts.
+     * @param virtualWorld World whose players may open it, as a uint32 number; defaults to the global world. Invalid values throw before creating stock.
+     */
+    static createVirtual(virtualWorld?: number): Stash;
+
     /**
      * Spawns and replicates an empty container. Fill it with `addItem` or `setInventory`, or let players put things in it.
      * @param position Optional world-space spawn position; omitted components default to zero.
@@ -4872,7 +5225,7 @@ declare global {
     static spawn(position?: Vector3 | Partial<Vector3>, rotation?: Vector3 | Quaternion, virtualWorld?: number): Stash;
 
     /**
-     * Lists every container the server currently has: every one the level places, which exist from boot in the global world, and every one a script spawned. In another virtual world a level container is built the first time anything there reaches it, so this lists only those.
+     * Lists every container the server currently has: every one the level places, which exist from boot in the global world, and every scripted chest or virtual stash. In another virtual world a level container is built the first time anything there reaches it, so this lists only those.
      * @returns One handle per live container, in no particular order.
      */
     static all(): Stash[];
@@ -4893,7 +5246,7 @@ declare global {
     static find(guid: string, virtualWorld?: number): Stash | null;
 
     /**
-     * Finds the container nearest a point, level or spawned. The server knows where every container the level places stands, so this answers at once, without asking a client.
+     * Finds the physical container nearest a point, level or spawned. Virtual stock is excluded. The server knows where every container the level places stands, so this answers at once, without asking a client.
      * @param position The point to measure from, usually a player's position.
      * @param maxDistance How far to look, in metres; omitted looks 5 m, about the reach the game gives a chest.
      * @param virtualWorld Optional virtual world to look in; omitted looks in the global one.
@@ -4902,7 +5255,7 @@ declare global {
     static nearest(position: Vector3 | Partial<Vector3>, maxDistance?: number, virtualWorld?: number): Stash | null;
 
     /**
-     * Despawns containers a script spawned, and everything in them with them. The level's own stay.
+     * Destroys scripted chests and virtual stashes, including everything inside. The level's own stay.
      * @param virtualWorld Optional virtual world to clear; omitted clears every one of them.
      * @returns How many containers were removed.
      */
@@ -5108,15 +5461,35 @@ declare global {
     distance: number;
 
     /**
-     * The surface type's own name, spelled the way the game's tables spell it -- `mat_wood`, `mat_stone`, `mat_water`. This is what a trace is worth over a position: it says what was hit, not just where. Empty only before the material tables are up.
+     * The surface type's own name, spelled the way the game's tables spell it in `Libs/MaterialEffects/SurfaceTypes.xml` -- `mat_wood`, `mat_rock`, `mat_soil`, `mat_water`. It says what the thing is made of, which is how footsteps and blows sound, not what it is: a plank wall is `mat_wood` as much as a trunk is, so tell a tree by `category`. Among the 74 the game defines: `mat_wood`, `mat_wood_soft`, `mat_vegetation`, `mat_bushes`, `mat_rock`, `mat_rock_unwalk`, `mat_rock_horse_ignore`, `mat_stairs_stone`, `mat_gravel`, `mat_soil`, `mat_mud`, `mat_grass`, `mat_road`, `mat_metal`, `mat_glass`, `mat_plaster`, `mat_thatch`, `mat_fabric`, `mat_flesh`. Empty only before the material tables are up.
      */
     surface: string;
 
     /**
-     * Whether the ground itself was hit rather than anything placed on it. Nothing lies behind the terrain, so a trace stops there.
+     * Whether the ground itself was hit rather than anything placed on it. Nothing lies behind the terrain, so a trace stops there. The same as `kind` being `terrain`.
      */
     terrain: boolean;
 
+    /**
+     * What sort of thing the ray stopped on. `entity` is anything with an `entityClass` -- doors, props, NPCs, players. `vegetation` is an instance the level paints on: trees, bushes, plants, and boulders painted the same way. `brush` is a static mesh placed one by one: walls, houses, rocks and cliffs. `static` is static geometry that is neither, or whose source the engine does not record. Trees and rocks are not entities, so for them this, `model` and `category` are what say what was hit.
+     */
+    kind: "terrain" | "entity" | "vegetation" | "brush" | "static";
+
+    /**
+     * The mesh of a vegetation instance or a brush, as the path the game loads it from -- `objects/natural/vegetation/trees/normal_trees/quercus_robur/quercus_robur_big_a.cgf`. Null for terrain, entities and `static`. A tree or a rock has no GUID, but its `model` and `position` together are the same on every client on the same level, which is what a server keeps a felled tree or a mined rock by.
+     */
+    model: string | null;
+
+    /**
+     * Which of the game's own folders of natural objects `model` comes from: `tree` for `objects/natural/vegetation/trees` -- living, dead, fallen and stumps alike, which `model` tells apart -- `bush` for its bushes, `plant` for the rest of its vegetation (grass, ferns, mushrooms, branches), and `rock` for `objects/natural/rocks` and `objects/natural/stones`. Null for anything else, man-made included.
+     */
+    category: "tree" | "bush" | "plant" | "rock" | null;
+
+    /**
+     * The material drawn where the ray met it, as the path the material manager keys it by, the sub-material when the mesh has several -- a trunk's bark rather than the tree's whole material. Null for terrain and when nothing names one.
+     */
+    material: string | null;
+
     /**
      * The level's own identity for what was hit, as sixteen lowercase hex digits -- the same on every machine, and what `Door.find` and the other GUID lookups take. Null for terrain, for static geometry and for anything the session spawned, none of which the level names.
      */
@@ -5213,6 +5586,129 @@ declare global {
     entities: WorldNearbyEntity[];
   }
 
+  /**
+   * A walk across the mesh.
+   */
+  interface NavigationPath {
+    /**
+     * The corners to walk through, first the point on the mesh nearest `from`. Straight lines between them stay on the mesh.
+     */
+    points: Vector3[];
+
+    /**
+     * Whether it reaches `to`. False when `to` cannot be reached, and the path then ends at the nearest point the mesh allows.
+     */
+    complete: boolean;
+
+    /**
+     * Its length in metres.
+     */
+    length: number;
+  }
+
+  /**
+   * How far a straight walk across the mesh gets.
+   */
+  interface NavigationRay {
+    /**
+     * Whether the edge of the mesh -- a wall, a drop, a locked door -- stops it before `to`.
+     */
+    hit: boolean;
+
+    /**
+     * Where it stops: the edge, or the point on the mesh under `to`.
+     */
+    point: Vector3;
+  }
+
+  /**
+   * 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.
+   */
+  const Navigation: {
+    /**
+     * Whether a mesh loaded from `mod.navmesh` or the server's `files/` directory. False when no usable copy is found; the server log gives the reason.
+     */
+    readonly ready: boolean;
+
+    /**
+     * Available overlay names, sorted. Overlays contain replacement navigation data for quest states. Enabling one replaces the covered part of the mesh. Empty without a mesh.
+     */
+    readonly overlays: string[];
+
+    /**
+     * Enabled overlays in activation order. Initially empty; the level starts with its base mesh.
+     */
+    readonly activeOverlays: string[];
+
+    /**
+     * Snaps a point to the nearest walkable surface.
+     * @param point The point to snap; omitted components default to zero.
+     * @param options How far to look, and which doors count.
+     * @returns The nearest point within the search limits, or null when none is found or no mesh is loaded.
+     */
+    closestPoint(point: Vector3 | Partial<Vector3>, options?: { searchRadius?: number; searchHeight?: number; doors?: "unlocked" | "open" | "any" | "none" }): Vector3 | null;
+
+    /**
+     * Returns the height of the nearest walkable surface, including upper floors, bridges and stairs.
+     * @param point The point to measure; omitted components default to zero. Its z estimates the floor height and selects the storey.
+     * @param options How far to look.
+     * @returns The height in metres, or null when none is found or no mesh is loaded.
+     */
+    floorAt(point: Vector3 | Partial<Vector3>, options?: { searchRadius?: number; searchHeight?: number; doors?: "unlocked" | "open" | "any" | "none" }): number | null;
+
+    /**
+     * Plans a path around obstacles on the mesh. Plan when a destination changes; avoid recalculating every NPC's path each tick.
+     * @param from Where the walk starts; omitted components default to zero.
+     * @param to Where it should end; omitted components default to zero.
+     * @param options How far to look for each end, and which doors to walk through.
+     * @returns The path, or null when an endpoint cannot be found, the query fails or no mesh is loaded. A partial path has `complete: false`.
+     */
+    findPath(from: Vector3 | Partial<Vector3>, to: Vector3 | Partial<Vector3>, options?: { searchRadius?: number; searchHeight?: number; doors?: "unlocked" | "open" | "any" | "none" }): NavigationPath | null;
+
+    /**
+     * Checks reachability by calling `findPath`.
+     * @param from Where the walk starts; omitted components default to zero.
+     * @param to Where it should end; omitted components default to zero.
+     * @param options How far to look for each end, and which doors to walk through.
+     * @returns True when a complete path exists; false otherwise, including when no mesh is loaded.
+     */
+    canReach(from: Vector3 | Partial<Vector3>, to: Vector3 | Partial<Vector3>, options?: { searchRadius?: number; searchHeight?: number; doors?: "unlocked" | "open" | "any" | "none" }): boolean;
+
+    /**
+     * Checks a straight line across the mesh and reports where it stops.
+     * @param from Where the walk starts; omitted components default to zero.
+     * @param to Where it heads; only its x and y are used, the walk follows the surface.
+     * @param options How far to look for `from`, and which doors let the walk through.
+     * @returns The result, or null when `from` is off the mesh, the query fails or no mesh is loaded.
+     */
+    raycast(from: Vector3 | Partial<Vector3>, to: Vector3 | Partial<Vector3>, options?: { searchRadius?: number; searchHeight?: number; doors?: "unlocked" | "open" | "any" | "none" }): NavigationRay | null;
+
+    /**
+     * Returns a random walkable point reachable from `center` and no further from it across the ground than `radius`. A point drawn outside the circle is drawn again, a bounded number of times. Without a centre, samples the whole level, choosing each tile with equal probability.
+     * @param center The point to scatter around; it has to be on the mesh, and omitted components default to zero. Omitted entirely, the point can be anywhere on the level's mesh; pass `undefined` for it and for `radius` to give options.
+     * @param radius How far from `center`, in metres, up to 512. Required with a centre.
+     * @param options How far to look for `center`, and which doors the point may lie behind.
+     * @returns The point, or null when `center` is off the mesh, no draw lands within `radius`, the query fails or no mesh is loaded.
+     */
+    randomPoint(center?: Vector3 | Partial<Vector3>, radius?: number, options?: { searchRadius?: number; searchHeight?: number; doors?: "unlocked" | "open" | "any" | "none" }): Vector3 | null;
+
+    /**
+     * Enables an overlay. Where overlays overlap, the last enabled takes precedence. Subsequent queries use the updated mesh.
+     * @param name An entry of `overlays`.
+     * @returns False for a name the level does not ship, one already enabled, one whose tiles cannot be read or loaded (the server log says why), or without a mesh.
+     */
+    enableOverlay(name: string): boolean;
+
+    /**
+     * Disables an overlay, restoring the previous enabled overlay or the base mesh in that area.
+     * @param name An entry of `activeOverlays`.
+     * @returns False for a name that is not enabled, or when part of the area could not be restored (the server log says why); the overlay is disabled either way.
+     */
+    disableOverlay(name: string): boolean;
+  };
+
   /**
    * What the game's own tables say about one status effect.
    */