@kingdomsconnected/types 1.5.6 → 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.
      */
@@ -2795,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

@@ -275,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];
 
@@ -325,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];
 
@@ -2910,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.
@@ -2924,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;
@@ -2938,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;
@@ -2946,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.
@@ -2959,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.
@@ -3557,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;
 
@@ -3569,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;
 
@@ -3653,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.
@@ -3677,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.
@@ -5213,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.6",
+  "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>;