@kingdomsconnected/types 1.5.7 → 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.
      */
@@ -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.
@@ -3329,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.
@@ -3354,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;
   }
 
   /**
@@ -3722,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`.
@@ -4032,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.
      */
@@ -4060,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.
@@ -4483,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 {
     /**
@@ -4493,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`.
@@ -4503,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;
   }
 
   /** */
@@ -4772,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;
 
@@ -4807,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.
      */
@@ -4853,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.
@@ -4878,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.
@@ -4888,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[];
@@ -4909,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.
@@ -4918,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.
      */
@@ -5124,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.
      */