@kingdomsconnected/types 1.5.4 → 1.5.6

package/generated/client-api.d.ts

@@ -84,6 +84,16 @@ declare global {
      */
     noclipChanged: [active: boolean, reason: "script" | "mapEditor" | "viewLost" | "sessionOver"];
 
+    /**
+     * Dispatched when a book `Book.open` asked for is in the player's hands and showing its first page, on this machine only.
+     */
+    bookOpened: [bookId: number];
+
+    /**
+     * Dispatched when a book leaves the player's hands, on this machine only. `reason` is `player` for the player's own exit (or the game ending the reading itself), `script` for `Book.close`, `failed` for a book that never reached the hands, and `sessionOver` for the session ending. Handler promises are not awaited, and a handler may open the next book straight away.
+     */
+    bookClosed: [bookId: number, reason: "player" | "script" | "failed" | "sessionOver"];
+
     /**
      * Dispatched after a resource entry point has run and immediately before the resource becomes running.
      */
@@ -898,7 +908,9 @@ declare global {
   };
 
   /**
-   * The game's own HUD messages, shown to the player at this machine. Nothing here is replicated: a message everyone should see is sent to everyone, and each client shows it. Every call returns false while there is no HUD, which is the case in the main menu and across a level load.
+   * The game's own HUD messages, shown to the player at this machine. Nothing here is replicated: a message everyone should see is sent to everyone, and each client shows it. Every message call returns false while there is no HUD, which is the case in the main menu and across a level load.
+   * 
+   * The screen-effect verbs -- `addScreenEffect` and its siblings -- put full-screen post effects on this player's own picture. They are drawn by the game's renderer rather than the HUD, so they need no HUD and hiding HUD elements leaves them alone.
    */
   const Hud: {
     /**
@@ -1010,8 +1022,129 @@ declare global {
      * @returns True when the HUD took it.
      */
     clearNotifications(): boolean;
+
+    /**
+     * Retains a visibility request for one HUD element, including before the HUD is ready. Hidden clips are suppressed before each HUD render, across movie and level reloads. Turning an element on releases multiplayer suppression; the current native HUD rules still apply. Suppression is released when its owning resource stops or the session ends. No console variables are changed.
+     * @param element The element, by the game's own name for it: `Stats` is the health, stamina and nourishment bars along the bottom. One of `Compass`, `Stats`, `QAMWeapon`, `QAMFood`, `Subtitles`, `InfoText`, `GameLog`, `Hints`, `DialogLeft`, `DialogRight`, `Cursor`, `Crime`, `Wanted`, `PopUpBackground`, `TutorialMessage`, `FancyEvent`, `SkillCheck`, `ItemTransfer`, `Buffs`, `CommonEvent`, `DiceCursor`, `Trespassing`, `RatioStrips`, `ShootingContest`, `Bubbles`, `TutorialInDialog`, `DiceContainer`, `Vignette`, compared exactly.
+     * @param visible False hides the element, true lets the game show it again.
+     * @returns True when the request is retained; application waits for the native HUD when it is not ready yet.
+     */
+    setElementVisible(element: string, visible: boolean): boolean;
+
+    /**
+     * Whether multiplayer permits the element to show. True when no resource suppresses it; native gameplay rules can still hide it. This is not a pixel-visibility query.
+     * @param element The element, by the game's own name for it, as `setElementVisible` takes it.
+     * @returns True while multiplayer allows the element to show.
+     */
+    isElementVisible(element: string): boolean;
+
+    /**
+     * Every effect `addScreenEffect` accepts, with each parameter's range, default and neutral value.
+     * @returns The effects, in a fixed order.
+     */
+    screenEffects(): ScreenEffect[];
+
+    /**
+     * Puts a full-screen effect on this player's own picture -- a colour grade, a blur, ghosting or the game's blood overlay, for intoxication, injury, poison, dreams or a place that should feel wrong -- owned by the calling resource. These are the game's own post-processing passes, driven with the parameters this build actually reads; they are not part of the HUD and showing or hiding HUD elements does not touch them.
+     * 
+     * This is presentation, not state. Nothing is replicated, nobody else sees it, and none of it makes a player drunk or hurt: whatever decides that -- usually the server -- keeps it, and a client script asks for the picture to match. Weather and time of day are shared world state and are not touched.
+     * 
+     * Effects from every resource combine rather than overwrite each other, on top of the game's own grade -- which already desaturates the screen as health runs low -- rather than in its place: brightness, contrast and saturation multiply, the colour cast and the hue shift add, and blur, ghosting and blood each draw the strongest one asked for. The result does not depend on which resource asked first, and removing one effect leaves the game's grade and every other effect as they were.
+     * 
+     * An effect belongs to the resource that created it: only that resource can change or remove it, and it goes when the resource stops, when the session ends or when the level changes. A cinematic that resets the game's post-processing clears the screen until the effect next changes. Up to 64 effects are kept across every resource.
+     * @param effect Which effect, as `screenEffects` names it.
+     * @param params Values for the effect's own parameters, each clamped into its range. A parameter left out takes its default; one the effect does not take is an error.
+     * @param options `fadeInMs` brings it up from nothing; `fadeOutMs` is how long it takes to go, when its duration runs out or when `removeScreenEffect` is called without a fade of its own; `durationMs` ends it on its own after that long, before its fade-out -- 0, the default, keeps it until it is removed. Fades are up to a minute.
+     * @returns A handle for `updateScreenEffect`, `removeScreenEffect` and `isScreenEffectActive`, or 0 when 64 effects are already on screen.
+     */
+    addScreenEffect(effect: "colorGrade" | "blur" | "ghosting" | "screenBlood", params?: { saturation?: number; brightness?: number; contrast?: number; cyan?: number; magenta?: number; yellow?: number; darkness?: number; hue?: number; amount?: number }, options?: { fadeInMs?: number; fadeOutMs?: number; durationMs?: number }): number;
+
+    /**
+     * Changes an effect while it is on screen -- a drunkenness that deepens with every drink, a wound that worsens.
+     * @param handle What `addScreenEffect` returned.
+     * @param params New values for some of the effect's parameters. The others keep theirs.
+     * @param options `fadeMs` moves the parameters to their new values over that long, from wherever they are now; 0, the default, moves them at once.
+     * @returns False when the handle is gone or belongs to another resource.
+     */
+    updateScreenEffect(handle: number, params: { saturation?: number; brightness?: number; contrast?: number; cyan?: number; magenta?: number; yellow?: number; darkness?: number; hue?: number; amount?: number }, options?: { fadeMs?: number }): boolean;
+
+    /**
+     * Takes an effect off the screen. An effect already fading out carries on from where it is.
+     * @param handle What `addScreenEffect` returned.
+     * @param options How long it takes to fade out. Left out, it fades over the `fadeOutMs` it was created with; 0 takes it off at once.
+     * @returns False when the handle is gone or belongs to another resource.
+     */
+    removeScreenEffect(handle: number, options?: { fadeOutMs?: number }): boolean;
+
+    /**
+     * Takes every effect the calling resource owns off the screen at once. Other resources' effects stay.
+     * @returns How many were removed.
+     */
+    removeAllScreenEffects(): number;
+
+    /**
+     * Whether an effect is still on screen, fading out included.
+     * @param handle What `addScreenEffect` returned.
+     * @returns False once it has been removed and faded, has run its duration out, or was dropped by its resource stopping, the session ending or the level changing.
+     */
+    isScreenEffectActive(handle: number): boolean;
   };
 
+  /**
+   * One parameter a screen effect takes.
+   */
+  interface ScreenEffectParam {
+    /**
+     * The key to pass it under in a params bag.
+     */
+    name: string;
+
+    /**
+     * What it does to the picture.
+     */
+    description: string;
+
+    /**
+     * The lowest value it takes. Anything lower is clamped.
+     */
+    min: number;
+
+    /**
+     * The highest value it takes. Anything higher is clamped.
+     */
+    max: number;
+
+    /**
+     * What `addScreenEffect` uses when the parameter is not given.
+     */
+    default: number;
+
+    /**
+     * The value at which it leaves the picture alone, which is also where a fade starts and ends.
+     */
+    neutral: number;
+  }
+
+  /**
+   * One screen effect `Hud.addScreenEffect` accepts.
+   */
+  interface ScreenEffect {
+    /**
+     * What to pass to `addScreenEffect`.
+     */
+    name: string;
+
+    /**
+     * What it does, and how several of it combine.
+     */
+    description: string;
+
+    /**
+     * Every parameter it takes, with its range.
+     */
+    params: ScreenEffectParam[];
+  }
+
   /**
    * The game's own sound triggers, played at this machine. A trigger is a name the game's audio data declares -- `a_o_bell_kkut_kostelni`, `c_torch_whoosh1`, `f_ge_cough_woman` -- standing for an FMOD event. The full vocabulary is `Libs/GameAudio/*.xml` in `IPL_GameData.pak`, with the gameplay-facing subset listed in `Libs/Tables/GameAudio/SkaldAtlTrigger.xml`. Nothing here is replicated: a sound everyone should hear is one the server tells every client to play. Every call returns false while the audio system is not up, which is the case before a world is loaded, and for a trigger name the audio data does not declare.
    */
@@ -1815,7 +1948,7 @@ declare global {
      * 
      * This is what a disguised player needs -- `player.setDisguise` hides the body the game's own camera sits in. It is this client's own view, so a gamemode turns it on from a client script, typically on an event the server sends the disguised player.
      * 
-     * There is one view to draw through: `NoClip` cannot start while this holds it, and while `NoClip` flies this waits. It lasts until the session ends.
+     * There is one view to draw through: `NoClip` cannot start while this holds it, and while `NoClip` flies this waits. The map, the inventory and the other pause-screen pages are filmed by the game's own camera, so this steps aside while one is open and comes back when it closes. It lasts until the session ends.
      * @param options Where the camera sits, in metres: `distance` back from the body along where the player looks (3.5 by default, 0.3 to 20), `height` of the point it orbits above the body's feet (1.6, up to 5 either way), and `shoulder` to the right of it, negative for the left (0, up to 3 either way). Null hands the view back to the game's own camera. Called again while on, it only moves the camera.
      */
     setThirdPerson(options?: { distance?: number; height?: number; shoulder?: number } | null): void;
@@ -2557,6 +2690,111 @@ declare global {
     getCatalog(): EmoteCatalogEntry[];
   };
 
+  /**
+   * A picture for the skill-book and map layouts, which place pictures by page rather than inline.
+   */
+  interface BookPageImage {
+    /**
+     * Zero-based page the picture belongs to.
+     */
+    page: number;
+
+    /**
+     * Its name under the game's own `Libs/UI/Textures/Books/` Skills or Maps folder, without the `_ui.dds` suffix, e.g. `swords1`.
+     */
+    image: string;
+  }
+
+  /**
+   * What `Book.open` shows and how it looks.
+   */
+  interface BookOptions {
+    /**
+     * One string per page, written in the book movie's own markup: `<title>`, `<subtitle>`, `<heading>`, `<paragraph>`, `<br/>`, `<accent>`, `<inc>X</inc>` for a decorated initial, `<poem>`, `<lpoem>`, `<note>`, `<p align>`, `<font size>`, `<i>` and `<img src='...' width='W' height='H' align='center'/>`. A page break follows every page but the last; `<newpage/>` inside a page breaks it further. The player's own reading skill never scrambles it; `legibility` decides that.
+     */
+    pages: string[];
+
+    /**
+     * The object in the player's hands: a red-covered book (the default), a plain-covered one, or a folded letter.
+     */
+    style: "book" | "plainBook" | "letter" | undefined;
+
+    /**
+     * The layout the movie uses, by `document_class` id: 1 book (the default), 2 recipe, 3 skill book, 4 map, 5 letter (the default for `letter`), 6 plan.
+     */
+    type: number | undefined;
+
+    /**
+     * How ornate the pages are, 1 plain to 7 embellished. Defaults to 1.
+     */
+    visual: number | undefined;
+
+    /**
+     * How much of the text can be read, 0 to 1; values outside are clamped. Defaults to 1, fully legible. Below 1 the movie swaps letters for look-alike glyphs, the same effect a vanilla book shows a player with low reading skill. It works in tenths: each step brings roughly another tenth of the character classes back, so 0.31 and 0.39 look the same. The substitution is deterministic -- the same text at the same level always reads the same way -- and markup is never touched.
+     */
+    legibility: number | undefined;
+
+    /**
+     * A picture `Book.image` returned, replacing the carrier's own diffuse texture: the paper and the cover together, which the model maps from one atlas. Paint it over the vanilla atlas to keep the UV layout -- `Objects/manmade/task_specific_props/read_and_write/books/book_alchemy_diff.dds` for the two book styles, `.../scrolls/scroll_diff.dds` for `letter`. The material's diffuse colour multiplies it: `book` darkens it to about 78% and `letter` to about 72%, while `plainBook` shows it as painted. It applies to this book's own copy of the material only, and goes with the book.
+     */
+    texture: string | undefined;
+
+    /**
+     * Pictures for the skill-book and map layouts. Inline pictures go in the page text as `<img>` instead.
+     */
+    images: BookPageImage[] | undefined;
+  }
+
+  /**
+   * Books a resource composes and opens in this player's hands.
+   * 
+   * A book is shown through the game's own reading: the same book in hand, camera, page-turn animation, prompts and pagination as any book the player reads from their inventory. The player turns pages and leaves it with the game's own keys, and `bookClosed` says when they did.
+   * 
+   * Client-only and local: the book exists on this machine alone, and reading it grants nothing -- no XP, no read marker, no quest progress. A server that wants a player to read something sends the pages in its own event.
+   * 
+   * Pictures a resource ships go through `Book.image`, which returns what an `<img src>` and the `texture` option take.
+   */
+  const Book: {
+    /**
+     * Opens a book in the player's hands.
+     * @param options The pages and how they look.
+     * @returns The book's id, which `bookOpened` and `bookClosed` carry; null when the game will not open one now -- no body yet, a book already open, or a place the player cannot read in (on horseback, in combat). `getLastError` says which. Malformed options throw.
+     */
+    open(options: BookOptions): number | null;
+
+    /**
+     * Closes the open book the way the player's own exit does.
+     * @returns False when no book is open.
+     */
+    close(): boolean;
+
+    /**
+     * Changes how legible the open book is, while it is in the player's hands.
+     * @param value 0 fully scrambled to 1 fully legible; clamped.
+     * @returns False when no book is in the hands yet (wait for `bookOpened`). The movie applies legibility while laying the text out, so the book is laid out again, which can return it to its first page. Throws for a non-number.
+     */
+    setLegibility(value: number): boolean;
+
+    /**
+     * The id of the book in the player's hands.
+     * @returns Null when there is none.
+     */
+    getOpenBook(): number | null;
+
+    /**
+     * Why the last `open` returned null.
+     * @returns Empty after one that succeeded.
+     */
+    getLastError(): string;
+
+    /**
+     * Makes a picture the resource ships reachable from page text.
+     * @param path A `.dds` file the calling resource ships, relative to the resource.
+     * @returns The value for an `<img src='...'>` attribute. Give the tag a `width` and `height` too: the movie sizes the picture to them and has no size of its own for it. Throws when the file is missing, not a `.dds`, or larger than 16 MiB.
+     */
+    image(path: string): string;
+  };
+
   /**
    * Mutable two-dimensional vector.
    */

package/generated/server-api.d.ts

@@ -195,27 +195,37 @@ declare global {
     playerPickpocketCaught: [thief: Player, victim: Player];
 
     /**
-     * A player asks to open an alchemy table. Every handler runs; one returning literal `false` refuses it. An async handler cannot refuse.
+     * Dispatched once a match has started and both players have been sent to the table. Which of them throws first is drawn at random.
+     */
+    diceMatchStart: [match: number, first: Player, second: Player, targetScore: number];
+
+    /**
+     * Dispatched once a match is over and both players have been told. `winner` is 0 when `first` won, 1 when `second` did, 255 when nobody did. `reason` is `won` (a player banked the target score), `gaveUp` (a player left the table), `left` (a player disconnected), `timedOut` (the player to throw did not move for three minutes), `failed` (a client could not play the table) or `stopped` (`Dice.stop`). A player who has gone since is null. Nothing changes hands on its own: what a match was played for is the gamemode's to settle here.
+     */
+    diceMatchEnd: [match: number, first: Player | null, second: Player | null, winner: number, reason: string, firstScore: number, secondScore: number];
+
+    /**
+     * 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.
      */
     craftingStarting: [player: Player, proposal: CraftStartProposal];
 
     /**
-     * A batch is brewing.
+     * A batch is brewing, or a workpiece took its materials.
      */
     craftingStarted: [player: Player, event: CraftStartedEvent];
 
     /**
-     * A batch finished and its result is computed. Every handler runs; one returning literal `false` refuses it: the batch ends as failed, what was spent stays spent, and nothing is granted.
+     * A batch or workpiece finished and its result is computed. Every handler runs; one returning literal `false` refuses it: alchemy ends the batch as failed, what was spent stays spent, and nothing is granted; smithing fails the workpiece, spending its failure share.
      */
     craftingCompleting: [player: Player, proposal: CraftCompletionProposal];
 
     /**
-     * A batch's result was granted, followed by `craftingEnded`. Raised after the `playerInventoryChanged` it caused.
+     * A result was granted, followed by `craftingEnded`. Raised after the `playerInventoryChanged` it caused.
      */
     craftingCompleted: [player: Player, event: CraftCompletedEvent];
 
     /**
-     * A batch is over. Raised after the `playerInventoryChanged` of any refund.
+     * A batch or workpiece is over. Raised after the `playerInventoryChanged` of any refund.
      */
     craftingEnded: [player: Player, event: CraftEndedEvent];
 
@@ -375,7 +385,7 @@ declare global {
     gatheringHarvest: [player: Player, proposal: GatheringProposal];
 
     /**
-     * A player was given a herb, after the `playerInventoryChanged` it caused. The plant and the same-kind plants harvested with it are picked for everyone in the virtual world until they regrow; nothing about them survives a restart.
+     * A player was given a herb, after the `playerInventoryChanged` it caused. The plant and the same-kind plants harvested with it are picked for everyone in the virtual world until timed or scripted regrowth; nothing about them survives a restart.
      */
     gatheringHarvested: [player: Player, event: GatheringHarvestedEvent];
 
@@ -1613,7 +1623,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`, `invalidQuality`, `immutableItemHealth`, `invalidItemHealth`, `contradictoryItemHealth`, `invalidCreationSentinel`, `unsupportedPoisonProperties`, `unsupportedOnEquipBuffs`).
+     * 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`).
      */
     code: string;
 
@@ -1639,7 +1649,7 @@ declare global {
     get(player: Player): InventoryState | null;
 
     /**
-     * Gives a player items of a class, 1 to 10000 at a time. Left-out properties mean quality 1 at full condition. 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.
      */
     add(player: Player, request: { item: string; amount: number; metadata?: Record<string, unknown>; revision?: number }): InventoryResult;
 
@@ -1662,6 +1672,21 @@ declare global {
      * 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.
      */
     transfer(source: Player, target: Player, request: { units: InventoryUnit[]; sourceRevision?: number; targetRevision?: number }): 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.
+     * @param metadata The item's properties, as a row's `metadata` holds them.
+     * @returns Null for a class the server does not know, or metadata `Inventory.add` would refuse.
+     */
+    getItemPrice(item: string, metadata?: Record<string, unknown>): { pristine: number; current: number } | null;
+
+    /**
+     * Changes what every player's game calls an item, in their inventory, the shops, loot and anywhere else the game names it; null gives the game its own name back. Every player sees it, including those who join later, until the server stops.
+     * 
+     * The game does not name classes one by one: many classes show the same name -- every kite shield is a Kite Shield -- and renaming one renames all of them. The result lists them. A name is up to 128 bytes with no control characters, and is not translated.
+     * @returns The GUIDs of every class that now shows this name.
+     */
+    setItemName(item: string, name: string | null): string[];
   };
 
   /**
@@ -2131,31 +2156,86 @@ declare global {
   }
 
   /**
-   * A table a player is about to open. Frozen: a handler can refuse it, not change it.
+   * How a dice match is played.
+   */
+  interface DiceMatchOptions {
+    /**
+     * The score that wins, banked at the end of a turn. 2000 when omitted, at most 100000.
+     */
+    targetScore: number | undefined;
+  }
+
+  /**
+   * Dice matches between two players on the game's own dice table.
+   * 
+   * 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: {
+    /**
+     * 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.
+     * @param second NetworkID of the player on the second seat.
+     * @param options The target score. Optional.
+     * @returns The match id.
+     */
+    start(first: number, second: number, options?: DiceMatchOptions): number;
+
+    /**
+     * Ends a match with nobody winning; both tables close.
+     * @param match The match to end.
+     * @returns False when it had already ended.
+     */
+    stop(match: number): boolean;
+
+    /**
+     * The match a player is in.
+     * @param player NetworkID of the player to ask about.
+     * @returns The match id, or 0.
+     */
+    matchOf(player: number): number;
+  };
+
+  /**
+   * A table a player is about to open, or a workpiece about to take its materials. Frozen: a handler can refuse it, not change it.
    */
   interface CraftStartProposal {
+    /**
+     * Which craft.
+     */
+    kind: 'alchemy' | 'smithing';
+
     /**
      * Station id, as `Crafting.stations` names it.
      */
     station: string;
 
     /**
-     * The player's virtual world; each world has its own tables.
+     * The player's virtual world; each world has its own stations.
      */
     virtualWorld: number;
 
     /**
-     * The batch this one follows at a table the player kept, or empty for a fresh entry.
+     * Smithing only: the recipe id the player chose, as `Crafting.recipes` keys it.
+     */
+    recipe: string | undefined;
+
+    /**
+     * The batch this one follows at a table the player kept, or empty for a fresh entry. Always empty for smithing.
      */
     continuationOf: string;
   }
 
   /**
-   * A batch that is now brewing: the table's opening animation finished, or the next batch started at a table the player kept.
+   * A batch that is now brewing, or a workpiece whose materials were taken.
    */
   interface CraftStartedEvent {
     /**
-     * The batch's session id.
+     * Which craft.
+     */
+    kind: 'alchemy' | 'smithing';
+
+    /**
+     * The batch's or workpiece's session id.
      */
     session: string;
 
@@ -2165,22 +2245,32 @@ declare global {
     station: string;
 
     /**
-     * The table's virtual world.
+     * The station's virtual world.
      */
     virtualWorld: number;
 
     /**
-     * The previous batch at this table, or empty for the first.
+     * Smithing only: the recipe being worked.
+     */
+    recipe: string | undefined;
+
+    /**
+     * The previous batch at this table, or empty for the first. Always empty for smithing.
      */
     continuationOf: string;
   }
 
   /**
-   * What a finished batch is about to grant, computed by the server. Frozen: a handler can refuse it, not change it.
+   * What a finished batch or workpiece is about to grant, computed by the server. Frozen: a handler can refuse it, not change it.
    */
   interface CraftCompletionProposal {
     /**
-     * The batch's session id.
+     * Which craft.
+     */
+    kind: 'alchemy' | 'smithing';
+
+    /**
+     * The session id.
      */
     session: string;
 
@@ -2190,22 +2280,22 @@ declare global {
     station: string;
 
     /**
-     * `failed` brews the game's failed potion.
+     * `failed` brews the game's failed potion. A smithing proposal is always `success`: a failed workpiece grants nothing to review.
      */
     outcome: 'success' | 'failed';
 
     /**
-     * The recipe the brew matched, or empty when it matched none.
+     * The recipe the brew matched, or empty when it matched none; the smithing recipe worked.
      */
     recipe: string;
 
     /**
-     * The product's native rank.
+     * The product's native rank; for smithing, its item quality tier.
      */
     grade: number;
 
     /**
-     * Item class GUID of what would be granted, or empty when the yield came out at zero.
+     * Item class GUID of what would be granted, or empty when nothing is: a zero alchemy yield, or a smithing quest product its quest creates.
      */
     product: string;
 
@@ -2215,22 +2305,32 @@ declare global {
     amount: number;
 
     /**
-     * Brewing quality, 0 to 1, after perks and the table-entry bonus.
+     * Brewing quality, 0 to 1, after perks and the table-entry bonus; for smithing, the workpiece quality the player's game reported.
      */
     quality: number;
 
     /**
-     * Base alchemy XP; the player's own multipliers apply on top.
+     * Base alchemy or craftsmanship XP; the player's own multipliers apply on top.
      */
     xp: number;
+
+    /**
+     * Smithing only: lockpicks granted alongside, drawn by the server from the player's perks.
+     */
+    lockpicks: number | undefined;
   }
 
   /**
-   * A batch whose result was granted: the output is in the inventory and the XP was ordered.
+   * A batch or workpiece whose result was granted: the output is in the inventory and the XP was ordered.
    */
   interface CraftCompletedEvent {
     /**
-     * The batch's session id.
+     * Which craft.
+     */
+    kind: 'alchemy' | 'smithing';
+
+    /**
+     * The session id.
      */
     session: string;
 
@@ -2240,7 +2340,7 @@ declare global {
     station: string;
 
     /**
-     * The table's virtual world.
+     * The station's virtual world.
      */
     virtualWorld: number;
 
@@ -2255,37 +2355,47 @@ declare global {
     recipe: string;
 
     /**
-     * The product's native rank.
+     * The product's native rank; for smithing, its item quality tier.
      */
     grade: number;
 
     /**
-     * Brewing quality, 0 to 1.
+     * Brewing or workpiece quality, 0 to 1.
      */
     quality: number;
 
     /**
-     * Base alchemy XP ordered.
+     * Base XP ordered.
      */
     xp: number;
 
     /**
-     * The inventory rows that received the output. Do not grant it again.
+     * Smithing only: lockpicks granted.
+     */
+    lockpicks: number | undefined;
+
+    /**
+     * The inventory rows that received the output, lockpicks included. Do not grant it again.
      */
     outputs: InventoryUnit[];
 
     /**
-     * The player's recipe knowledge after this batch, as `Crafting.knowledge` returns it.
+     * Alchemy only: the player's recipe knowledge after this batch, as `Crafting.knowledge` returns it.
      */
-    knowledge: Record<string, number>;
+    knowledge: Record<string, number> | undefined;
   }
 
   /**
-   * A batch that is over, for any reason. A table kept for the next batch is not closed by this.
+   * A batch or workpiece that is over, for any reason. A table kept for the next batch is not closed by this.
    */
   interface CraftEndedEvent {
     /**
-     * The batch's session id.
+     * Which craft.
+     */
+    kind: 'alchemy' | 'smithing';
+
+    /**
+     * The session id.
      */
     session: string;
 
@@ -2295,7 +2405,7 @@ declare global {
     station: string;
 
     /**
-     * The table's virtual world.
+     * The station's virtual world.
      */
     virtualWorld: number;
 
@@ -2305,12 +2415,12 @@ declare global {
     outcome: 'success' | 'failed' | 'cancelled';
 
     /**
-     * Empty for a completed batch. `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.
+     * 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`.
      */
     reason: string;
 
     /**
-     * The inventory rows ingredients went back to. Wholly unmilled bowl, mortar and herb groups come back; everything else put on the table was spent.
+     * 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.
      */
     refunded: InventoryUnit[];
   }
@@ -2333,6 +2443,11 @@ declare global {
      * Units required for one attempt.
      */
     amount: number;
+
+    /**
+     * A quest item, which only its quest hands out: the game cannot create one, so the inventory refuses it (`questItem`) and Player.giveItem returns false. It must be held to craft, and is never taken.
+     */
+    quest: boolean;
   }
 
   /**
@@ -2436,7 +2551,7 @@ declare global {
   }
 
   /**
-   * Who holds an alchemy table. A player keeps it between batches until they leave it.
+   * Who holds a station. A player keeps an alchemy table between batches until they leave it; a smithery is held for one workpiece.
    */
   interface CraftStationOccupant {
     /**
@@ -2455,9 +2570,9 @@ declare global {
     sessionId: string;
 
     /**
-     * `entering` until the opening animation finishes; `finishing` while a finished batch waits to settle.
+     * `entering` until the opening animation finishes; `finishing` while a finished batch waits to settle; `working` at a smithery.
      */
-    phase: 'entering' | 'brewing' | 'finishing' | 'betweenBatches';
+    phase: 'entering' | 'brewing' | 'finishing' | 'betweenBatches' | 'working';
 
     /**
      * Milliseconds until the table is taken back. Each batch has 30 minutes.
@@ -2466,7 +2581,7 @@ declare global {
   }
 
   /**
-   * One table in one virtual world. A free table may still be unusable in the game, for instance behind a quest layer.
+   * One station in one virtual world. A free station may still be unusable in the game, for instance behind a quest layer.
    */
   interface CraftStationOccupancy {
     /**
@@ -2491,11 +2606,16 @@ declare global {
   }
 
   /**
-   * A player's alchemy session, or the table they kept between batches. A copy: changing it changes nothing.
+   * A player's alchemy session or kept table, or their smithing workpiece. A copy: changing it changes nothing.
    */
   interface CraftSessionInfo {
     /**
-     * The batch's session id.
+     * Which craft.
+     */
+    kind: 'alchemy' | 'smithing';
+
+    /**
+     * The session id.
      */
     id: string;
 
@@ -2505,24 +2625,34 @@ declare global {
     station: string;
 
     /**
-     * The table's virtual world.
+     * The station's virtual world.
      */
     virtualWorld: number;
 
     /**
-     * Where the batch is.
+     * Where the batch is; `working` for a smithing workpiece.
+     */
+    phase: 'entering' | 'brewing' | 'finishing' | 'betweenBatches' | 'working';
+
+    /**
+     * Alchemy only: native actions accepted so far.
      */
-    phase: 'entering' | 'brewing' | 'finishing' | 'betweenBatches';
+    sequence: number | undefined;
 
     /**
-     * Native actions accepted so far.
+     * Alchemy only: what is on the table: item class, the inventory row it came from (empty for a base liquid), and the native table position.
      */
-    sequence: number;
+    resources: { id: number; item: string; itemId: string; position: number; base: boolean; milled: boolean; distilled: boolean }[] | undefined;
 
     /**
-     * What is on the table: item class, the inventory row it came from (empty for a base liquid), and the native table position.
+     * Smithing only: the recipe being worked.
      */
-    resources: { id: number; item: string; itemId: string; position: number; base: boolean; milled: boolean; distilled: boolean }[];
+    recipe: string | undefined;
+
+    /**
+     * Smithing only: the units taken from the inventory for this workpiece. Quest materials are required but never taken.
+     */
+    materials: { item: string; amount: number }[] | undefined;
 
     /**
      * Milliseconds until the session times out.
@@ -2531,11 +2661,11 @@ declare global {
   }
 
   /**
-   * Crafting catalogs, alchemy table occupancy, sessions and recipe knowledge. Held in memory for each connection; nothing is saved.
+   * Crafting catalogs, station occupancy, alchemy and smithing sessions, and alchemy recipe knowledge. Held in memory for each connection; nothing is saved.
    */
   const Crafting: {
     /**
-     * True for alchemy, false for smithing, which is not synchronized yet. Omitted kind checks alchemy.
+     * True: alchemy and smithing are both ruled by the server. Omitted kind checks alchemy.
      */
     isAvailable(kind?: 'alchemy' | 'smithing'): boolean;
 
@@ -2550,17 +2680,17 @@ declare global {
     recipes(player: Player, kind?: 'alchemy' | 'smithing'): readonly CraftRecipeInfo[];
 
     /**
-     * The player's alchemy session or the table they kept between batches, or null.
+     * The player's alchemy session or the table they kept between batches, else their smithing workpiece, else null.
      */
     session(player: Player): CraftSessionInfo | null;
 
     /**
-     * Who holds a table. World defaults to 0. Null for an unknown or non-alchemy station.
+     * Who holds a station. World defaults to 0. Null for an unknown station.
      */
     occupancy(stationId: string, virtualWorld?: number): CraftStationOccupancy | null;
 
     /**
-     * Ends the player's session as leaving the table would: wholly unmilled groups go back to the inventory, the rest is spent, the table is released and their game closes it. `craftingEnded` follows next tick. False when there was nothing to end.
+     * Ends the player's session as leaving the station would, and their game closes it. Alchemy: wholly unmilled groups go back to the inventory, the rest is spent. Smithing: the workpiece fails, spending its failure share. `craftingEnded` follows next tick. False when there was nothing to end.
      */
     cancel(player: Player): boolean;
 
@@ -3464,6 +3594,54 @@ declare global {
      */
     toString(): string;
 
+    /**
+     * Checks whether this NPC's nametag is drawn; the same switch as the `nametag` property.
+     * @returns True while the nametag is shown.
+     */
+    isNametagVisible(): boolean;
+
+    /**
+     * Shows or hides the name over this NPC's head for every player; the same switch as the `nametag` property. Each player can still hide all nametags locally.
+     * @param visible True to draw this NPC's nametag for every player, false to hide it.
+     */
+    setNametagVisible(visible: boolean): void;
+
+    /**
+     * Checks whether the health bar under this NPC's nametag is shown.
+     * @returns True unless the health bar was hidden.
+     */
+    isNametagHealthVisible(): boolean;
+
+    /**
+     * Shows or hides the health bar under this NPC's nametag, leaving the name itself alone.
+     * @param visible True to show the health bar under this NPC's name, false to hide it.
+     */
+    setNametagHealthVisible(visible: boolean): void;
+
+    /**
+     * Reads this NPC's nametag text override.
+     * @returns The override, or an empty string when the NPC's `name` is drawn.
+     */
+    getNametagText(): string;
+
+    /**
+     * Overrides the text drawn on this NPC's nametag without renaming it: `name` still reaches conversation and the soul.
+     * @param text Text to show instead of the NPC's name; empty or omitted restores the name.
+     */
+    setNametagText(text?: string): void;
+
+    /**
+     * Reads this NPC's nametag color.
+     * @returns Packed 0xAARRGGBB color; opaque white when untinted.
+     */
+    getNametagColor(): number;
+
+    /**
+     * Tints the text on this NPC's nametag.
+     * @param color Packed 0xAARRGGBB color.
+     */
+    setNametagColor(color: number): void;
+
     /**
      * Despawns this NPC everywhere, after emitting npcDestroy.
      */
@@ -3894,6 +4072,60 @@ declare global {
 
   interface GroundItem extends Entity {}
 
+  /**
+   * The server-wide override for herb regrowth, measured in game hours.
+   */
+  interface GatheringRespawnTime {
+    /**
+     * Lower bound, inclusive. Both bounds zero disable timed regrowth.
+     */
+    minHours: number;
+
+    /**
+     * Upper bound, inclusive. Equal positive bounds give a fixed duration.
+     */
+    maxHours: number;
+  }
+
+  /**
+   * Controls herb regrowth. Defaults are five times faster than the game's authored species timings. Changes are held in server memory.
+   */
+  const Gathering: {
+    /**
+     * Current frozen override, or null for the species defaults at one fifth of their authored duration.
+     */
+    readonly respawnTime: GatheringRespawnTime | null;
+
+    /**
+     * Restarts all active herb deadlines from now and sets the policy for future picks. Samples uniformly per plant. Equal bounds fix the duration; (0, 0) disables timed regrowth while manual respawn remains available. Applies to every virtual world.
+     * @param minHours Minimum game hours, from 0 to maxHours.
+     * @param maxHours Maximum game hours, up to 87600. Positive durations must reach at least one game millisecond.
+     * @returns True on success; false for non-finite, reversed or out-of-range bounds.
+     */
+    setRespawnTime(minHours: number, maxHours: number): boolean;
+
+    /**
+     * Restores five-times-faster species defaults and restarts all active herb timers from now.
+     */
+    resetRespawnTime(): void;
+
+    /**
+     * Respawns recorded harvested plants in a sphere, including plants with timed regrowth disabled. Restores client vegetation as well as server availability. Does not create new plants.
+     * @param position Centre of the sphere in world metres; finite coordinates within +/-100000.
+     * @param radius Inclusive 3D radius in metres, from 0 to 100000.
+     * @param virtualWorld Only this virtual world; defaults to 0.
+     * @returns Number of active harvested sources restored. Invalid arguments throw.
+     */
+    respawn(position: Vector3, radius: number, virtualWorld?: number): number;
+
+    /**
+     * Respawns every recorded harvested plant in one virtual world, including plants with timed regrowth disabled.
+     * @param virtualWorld Only this virtual world; defaults to 0.
+     * @returns Number of active harvested sources restored. Invalid arguments throw.
+     */
+    respawnAll(virtualWorld?: number): number;
+  };
+
   /**
    * A plant a player picked and what it is about to give them.
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kingdomsconnected/types",
-  "version": "1.5.4",
+  "version": "1.5.6",
   "description": "TypeScript declarations for the Kingdoms Connected scripting API, one entry per side: @kingdomsconnected/types/server and @kingdomsconnected/types/client",
   "license": "UNLICENSED",
   "keywords": [