@kingdomsconnected/types 1.5.5 → 1.5.7

package/generated/client-api.d.ts

@@ -1,4 +1,4 @@
-import type { Color, EventHandler, KeyHandler, MessageHandler, MessageReply, NativeClipHandler, NativeElementHandler, NativeScreenHandler, PlacementHandler, Quaternion, Unsubscribe, Vector2, Vector3, WebEventHandler } from "../shared.js";
+import type { ActionHintHandler, Color, EventHandler, KeyHandler, MessageHandler, MessageReply, NativeClipHandler, NativeElementHandler, NativeScreenHandler, PlacementHandler, Quaternion, Unsubscribe, Vector2, Vector3, WebEventHandler } from "../shared.js";
 
 declare global {
   /**
@@ -94,6 +94,11 @@ declare global {
      */
     bookClosed: [bookId: number, reason: "player" | "script" | "failed" | "sessionOver"];
 
+    /**
+     * Dispatched once for every creator, on this machine only, whatever ended it. `appearance` is the look the player accepted, and null for every other ending. `reason` is `accepted`, `cancelled` for the player backing out, `closed` for `CharacterCreator.close`, `replaced` for another `CharacterCreator.open`, `unavailable` when the stage could not be put up, and `interrupted` when the session or the body went away under it. Nothing is put on the body: send the look wherever it should go -- `Events.emitServer`, then `player.setAppearance` on the server -- or open the next creator straight from the handler.
+     */
+    characterCreatorClosed: [appearance: Appearance | null, reason: "accepted" | "cancelled" | "closed" | "replaced" | "unavailable" | "interrupted"];
+
     /**
      * Dispatched after a resource entry point has run and immediately before the resource becomes running.
      */
@@ -909,6 +914,8 @@ 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 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: {
     /**
@@ -1022,21 +1029,127 @@ declare global {
     clearNotifications(): boolean;
 
     /**
-     * Hides or shows one element of the game's HUD at this client, through the switch the game itself keeps for each. It can be called at any time, before the HUD has loaded included: the game re-applies the switch every time the HUD loads, across level loads too. Turning an element on does not force it up; the game still hides it where it would anyway, in dialogue or a menu, say. The player's own setting comes back when the resource that changed it stops.
+     * 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 switch took it; false only before the game has created its HUD switches, which it does at startup.
+     * @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 one element's switch is on. An element whose switch is on can still be hidden by the game at that moment.
+     * 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 the element is allowed to show.
+     * @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.
    */
@@ -2687,6 +2800,102 @@ declare global {
     image(path: string): string;
   };
 
+  /**
+   * What `CharacterCreator.open` shows.
+   */
+  interface CharacterCreatorOptions {
+    /**
+     * The look the stage starts on. Left out, it starts on the first gender offered with every part left to the figure -- the player's own look on the man, the game's default on the woman.
+     */
+    appearance: Appearance | undefined;
+
+    /**
+     * Which bodies the player may choose between; `both` (the default) lets them switch.
+     */
+    genders: "male" | "female" | "both" | undefined;
+
+    /**
+     * The panel's heading, at most 64 bytes. Defaults to `Character`.
+     */
+    title: string | undefined;
+  }
+
+  /**
+   * The game's own character stage, for the local player to choose how they look.
+   * 
+   * Opens the pause screen on its character page, hides the page's own panels and stands a panel of tabs -- body, face, hair, beard -- beside a figure the player dresses and turns. The keys are listed on the panel, named as the game names them.
+   * 
+   * Client-only and local: it changes nothing anywhere. `characterCreatorClosed` reports what the player accepted, and the resource decides what that means.
+   */
+  const CharacterCreator: {
+    /**
+     * Opens a creator, ending one already open as `replaced`. The stage goes up on the next ticks; one that cannot ends as `unavailable`.
+     * @param options What to show.
+     * @returns True. Malformed options throw.
+     */
+    open(options?: CharacterCreatorOptions): boolean;
+
+    /**
+     * Ends the open creator as `closed`.
+     * @returns False when none was open.
+     */
+    close(): boolean;
+
+    /**
+     * Whether a creator is open or going up.
+     * @returns True from `open` until its `characterCreatorClosed`.
+     */
+    isOpen(): boolean;
+  };
+
+  /**
+   * "Press [key] to ..." hints, drawn by the game's own HUD beside its own, with a handler run when the player presses the key.
+   * 
+   * A hint names one of the game's keys by its control -- `primary_action`, `jump` and the rest of `keys()` -- and never a physical key: the glyph is whatever the player has bound to that control, keyboard or pad, and follows a rebind. A press hint fires on the press; a hold hint draws the game's ring and fires once it fills.
+   * 
+   * Hints are drawn while the player is in control of their character, on foot or in the saddle, and the game takes them down in dialogue, minigames and menus. Two hints on one key stack: the newest is drawn and gets the press, and removing it brings back the one under it. A hint does not stop the game's own action on that key -- put a hint on `primary_action` and the player still interacts with whatever they look at.
+   * 
+   * Client-only and local: a hint is shown to the player at this machine. Hints go when the resource that made them stops.
+   */
+  const ActionHint: {
+    /**
+     * Puts a hint up. It is drawn from the next frame the player is in control.
+     * @param options `key` is one of `keys()`. `text` is what the HUD writes beside the key, as written, at most 256 bytes. `mode` is "press" by default. `holdDuration` is how long a hold hint's ring takes to fill, 0.2 to 10 seconds, 1 by default. `enabled` false draws the hint greyed out and keeps the handler from running.
+     * @param handler Run with the hint's id each time it fires.
+     * @returns The hint's id. Throws when an option is out of range or the key is not one of `keys()`.
+     */
+    create(options: { key: string; text: string; mode?: "press" | "hold"; holdDuration?: number; enabled?: boolean }, handler: ActionHintHandler): number;
+
+    /**
+     * Rewrites a hint's text in place.
+     * @param hint An id from `create`.
+     * @param text The new text, as written, at most 256 bytes.
+     * @returns False when the hint is gone or the text is too long.
+     */
+    setText(hint: number, text: string): boolean;
+
+    /**
+     * Greys a hint out, or brings it back.
+     * @param hint An id from `create`.
+     * @param enabled False greys the hint out and its handler stops running.
+     * @returns False when the hint is gone.
+     */
+    setEnabled(hint: number, enabled: boolean): boolean;
+
+    /**
+     * Takes a hint down for good.
+     * @param hint An id from `create`.
+     * @returns False when it was already gone.
+     */
+    remove(hint: number): boolean;
+
+    /**
+     * The controls a hint can be put on.
+     * @returns Control names, in a fixed order.
+     */
+    keys(): string[];
+  };
+
   /**
    * Mutable two-dimensional vector.
    */

package/generated/server-api.d.ts

@@ -194,6 +194,16 @@ declare global {
      */
     playerPickpocketCaught: [thief: Player, victim: Player];
 
+    /**
+     * 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.
      */
@@ -265,7 +275,7 @@ declare global {
     cartEntering: [cart: Cart, player: Player, seat: string];
 
     /**
-     * Dispatched after a player is given a seat. `seat` is `driver` or `back`; a driver's client runs the cart from here on.
+     * Dispatched after a player is given a seat, named as in `cart.seats`; the `driver` seat's client runs the cart from here on.
      */
     cartEnter: [cart: Cart, player: Player | null, seat: string];
 
@@ -315,7 +325,7 @@ declare global {
     npcDestroy: [npc: Npc];
 
     /**
-     * Dispatched when an NPC finishes what it was told to do. `status` is `reached` when it arrived, `blocked` when it could not make progress, or `failed` when the order could not be carried out at all. A patrol steps on this event, so a handler that re-orders the NPC here replaces the route rather than racing it.
+     * Dispatched once when an NPC finishes what it was told to do. `status` is `reached` when it arrived, `blocked` when it could not make progress, or `failed` when the order could not be carried out at all, or when a patrol gives up. Server-planned intermediate corners do not raise this event, and neither does a change of simulator: a finished order is not reported twice. A follow, which never finishes, raises `reached` the first time it catches up and again only after a change of simulator. A patrol steps on this event, so a handler that re-orders the NPC here replaces the route rather than racing it.
      */
     npcIntentDone: [npc: Npc, status: string];
 
@@ -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];
 
@@ -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;
 
@@ -2145,6 +2155,46 @@ declare global {
     amount: number;
   }
 
+  /**
+   * 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.
    */
@@ -2860,6 +2910,16 @@ declare global {
      */
     readonly pace: string;
 
+    /**
+     * The names of this cart's seats, the reins first: six on a wagon, three on the two-wheeler.
+     */
+    readonly seats: string[];
+
+    /**
+     * The fastest the driver may take it urged on (the trot key held), in metres a second, 0 to 15; 7 by default. Unurged the team trots at 3.6 or this, whichever is less. A value outside the range is ignored.
+     */
+    maxSpeed: number;
+
     /**
      * Formats this cart handle for logging and debugging.
      * @returns The cart ID, its blueprint, its driver and its pace.
@@ -2874,7 +2934,7 @@ declare global {
     /**
      * Puts a player in a seat. They are taken out of any cart they were in, their own game walks them to the seat and climbs in, and `cartEnter` follows; the driver's client runs the cart from then on. `cartEntering` handlers are asked first.
      * @param player The player to seat.
-     * @param seat `driver` (the bench, holding the reins) or `back` (the right rail): the two seats the game animates a player in.
+     * @param seat One of the cart's `seats`. A wagon has `driver` (the reins, on the bench's left), `bench` (beside them), `rightBack`, `leftBack`, `rightFront` and `leftFront` (on the rails); the two-wheeler `driver`, `rightBack` and `leftBack`.
      * @returns Whether the player was seated: false for a taken seat, a player that is not connected, or a handler's refusal.
      */
     putPlayer(player: Player, seat: string): boolean;
@@ -2888,7 +2948,7 @@ declare global {
 
     /**
      * Who sits in a seat.
-     * @param seat `driver` or `back`.
+     * @param seat One of the cart's `seats`.
      * @returns The player in it, or null when it is empty.
      */
     getOccupant(seat: string): Player | null;
@@ -2896,12 +2956,12 @@ declare global {
     /**
      * Where a player sits in this cart.
      * @param player The player to look for.
-     * @returns `driver` or `back`, or null when they are not in it.
+     * @returns The seat's name, one of `seats`, or null when they are not in it.
      */
     seatOf(player: Player): string | null;
 
     /**
-     * Moves the cart outright, with everyone in it: every client rebuilds it on a new short road at the new pose, and a driver carries on from there.
+     * Moves the cart outright, standing, with everyone in it; a driver carries on from there.
      * @param position Where the cart's front axle stands.
      * @param rotation Which way it faces; omitted keeps its heading.
      * @returns False for a pose that is not finite.
@@ -2909,7 +2969,7 @@ declare global {
     teleport(position: Vector3, rotation?: Vector3 | Quaternion): boolean;
 
     /**
-     * Spawns and replicates a cart or wagon from the game's own prefabs, with its horses already in the shafts. It stands on a short straight road until somebody takes the reins.
+     * Spawns and replicates a cart or wagon from the game's own prefabs, with its horses already in the shafts. It stands where it was put until somebody takes the reins.
      * @param blueprint Which of the game's cart prefabs to build; omitted builds `wagon_b_covered`. `Cart.blueprints()` lists them.
      * @param position Where the cart's front axle stands; omitted components default to zero.
      * @param rotation Which way it faces: a Quaternion, or a Vector3 of Euler angles in degrees.
@@ -3507,9 +3567,7 @@ declare global {
     lootable: boolean;
 
     /**
-     * How the simulating client moves this body.
-     * 
-     * `kinematic` (the default) advances the pose and lets every client animate it -- predictable, and the same path every remote player's body already runs on. `native` hands the destination to the game's own movement controller, which walks the body with real footfalls and real turns but will walk into whatever the engine does not route around. Pick `native` for bodies in the open and `kinematic` for anything on an authored route.
+     * How the client simulator moves the body. `native` (default) uses the game's movement controller and walk animations. `kinematic` moves the body directly without walk animation. Neither finds a way around anything: the game's movement controller steers straight at the point it is given. Routes come from server pathfinding, which hands either mode mesh corners -- see `moveTo`.
      */
     locomotion: string;
 
@@ -3519,7 +3577,7 @@ declare global {
     readonly intent: string;
 
     /**
-     * What the simulating client last reported about the current intent: `idle`, `running`, `reached`, `blocked` or `failed`. A dormant NPC that is walking an authored route reports through the server's own dead reckoning instead, so a patrol keeps stepping with nobody there to watch it.
+     * What has become of the current order: `idle`, `running`, `reached`, `blocked` or `failed`. A move reads `running` from the moment it is given -- while its route is planned and while it walks the route's corners -- until it ends, and then the outcome `npcIntentDone` announced, which stays until the next order. A follow reads `reached` while it is within its radius. Dormant moves in `auto` or `server` mode are carried out and decided by the server; dormant `game` moves wait for a client simulator.
      */
     readonly status: string;
 
@@ -3603,23 +3661,31 @@ declare global {
     hold(): void;
 
     /**
-     * Sends the NPC somewhere and raises `npcIntentDone` when it arrives, cannot get there, or gives up. Cancels any patrol.
+     * Moves to `position`, cancels any patrol, and emits `npcIntentDone` once when the move ends.
+     * 
+     * The game's own movement steers a body straight at the point it is given and finds no way around anything, so routes come from the server's navigation mesh. The server plans the route and hands the simulating client one corner at a time, the next before the body reaches the last, so it walks through bends without stopping; a dormant NPC is walked along the same route by the server. Routes only use doorways whose door stands open.
+     * 
+     * `auto` (the default) routes on the server whenever a mesh is loaded. Without one, a simulating client steers straight at `position` and a dormant NPC moves in a straight line. `game` steers straight at `position` and waits while dormant; if the body reports `blocked` and a mesh is loaded, the server tries a route before emitting `npcIntentDone`. `server` always routes on the server and throws without a loaded mesh, preserving the previous order.
+     * 
+     * A missing or partial route ends with `blocked`, and a blocked route is not retried. Route plans are queued and spread over ticks; the move reads `running` meanwhile.
      * @param position Where to walk to.
-     * @param options `speed` is the pace to walk at; `radius` is how close counts as arrived, in metres.
-     * @returns True when the order went out.
+     * @param options `speed` defaults to `walk`; `radius` is the arrival distance in metres (default 1.5). `pathfinding` defaults to `auto`.
+     * @returns True when the order went out; false for an invalid NPC or destination.
      */
-    moveTo(position: Vector3 | Partial<Vector3>, options?: { speed?: 'walk' | 'jog' | 'run'; radius?: number }): boolean;
+    moveTo(position: Vector3 | Partial<Vector3>, options?: { speed?: 'walk' | 'jog' | 'run'; radius?: number; pathfinding?: 'auto' | 'game' | 'server' }): boolean;
 
     /**
-     * Walks a route, one waypoint at a time. The route stays on the server and only the waypoint being walked to is ever replicated, so a player who joins mid-patrol sees one move rather than a plan to catch up with -- and a patrol nobody is near enough to simulate keeps advancing on the server's own reckoning.
+     * Walks the waypoints in order. The server stores the route and replicates the current target. `npcIntentDone` fires once per leg, after its final mesh corner or a movement failure.
+     * 
+     * A leg that ends `blocked` or `failed` is skipped after at least 2 seconds. When every leg of a lap has failed in a row, the patrol is abandoned and that last leg reports `failed` instead.
      * @param points The waypoints, in order.
-     * @param options `loop` walks the route forever (the default); `waitSeconds` is how long to stand at each waypoint; `speed` is the pace.
-     * @returns True when the route was accepted; false for an empty route or a point that is not finite.
+     * @param options `loop` defaults to true; `waitSeconds` is the wait at each waypoint, 0 to 3600 (default 0); `speed` defaults to `walk`. `pathfinding` uses the modes documented for `moveTo` and applies to every leg.
+     * @returns True when the route was accepted; false for an empty route, more than 256 waypoints, a waypoint that is not finite or lies outside the world, or a `waitSeconds` that is not a number. Throws if server mode has no loaded mesh, leaving the previous order intact.
      */
-    patrol(points: (Vector3 | Partial<Vector3>)[], options?: { speed?: 'walk' | 'jog' | 'run'; loop?: boolean; waitSeconds?: number }): boolean;
+    patrol(points: (Vector3 | Partial<Vector3>)[], options?: { speed?: 'walk' | 'jog' | 'run'; loop?: boolean; waitSeconds?: number; pathfinding?: 'auto' | 'game' | 'server' }): boolean;
 
     /**
-     * Keeps the NPC near somebody as they move.
+     * Keeps the NPC near somebody as they move, steering straight at them. `npcIntentDone` reports `reached` the first time it catches up, and the follow carries on. If the body reports `blocked`, a loaded mesh lets the server route to the target's current position before reporting it. After recovery it resumes following the moving target.
      * @param target Who to follow, as a handle or a network ID.
      * @param options `radius` is how close it tries to stay, in metres; `speed` is the pace.
      * @returns True when the order went out.
@@ -3627,7 +3693,7 @@ declare global {
     follow(target: Player | Npc | number, options?: { speed?: 'walk' | 'jog' | 'run'; radius?: number }): boolean;
 
     /**
-     * Sends the NPC away from a place. The one intent that picks its own direction.
+     * Sends the NPC straight away from a place until the requested distance separates them. If the body reports `blocked`, a loaded mesh lets the server try a route to a point past that distance, on the ground at the NPC's own height, before reporting it.
      * @param from What to run away from.
      * @param options `radius` is how far away is far enough; `speed` is the pace, `run` by default.
      * @returns True when the order went out.
@@ -4022,6 +4088,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.
    */
@@ -5109,6 +5229,129 @@ declare global {
     entities: WorldNearbyEntity[];
   }
 
+  /**
+   * A walk across the mesh.
+   */
+  interface NavigationPath {
+    /**
+     * The corners to walk through, first the point on the mesh nearest `from`. Straight lines between them stay on the mesh.
+     */
+    points: Vector3[];
+
+    /**
+     * Whether it reaches `to`. False when `to` cannot be reached, and the path then ends at the nearest point the mesh allows.
+     */
+    complete: boolean;
+
+    /**
+     * Its length in metres.
+     */
+    length: number;
+  }
+
+  /**
+   * How far a straight walk across the mesh gets.
+   */
+  interface NavigationRay {
+    /**
+     * Whether the edge of the mesh -- a wall, a drop, a locked door -- stops it before `to`.
+     */
+    hit: boolean;
+
+    /**
+     * Where it stops: the edge, or the point on the mesh under `to`.
+     */
+    point: Vector3;
+  }
+
+  /**
+   * Queries the level's navigation mesh on the server. The mesh includes walkable floors, bridges and stairs.
+   * 
+   * Copy the game's `Data/Levels/<level>/recast.pak` to the server's `files/<level>/` directory. The server searches `files/` recursively at startup. An optional `mod.navmesh` in `server.json` takes priority and can name a game install, level folder or pak file. The game data must be supplied separately. Without a mesh, `ready` is false and geometry queries return null or false. Points are world-space metres, Z up. Every query takes an optional options object. `searchRadius` and `searchHeight` limit how far a point may be from the mesh, across the ground and up or down: 2 metres by default, up to 64, and 4 by default, up to 128. Keep `searchHeight` under a storey's height, or a point on one floor snaps to the floor above. `doors` picks which doors a query walks through: `unlocked`, the default, is how an NPC treats a door -- open or shut, it goes through unless the door is locked; `open` only through doors that stand open; `any` ignores locks; `none` treats every doorway as a wall. A door's state is read off the door in the global world. A field given with the wrong type or out of range throws.
+   */
+  const Navigation: {
+    /**
+     * Whether a mesh loaded from `mod.navmesh` or the server's `files/` directory. False when no usable copy is found; the server log gives the reason.
+     */
+    readonly ready: boolean;
+
+    /**
+     * Available overlay names, sorted. Overlays contain replacement navigation data for quest states. Enabling one replaces the covered part of the mesh. Empty without a mesh.
+     */
+    readonly overlays: string[];
+
+    /**
+     * Enabled overlays in activation order. Initially empty; the level starts with its base mesh.
+     */
+    readonly activeOverlays: string[];
+
+    /**
+     * Snaps a point to the nearest walkable surface.
+     * @param point The point to snap; omitted components default to zero.
+     * @param options How far to look, and which doors count.
+     * @returns The nearest point within the search limits, or null when none is found or no mesh is loaded.
+     */
+    closestPoint(point: Vector3 | Partial<Vector3>, options?: { searchRadius?: number; searchHeight?: number; doors?: "unlocked" | "open" | "any" | "none" }): Vector3 | null;
+
+    /**
+     * Returns the height of the nearest walkable surface, including upper floors, bridges and stairs.
+     * @param point The point to measure; omitted components default to zero. Its z estimates the floor height and selects the storey.
+     * @param options How far to look.
+     * @returns The height in metres, or null when none is found or no mesh is loaded.
+     */
+    floorAt(point: Vector3 | Partial<Vector3>, options?: { searchRadius?: number; searchHeight?: number; doors?: "unlocked" | "open" | "any" | "none" }): number | null;
+
+    /**
+     * Plans a path around obstacles on the mesh. Plan when a destination changes; avoid recalculating every NPC's path each tick.
+     * @param from Where the walk starts; omitted components default to zero.
+     * @param to Where it should end; omitted components default to zero.
+     * @param options How far to look for each end, and which doors to walk through.
+     * @returns The path, or null when an endpoint cannot be found, the query fails or no mesh is loaded. A partial path has `complete: false`.
+     */
+    findPath(from: Vector3 | Partial<Vector3>, to: Vector3 | Partial<Vector3>, options?: { searchRadius?: number; searchHeight?: number; doors?: "unlocked" | "open" | "any" | "none" }): NavigationPath | null;
+
+    /**
+     * Checks reachability by calling `findPath`.
+     * @param from Where the walk starts; omitted components default to zero.
+     * @param to Where it should end; omitted components default to zero.
+     * @param options How far to look for each end, and which doors to walk through.
+     * @returns True when a complete path exists; false otherwise, including when no mesh is loaded.
+     */
+    canReach(from: Vector3 | Partial<Vector3>, to: Vector3 | Partial<Vector3>, options?: { searchRadius?: number; searchHeight?: number; doors?: "unlocked" | "open" | "any" | "none" }): boolean;
+
+    /**
+     * Checks a straight line across the mesh and reports where it stops.
+     * @param from Where the walk starts; omitted components default to zero.
+     * @param to Where it heads; only its x and y are used, the walk follows the surface.
+     * @param options How far to look for `from`, and which doors let the walk through.
+     * @returns The result, or null when `from` is off the mesh, the query fails or no mesh is loaded.
+     */
+    raycast(from: Vector3 | Partial<Vector3>, to: Vector3 | Partial<Vector3>, options?: { searchRadius?: number; searchHeight?: number; doors?: "unlocked" | "open" | "any" | "none" }): NavigationRay | null;
+
+    /**
+     * Returns a random walkable point reachable from `center` and no further from it across the ground than `radius`. A point drawn outside the circle is drawn again, a bounded number of times. Without a centre, samples the whole level, choosing each tile with equal probability.
+     * @param center The point to scatter around; it has to be on the mesh, and omitted components default to zero. Omitted entirely, the point can be anywhere on the level's mesh; pass `undefined` for it and for `radius` to give options.
+     * @param radius How far from `center`, in metres, up to 512. Required with a centre.
+     * @param options How far to look for `center`, and which doors the point may lie behind.
+     * @returns The point, or null when `center` is off the mesh, no draw lands within `radius`, the query fails or no mesh is loaded.
+     */
+    randomPoint(center?: Vector3 | Partial<Vector3>, radius?: number, options?: { searchRadius?: number; searchHeight?: number; doors?: "unlocked" | "open" | "any" | "none" }): Vector3 | null;
+
+    /**
+     * Enables an overlay. Where overlays overlap, the last enabled takes precedence. Subsequent queries use the updated mesh.
+     * @param name An entry of `overlays`.
+     * @returns False for a name the level does not ship, one already enabled, one whose tiles cannot be read or loaded (the server log says why), or without a mesh.
+     */
+    enableOverlay(name: string): boolean;
+
+    /**
+     * Disables an overlay, restoring the previous enabled overlay or the base mesh in that area.
+     * @param name An entry of `activeOverlays`.
+     * @returns False for a name that is not enabled, or when part of the area could not be restored (the server log says why); the overlay is disabled either way.
+     */
+    disableOverlay(name: string): boolean;
+  };
+
   /**
    * What the game's own tables say about one status effect.
    */

package/package.json

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

package/shared.d.ts

@@ -10,6 +10,9 @@
  * inline `(...) => ...`, so a handler parameter has nowhere else it can be spelled.
  */
 
+/** Handler for an `ActionHint`, given the id `ActionHint.create` returned for it. */
+export type ActionHintHandler = (hint: number) => void;
+
 /** Handler for an event raised through the framework event bus. A returned promise is awaited, so a handler may be async. */
 export type EventHandler = (...args: unknown[]) => unknown | Promise<unknown>;