@kingdomsconnected/types 1.5.7 → 1.6.1

package/generated/server-api.d.ts

@@ -23,7 +23,7 @@ declare global {
     playerDied: [player: Player, killer: Player | null, reason: "unknown" | "combat" | "gunshot" | "starvation" | "collision" | "scripted" | "disintegrate" | "fall" | "poison" | "bleeding" | "selfHarm"];
 
     /**
-     * Dispatched when something takes health off a player: a weapon, an arrow, a fall, a collision, a scripted hit. The hit player's own client reports it, because only it resolved the blow against its armour and its skills, so `amount` is what was really taken. It arrives ahead of the `playerDied` a killing blow causes.
+     * Dispatched when something takes health off a player: a weapon, an arrow, a fall, a collision, a scripted hit. Another player's blow is raised by the server as it rules on it, after `playerHit` had its say, so `amount` is what the ruling takes; anything else is reported by the hit player's own client, which resolved it against its armour and its skills. It arrives ahead of the `playerDied` a killing blow causes.
      * 
      * `attacker` is the player who dealt it, or null. `bodyPart` is where it landed, or null for damage that lands nowhere in particular. The weapon is the attacker's own `rightHandItem` or `leftHandItem`.
      * 
@@ -31,6 +31,23 @@ declare global {
      */
     playerDamage: [player: Player, attacker: Player | null, amount: number, bodyPart: "head" | "torso" | "leftArm" | "rightArm" | "leftLeg" | "rightLeg" | null, reason: "unknown" | "combat" | "gunshot" | "starvation" | "collision" | "scripted" | "disintegrate" | "fall" | "poison" | "bleeding" | "selfHarm"];
 
+    /**
+     * A melee swing aimed at another player was admitted by the server, including a miss. Raised once per attack generation, after presentation admission. Use it to track combat inactivity in your resource.
+     */
+    playerAttack: [player: Player, opponent: Player];
+
+    /**
+     * A resource called cancelCombat for this pair. Raised after the cancellation was sent to both players and their observers.
+     */
+    playerCombatCancelled: [first: Player, second: Player];
+
+    /**
+     * Dispatched when another player's blade or arrow lands on a player, before anything is taken -- the place for teams, safe zones, friendly fire and damage rules. The game resolved the blow against the guard the victim really held -- whether it was blocked, perfectly or not, and where it landed -- and the server works out what a swing takes from there; it has checked that the swing was one it relayed and could still land, or that the arrow was one whose impact it accepted, and that the two stood within reach. Only what is ruled here comes off the victim's health, on every client at once.
+     * 
+     * Return `false` from a handler to refuse the blow: no health is taken and no `playerDamage` follows. Scale `hit.modifiers` to change how a swing is worked out -- a stronger attack, weaker armour -- or set `hit.damage` to say outright what it takes: `0` for a blow that lands harmlessly, more for a heavier one. Either way the blow is still seen and heard: the blades met. Handlers run synchronously, so the decision cannot wait on anything awaited.
+     */
+    playerHit: [player: Player, attacker: Player, hit: PlayerHit];
+
     /**
      * Dispatched when a limb becomes injured -- usually a blow landing there, sometimes a fall on both legs. `player.injuries` already says so. A limb hit again while injured stays injured and raises nothing new.
      */
@@ -74,6 +91,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 +236,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 +433,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 reporting player -- the attacker when near enough, else whoever is 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 +474,17 @@ 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()`.
+     * Raised once after every configured world export has loaded successfully, including an empty list. WorldResource.ready is true inside the handler. A script starting later must check WorldResource.ready first; the event is not replayed. Do not await this event inside resourceStart: exports load after script startup. Handler promises are not awaited.
+     */
+    worldResourcesReady: [];
+
+    /**
+     * 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 +504,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"];
 
@@ -906,6 +978,136 @@ declare global {
     walkEnforced: boolean;
   }
 
+  /**
+   * One number per damage type a blow is worked out in. A blade's stab, slash and smash are priced separately and added; a blow runs only the passes its attack and weapon call for.
+   */
+  interface DamagePasses {
+    /**
+     * The stab pass.
+     */
+    stab: number;
+
+    /**
+     * The slash pass.
+     */
+    slash: number;
+
+    /**
+     * The smash pass.
+     */
+    smash: number;
+  }
+
+  /**
+   * Scales a `playerHit` handler puts on the server's price of a melee blow, each 1 until a handler changes it. The server works the blow out again with them, step by step as the game does: a heavier attack has to get through the same armour and the same block, so doubling `attack` does not simply double the damage. Never negative.
+   */
+  interface PlayerHitModifiers {
+    /**
+     * Scales the attacker's attack in every pass, after their weapon, strength, skill and the swing itself.
+     */
+    attack: number;
+
+    /**
+     * Scales the victim's armour where the blow landed.
+     */
+    defense: number;
+
+    /**
+     * Scales what the victim's block put up. Nothing for a blow that was not blocked.
+     */
+    block: number;
+
+    /**
+     * Scales the health the blow takes, once everything else is worked out. The game's own cap of 200 a blow is applied before it, so this can go past it.
+     */
+    health: number;
+  }
+
+  /**
+   * Another player's blow, as `playerHit` shows it before the referee rules. `damage` is what the blow will take and `modifiers` scale how the server works it out; a handler may change either. Every other field describes what happened and is read-only in effect.
+   */
+  interface PlayerHit {
+    /**
+     * Health the blow takes. For a swing the server works it out itself, the way the game does, from the attacker's weapon and its wear, both players' strength and skills, the armour the victim wears where it landed, the block and the perks and buffs it can vouch for; for an arrow it is what the victim's own game worked out. Set it and it stands as set: `modifiers` are then ignored. Never negative.
+     */
+    damage: number;
+
+    /**
+     * Health the game itself took for the blow on the machine that saw it land. Matches `damage` unless a perk that depends on the moment -- a heavy weapon's, a first strike's -- was in play, which the server leaves out.
+     */
+    engineDamage: number;
+
+    /**
+     * Whether the server worked `damage` out itself: true for a swing, false for an arrow.
+     */
+    priced: boolean;
+
+    /**
+     * The attacker's weapon as 32 hex digits, or null for a bare hand.
+     */
+    weapon: string | null;
+
+    /**
+     * The attacker's attack in each pass, after the swing's own strength and before `modifiers`.
+     */
+    attack: DamagePasses;
+
+    /**
+     * The victim's armour in each pass where the blow landed, before `modifiers`.
+     */
+    armor: DamagePasses;
+
+    /**
+     * What the victim's block put up, or 0 when nothing blocked it.
+     */
+    blockDefense: number;
+
+    /**
+     * How much the place it landed multiplies the damage by: 1.5 for the head, 1 for the torso, 0.7 for a limb.
+     */
+    bodyPartCoefficient: number;
+
+    /**
+     * Scales on the server's price; see `PlayerHitModifiers`. Ignored for an arrow.
+     */
+    modifiers: PlayerHitModifiers;
+
+    /**
+     * Stamina the blow cost the victim. Already spent: stamina decides their next block, which cannot wait for a ruling.
+     */
+    stamina: number;
+
+    /**
+     * The limb it landed on, or null for none in particular.
+     */
+    bodyPart: "head" | "torso" | "leftArm" | "rightArm" | "leftLeg" | "rightLeg" | null;
+
+    /**
+     * The game's own reason for the damage: `combat` for a blade or a bow.
+     */
+    reason: "unknown" | "combat" | "gunshot" | "starvation" | "collision" | "scripted" | "disintegrate" | "fall" | "poison" | "bleeding" | "selfHarm";
+
+    /**
+     * Whether it was a swing or an arrow.
+     */
+    source: "melee" | "missile";
+
+    /**
+     * The victim's block caught it.
+     */
+    blocked: boolean;
+
+    /**
+     * The victim's perfect block caught it. The game takes nothing for one.
+     */
+    perfectBlock: boolean;
+
+    /**
+     * The victim's block gave way under it.
+     */
+    blockBroken: boolean;
+  }
+
   /**
    * Which of a player's limbs carry an injury, one flag per limb. An injury is the game's own: it lowers the stamina ceiling (`healthyStamina`), can bleed, and heals slowly by itself or at once with a bandage or `player.heal`.
    */
@@ -1198,6 +1400,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.
      */
@@ -1301,6 +1508,13 @@ declare global {
      */
     revive(): boolean;
 
+    /**
+     * Ends melee combat between these two players and retires their pending blows against each other. Other opponents are left alone. A later attack can start combat again. Consent and timeout rules belong to your resource.
+     * @param opponent The other player. Both sides are cancelled.
+     * @returns True when sent; false for disconnected players, the same player, or different virtual worlds.
+     */
+    cancelCombat(opponent: Player): boolean;
+
     /**
      * Puts this player somewhere, as a spawn rather than as a teleport: their client holds the body still until there is real ground under it, so it cannot fall through a world that has not streamed in yet.
      * 
@@ -1330,10 +1544,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.
@@ -1379,6 +1593,13 @@ declare global {
      */
     setAppearance(appearance: Partial<Appearance>): boolean;
 
+    /**
+     * Grants or revokes World Builder access for this player. Multiplayer connections start without access. Enabling allows F7 and the client MapEditor.open API; disabling also closes an open editor. The permission lasts until changed or disconnected and does not affect other players. Offline editing is always allowed.
+     * @param enabled Whether this player may open World Builder.
+     * @returns True when the permission was sent; false for a player with no connection. Throws unless enabled is a boolean.
+     */
+    setWorldBuilderEnabled(enabled: boolean): boolean;
+
     /**
      * Puts a pace rule on this player. `walkByDefault` makes walking the pace they keep coming back to and leaves their own key working; `walkEnforced` forbids running and sprinting outright, and their key stops mattering.
      * 
@@ -1393,7 +1614,7 @@ declare global {
     setMovementMode(mode: Partial<MovementMode>): boolean;
 
     /**
-     * Grants items into this player's inventory, which the server holds; their game shows them on the next tick. `Inventory.add` does the same and can also set the items' properties.
+     * Grants items into this player's inventory, which the server holds; their game shows them on the next tick and announces them with its own "You received" toast. `Inventory.add` does the same, can set the items' properties, and can leave out the toast.
      * @param item Item class GUID, or the exact name the game's own item tables use.
      * @param amount How many to grant; defaults to 1, and at most 10000.
      * @returns True when the items were added; false for an unknown item, an amount outside 1..10000, or a player with no inventory.
@@ -1401,7 +1622,7 @@ declare global {
     giveItem(item: string, amount?: number): boolean;
 
     /**
-     * Takes items of a class out of this player's inventory, across its rows, all of them or none. The server holds the inventory, so the promise is already settled when it is returned; it stays a promise so existing scripts keep working. To move items between players use `Inventory.transfer`, which cannot lose them half way.
+     * Takes items of a class out of this player's inventory, across its rows, all of them or none. The server holds the inventory, so the promise is already settled when it is returned; it stays a promise so existing scripts keep working. Their game announces the loss with its own toast; `Inventory.remove` can leave it out. To move items between players use `Inventory.transfer`, which cannot lose them half way.
      * @param item Item class GUID, or the exact name the game's own item tables use. The same spelling `giveItem` takes.
      * @param amount How many units to take; defaults to 1, and at most 10000. Zero is refused rather than read as "all of them".
      * @returns An object carrying `removed` (the amount when it happened, otherwise 0), `requested`, `ok`, and `reason` (empty on success, otherwise the inventory code, such as `insufficientItems`).
@@ -1468,7 +1689,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 +1706,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.
@@ -1603,7 +1842,7 @@ declare global {
     revision: number;
 
     /**
-     * `add`, `remove`, `properties`, `set`, `transfer`, `wear` when the player's game wore an item down in use, `use` for food, potions and ointments, `shot` for a fired round, `pickpocket`, `trade` for a vendor deal, `drop` for `player.dropInventory`, or the ground, stash and gathering reasons.
+     * `add`, `remove`, `properties`, `set`, `transfer`, `wear` when the player's game wore an item down in use, `use` for food, potions and ointments, `shot` for a fired round, `pickpocket`, `trade` for a vendor deal, `repair` for a repair kit, `drop` for `player.dropInventory`, or the ground, stash and gathering reasons.
      */
     reason: string;
 
@@ -1623,7 +1862,7 @@ declare global {
     ok: boolean;
 
     /**
-     * Empty on success, otherwise why not: `inventoryUnavailable`, `invalidRequest`, `staleRevision`, `invalidItem`, `invalidItems`, `invalidAmount`, `unknownItem`, `insufficientItems`, `inventoryCapacity`, `sameInventory`, or a property policy code (`invalidMetadata`, `unknownItemClass`, `questItem`, `invalidQuality`, `immutableItemHealth`, `invalidItemHealth`, `contradictoryItemHealth`, `invalidCreationSentinel`, `unsupportedPoisonProperties`, `unsupportedOnEquipBuffs`).
+     * Empty on success, otherwise why not: `inventoryUnavailable`, `invalidRequest`, `staleRevision`, `invalidItem`, `invalidItems`, `invalidAmount`, `unknownItem`, `insufficientItems`, `inventoryCapacity`, `sameInventory`, `invalidEquipment`, or a property policy code (`invalidMetadata`, `unknownItemClass`, `questItem`, `invalidQuality`, `immutableItemHealth`, `invalidItemHealth`, `contradictoryItemHealth`, `invalidCreationSentinel`, `unsupportedPoisonProperties`, `unsupportedOnEquipBuffs`).
      */
     code: string;
 
@@ -1649,14 +1888,14 @@ declare global {
     get(player: Player): InventoryState | null;
 
     /**
-     * Gives a player items of a class, 1 to 10000 at a time. `item` is the class GUID or the exact name the game's own item tables use, the same spelling `giveItem` takes. Left-out properties mean quality 1 at full condition; `metadata.quality` asks for a higher tier, up to what the class is made in, and `invalidQuality` refuses one past it. The units join the row that already holds this class with these properties, if there is one.
+     * Gives a player items of a class, 1 to 10000 at a time. `item` is the class GUID or the exact name the game's own item tables use, the same spelling `giveItem` takes. Left-out properties mean quality 1 at full condition; `metadata.quality` asks for a higher tier, up to what the class is made in, and `invalidQuality` refuses one past it. The units join the row that already holds this class with these properties, if there is one. The player's game announces them with its own "You received" toast unless `notify` is false.
      */
-    add(player: Player, request: { item: string; amount: number; metadata?: Record<string, unknown>; revision?: number }): InventoryResult;
+    add(player: Player, request: { item: string; amount: number; metadata?: Record<string, unknown>; revision?: number; notify?: boolean }): InventoryResult;
 
     /**
-     * Takes exact units from named rows, every one of them or none.
+     * Takes exact units from named rows, every one of them or none. The player's game announces the loss with its own toast unless `notify` is false.
      */
-    remove(player: Player, request: { units: InventoryUnit[]; revision?: number }): InventoryResult;
+    remove(player: Player, request: { units: InventoryUnit[]; revision?: number; notify?: boolean }): InventoryResult;
 
     /**
      * Replaces a row's properties. The row keeps its identity and amount. It replaces rather than merges: carry over anything you want to keep, and give `health` or `condition`, not two that disagree.
@@ -1664,14 +1903,14 @@ declare global {
     setProperties(player: Player, request: { id: string; metadata: Record<string, unknown>; revision?: number }): InventoryResult;
 
     /**
-     * Replaces a player's whole inventory, which is how a saved one comes back. Rows keep the ids they are given (letters, digits and `-_:.`, up to 64) and get new ones when they have none. `equipped` is how many units of a gear row the body wears, up to 48 in all; their game dresses in them. An empty list clears the inventory.
+     * Replaces a player's whole inventory, which is how a saved one comes back. It is never announced in the player's game. Rows keep the ids they are given (letters, digits and `-_:.`, up to 64) and get new ones when they have none. `equipped` is how many units of a gear row the body wears, up to 48 in all; their game dresses in them. An empty list clears the inventory.
      */
     set(player: Player, request: { items: { id?: string; item: string; amount: number; metadata?: Record<string, unknown>; equipped?: number }[]; revision?: number }): InventoryResult;
 
     /**
-     * Moves exact units from one player to another with their properties, all or nothing. They join matching rows in the target, so the target's row ids are the ones in the result's `items`. Whether the two may trade -- distance, consent, price -- is for the script to decide.
+     * Moves exact units from one player to another with their properties, all or nothing. They join matching rows in the target, so the target's row ids are the ones in the result's `items`. Whether the two may trade -- distance, consent, price -- is for the script to decide. Both players' games announce what they lost and gained unless `notify` is false.
      */
-    transfer(source: Player, target: Player, request: { units: InventoryUnit[]; sourceRevision?: number; targetRevision?: number }): InventoryResult;
+    transfer(source: Player, target: Player, request: { units: InventoryUnit[]; sourceRevision?: number; targetRevision?: number; notify?: boolean }): InventoryResult;
 
     /**
      * What the game prices one unit of an item at, in money units, worked out the way the game does it. `pristine` is the price at the best health its quality allows, `current` at its own health. Quality changes the price only through that health. The metadata reads as `Inventory.add` reads it -- left out, quality 1 at full condition -- so `Inventory.getItemPrice(row.item, row.metadata)` prices a row. This is the item's own worth: what the game's shopkeepers would ask depends on their terms and the haggling, and a `Vendor` charges whatever its script says.
@@ -1911,7 +2150,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 +2160,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 +2217,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 +2394,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 +2421,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 +2430,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 +2650,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 +2740,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 +3145,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,15 +3172,15 @@ 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.
+     * @param scale Uniform size or separate X/Y/Z sizes, each from 0.01 to 100. Omitted uses the mesh size. Nonuniform collision follows the native engine limitations.
      * @param physics Optional collision: `static` (the default), `rigid` or `none`.
      * @param virtualWorld Optional virtual world the prop belongs to; omitted puts it in the global one.
      * @returns The newly spawned prop handle.
      */
-    static spawn(model: string, position?: Vector3 | Partial<Vector3>, rotation?: Vector3 | Quaternion, scale?: number, physics?: string, virtualWorld?: number): Prop;
+    static spawn(model: string, position?: Vector3 | Partial<Vector3>, rotation?: Vector3 | Quaternion, scale?: number | Vector3, physics?: string, virtualWorld?: number): Prop;
 
     /**
      * Lists every prop the server currently has.
@@ -3329,22 +3654,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 +3679,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;
   }
 
   /**
@@ -3377,7 +3702,7 @@ declare global {
    */
   class LevelEdit {
     /**
-     * Wraps an edit the server already holds; use LevelEdit.apply or LevelEdit.applyMap to make one.
+     * Wraps an edit the server already holds; use LevelEdit.apply to make one, or WorldResource for a whole export.
      * @param id Network entity identifier.
      */
     constructor(id: number);
@@ -3461,14 +3786,6 @@ declare global {
      */
     static apply(definition: LevelEditDefinition, virtualWorld?: number): LevelEdit;
 
-    /**
-     * Applies every entry of a map's `world` array, which is how edits made in the World Builder reach every player instead of being loaded by hand on each.
-     * @param map A World Builder map saved from the editor, as its JSON text or the parsed object. Only its `world` array is read: its placed objects are `Prop.spawn`'s, its areas `Area.create`'s.
-     * @param virtualWorld Optional virtual world whose players see the edits; the global one when omitted.
-     * @returns One edit per entry, in the map's order. Throws, naming the entry, for one no client could find the object by.
-     */
-    static applyMap(map: string | Record<string, unknown>, virtualWorld?: number): LevelEdit[];
-
     /**
      * Lists every edit the server currently has.
      * @param virtualWorld Optional virtual world to list; omitted lists every one of them.
@@ -3722,10 +4039,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 +4349,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 +4382,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.
@@ -4393,7 +4715,7 @@ declare global {
   }
 
   /**
-   * Replicated handle for one of the level's animated gates.
+   * Replicated handle for one of the level's castle gates.
    */
   class Gate {
     /**
@@ -4403,12 +4725,12 @@ declare global {
     constructor(id: number);
 
     /**
-     * The level's own EntityGuid, as sixteen lowercase hex digits. The same on every machine, so it is the identity to store a gate under; `Gate.find` takes it back.
+     * The level's own EntityGuid, as sixteen lowercase hex digits. The same on every machine, so it is the identity to store a gate under; `Gate.find` takes it back. A `gate` has no entity of its own, so its key is the GUID of the layer that draws it shut.
      */
     readonly guid: string;
 
     /**
-     * What piece of architecture this is: `drawbridge` or `portcullis`. The shipped game has two in total.
+     * What piece of architecture this is: `drawbridge` or `portcullis`, which animate, or `gate`, a pair of leaves the level swaps between drawn open and drawn shut -- the Ratborsch and Nebakov fortress gates and the Ruthard palace gate. A `gate` opens and closes at once.
      */
     readonly kind: string;
 
@@ -4428,7 +4750,7 @@ declare global {
     readonly moving: boolean;
 
     /**
-     * How long opening takes, in seconds, from the key range the asset's animation database stores. A gate with no opening clip runs its closing one backwards, so this is that clip's length.
+     * How long opening takes, in seconds, from the key range the asset's animation database stores. A gate with no opening clip runs its closing one backwards, so this is that clip's length. 0 for a `gate`.
      */
     readonly openDuration: number;
 
@@ -4483,6 +4805,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 attacker is asked to report when near enough, else the player nearest the target, 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 +4971,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 +4981,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 +5250,97 @@ declare global {
   }
 
   /**
-   * Replicated container handle: one a script spawned, or one the level places.
+   * A named world export loaded from mod.world_resources. Server-owned, with live access to its surviving props, effects, level edits and areas. Obtain handles through all or find; runtime loading, reloading and unloading are not exposed.
+   */
+  class WorldResource {
+    private constructor();
+
+    /**
+     * Unique case-sensitive resource name: the filename without .world.json, or the explicit config name. Empty after shutdown.
+     */
+    readonly name: string;
+
+    /**
+     * Resolved absolute source file path, in UTF-8. Empty after shutdown.
+     */
+    readonly path: string;
+
+    /**
+     * The exported game level, checked against the server level at startup. Empty after shutdown.
+     */
+    readonly level: string;
+
+    /**
+     * Whether this export is registered. Remains true even if scripts destroy all of its contents.
+     */
+    readonly loaded: boolean;
+
+    /**
+     * A fresh array of surviving props in export order. Changing the array does not change membership; the handles support normal Prop operations.
+     */
+    readonly props: Prop[];
+
+    /**
+     * A fresh array of surviving effects in export order, excluding destroyed effects.
+     */
+    readonly effects: Vfx[];
+
+    /**
+     * A fresh array of surviving level edits in export order, excluding restored edits.
+     */
+    readonly levelEdits: LevelEdit[];
+
+    /**
+     * A fresh array of surviving exported areas in export order, excluding destroyed areas.
+     */
+    readonly areas: Area[];
+
+    /**
+     * True after every configured export has loaded successfully, even when the config list is empty. Check this before subscribing to worldResourcesReady when a script may start later.
+     */
+    static readonly ready: boolean;
+
+    /**
+     * Lists config-loaded world exports in configuration order. Empty before successful startup and after shutdown.
+     * @returns A fresh array of resource handles.
+     */
+    static all(): WorldResource[];
+
+    /**
+     * Finds a config-loaded export by name. Throws for a non-string argument.
+     * @param name Exact, case-sensitive resource name.
+     * @returns The resource, or null when absent or startup has not completed.
+     */
+    static find(name: string): WorldResource | null;
+  }
+
+  /**
+   * 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 +5350,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 +5401,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 +5432,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 +5448,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 +5469,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 +5478,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 +5684,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.
      */
@@ -6932,6 +7512,8 @@ declare global {
    * Arbitrary key/value state attached to one replicated entity, reached as `entity.state`. Keys set on the server replicate to every client that can currently see the entity.
    */
   class StateBag {
+    private constructor();
+
     /**
      * Reads one key from this entity's state.
      * @param key Key to read.