@kingdomsconnected/types 1.5.7 → 1.6.0

package/generated/client-api.d.ts

@@ -80,7 +80,7 @@ declare global {
     /**
      * Dispatched when the flight starts and when it ends, on this machine only. Handler promises are not awaited.
      * 
-     * `reason` is `script` on the way in. On the way out it is `script` for a resource ending it, `mapEditor` for F7 taking the one camera, `viewLost` for the level going away underneath the camera's anchor, and `sessionOver` for the session ending.
+     * `reason` is `script` on the way in. On the way out it is `script` for a resource ending it, `mapEditor` for the map editor taking the one camera, `viewLost` for the level going away underneath the camera's anchor, and `sessionOver` for the session ending.
      */
     noclipChanged: [active: boolean, reason: "script" | "mapEditor" | "viewLost" | "sessionOver"];
 
@@ -1177,6 +1177,15 @@ declare global {
      */
     playOnEntity(trigger: string, entityId: number): boolean;
 
+    /**
+     * Plays a sound file on an entity, positioned and attenuated like the game's own spoken lines and under the same volume settings. A file streamed by the server plays exactly like one the game ships. An entity takes one file per 0.1 seconds.
+     * @param file Game-root path of an `.ogg`, with or without the extension -- `sounds/kcdc/<resource>/line` for one a server streams.
+     * @param entityId Engine entity to play it on -- what `Player.entityId` reports.
+     * @param purpose Which of the game's voice host events carries it: `inner`, `10`, `20`, `35`, `50`, `100`, `200` (a bark heard up to that many metres), `sfp_dialog`, `sfp_cutscene` or `sfp_music`. Defaults to `50`.
+     * @returns True when the entity was there and took it.
+     */
+    playFile(file: string, entityId: number, purpose?: string): boolean;
+
     /**
      * Stops every instance of one trigger on the entity. Triggers that have already finished are not an error.
      * @param trigger Name of the trigger to stop.
@@ -1218,6 +1227,18 @@ declare global {
     hasTrigger(trigger: string): boolean;
   };
 
+  /**
+   * What the server streams, seen from this machine. Models, materials, textures, sounds and particle libraries a server streams load by path like the game's own -- `objects/kcdc/<resource>/chair.cgf` works wherever a model path does -- so nothing here is needed to use them. Clips play through the server's `playClip`.
+   */
+  const Assets: {
+    /**
+     * Whether the session's streamed assets carry a file at this path. Only new assets count; a replaced stock file is the game's own path.
+     * @param path Path inside the game's data, as a server streams it -- `objects/kcdc/<resource>/chair.cgf`.
+     * @returns True when a mounted stream-lane pak carries it.
+     */
+    has(path: string): boolean;
+  };
+
   /**
    * The game's own particle effects, played on this machine. An effect is a name out of the game's particle libraries -- `WH_Particels.fires.candle`, `collisions.combat.sword_sword`, `cinematics.dust.dust_army_a` -- and `list` is the whole vocabulary. Nothing here is replicated: an effect everyone should see is one the server tells every client to play with `Vfx.burst`, or one the server places with `Vfx.spawn`, which the interest grid then streams to whoever is near it. Almost every effect the game ships is continuous, which means it never ends on its own -- so everything started here is given a duration, and one that is not stopped first is stopped when the session ends.
    */
@@ -1419,15 +1440,35 @@ declare global {
     distance: number;
 
     /**
-     * The surface type's own name, spelled the way the game's tables spell it -- `mat_wood`, `mat_stone`, `mat_water`. This is what a trace is worth over a position: it says what was hit, not just where. Empty only before the material tables are up.
+     * The surface type's own name, spelled the way the game's tables spell it in `Libs/MaterialEffects/SurfaceTypes.xml` -- `mat_wood`, `mat_rock`, `mat_soil`, `mat_water`. It says what the thing is made of, which is how footsteps and blows sound, not what it is: a plank wall is `mat_wood` as much as a trunk is, so tell a tree by `category`. Among the 74 the game defines: `mat_wood`, `mat_wood_soft`, `mat_vegetation`, `mat_bushes`, `mat_rock`, `mat_rock_unwalk`, `mat_rock_horse_ignore`, `mat_stairs_stone`, `mat_gravel`, `mat_soil`, `mat_mud`, `mat_grass`, `mat_road`, `mat_metal`, `mat_glass`, `mat_plaster`, `mat_thatch`, `mat_fabric`, `mat_flesh`. Empty only before the material tables are up.
      */
     surface: string;
 
     /**
-     * Whether the ground itself was hit rather than anything placed on it. Nothing lies behind the terrain, so a trace stops there.
+     * Whether the ground itself was hit rather than anything placed on it. Nothing lies behind the terrain, so a trace stops there. The same as `kind` being `terrain`.
      */
     terrain: boolean;
 
+    /**
+     * What sort of thing the ray stopped on. `entity` is anything with an `entityClass` -- doors, props, NPCs, players. `vegetation` is an instance the level paints on: trees, bushes, plants, and boulders painted the same way. `brush` is a static mesh placed one by one: walls, houses, rocks and cliffs. `static` is static geometry that is neither, or whose source the engine does not record. Trees and rocks are not entities, so for them this, `model` and `category` are what say what was hit.
+     */
+    kind: "terrain" | "entity" | "vegetation" | "brush" | "static";
+
+    /**
+     * The mesh of a vegetation instance or a brush, as the path the game loads it from -- `objects/natural/vegetation/trees/normal_trees/quercus_robur/quercus_robur_big_a.cgf`. Null for terrain, entities and `static`. A tree or a rock has no GUID, but its `model` and `position` together are the same on every client on the same level, which is what a server keeps a felled tree or a mined rock by.
+     */
+    model: string | null;
+
+    /**
+     * Which of the game's own folders of natural objects `model` comes from: `tree` for `objects/natural/vegetation/trees` -- living, dead, fallen and stumps alike, which `model` tells apart -- `bush` for its bushes, `plant` for the rest of its vegetation (grass, ferns, mushrooms, branches), and `rock` for `objects/natural/rocks` and `objects/natural/stones`. Null for anything else, man-made included.
+     */
+    category: "tree" | "bush" | "plant" | "rock" | null;
+
+    /**
+     * The material drawn where the ray met it, as the path the material manager keys it by, the sub-material when the mesh has several -- a trunk's bark rather than the tree's whole material. Null for terrain and when nothing names one.
+     */
+    material: string | null;
+
     /**
      * The level's own identity for what was hit, as sixteen lowercase hex digits -- the same on every machine, and what `Door.find` and the other GUID lookups take. Null for terrain, for static geometry and for anything the session spawned, none of which the level names.
      */
@@ -1719,7 +1760,7 @@ declare global {
    * 
    * Client-only, and nothing here is an order another machine takes. It is not invisible to the session either: in `body` mode the thing being flown is the entity this client replicates, so the other players watch the flier go. In `camera` mode the body never moves.
    * 
-   * The game's controls are held for as long as the flight lasts, whichever side is driving. F7's map editor flies the same one camera: a flight in progress ends when the editor opens, and `enable` refuses while it is open.
+   * The game's controls are held for as long as the flight lasts, whichever side is driving. The map editor (`MapEditor`) flies the same one camera: a flight in progress ends when the editor opens, and `enable` refuses while it is open.
    */
   const NoClip: {
     /**
@@ -1729,7 +1770,7 @@ declare global {
      * `input` is whether this machine's keyboard and mouse fly the camera -- on the keys the game's own photo mode is bound to in the controls menu (forward, back, left, right, jump to rise, crouch to sink, fast movement to boost), read through the active keyboard layout so AZERTY and the like work as the game does; Alt to crawl, mouse to turn. On by default; off, drive it with `move`.
      * 
      * `speed` is metres a second at rest, 0.05 to 400 and 12 by default. `fov` is the vertical field of view in degrees, up to 140; omitted, the view keeps the game's.
-     * @returns `enabled` when the flight started. `alreadyActive` when one was already running -- the options are not re-applied. `noCamera` when there is no level to spawn the camera's anchor into. `cameraBusy` when F7's map editor holds the camera.
+     * @returns `enabled` when the flight started. `alreadyActive` when one was already running -- the options are not re-applied. `noCamera` when there is no level to spawn the camera's anchor into. `cameraBusy` when the map editor holds the camera.
      */
     enable(options?: { mode?: "body" | "camera"; input?: boolean; speed?: number; fov?: number }): "enabled" | "alreadyActive" | "noCamera" | "cameraBusy";
 
@@ -1965,6 +2006,333 @@ declare global {
     isThirdPerson(): boolean;
   };
 
+  /**
+   * A position or offset in metres. Accepts plain objects and Vector3 instances.
+   */
+  interface GizmoPoint {
+    /**
+     * X coordinate.
+     */
+    x: number;
+
+    /**
+     * Y coordinate.
+     */
+    y: number;
+
+    /**
+     * Z coordinate.
+     */
+    z: number;
+  }
+
+  /**
+   * Appearance and lifetime of a client debug drawing.
+   */
+  interface GizmoStyle {
+    /**
+     * Unsigned 0xAARRGGBB color. Defaults to 0xFF6EE678 (opaque green).
+     */
+    color?: number | undefined;
+
+    /**
+     * Line width in pixels, 0.5 to 8. Defaults to 1.5; polygon vertical edges use 60% of this width.
+     */
+    width?: number | undefined;
+
+    /**
+     * Defaults to true: scene geometry occludes the drawing. Set false to show through walls. Drawings never write scene depth.
+     */
+    depthTest?: boolean | undefined;
+
+    /**
+     * Unsigned 0xAARRGGBB fill color. Defaults to transparent (outline only). Supports boxes, spheres, circles, cones, cylinders, capsules, arrow heads and meshes. Throws for lines, polylines, grids, axes and polygon areas, which have no faces; fill a polygon with explicit mesh triangles.
+     */
+    fillColor?: number | undefined;
+
+    /**
+     * Integer lifetime from 0 to 3600000 milliseconds. Zero (default) persists until removed. Replacing the drawing restarts its lifetime.
+     */
+    durationMs?: number | undefined;
+  }
+
+  /**
+   * Geometry from an Area.toJSON() or World Builder area export. Extra fields are ignored; this draws debug geometry and creates no trigger.
+   */
+  interface GizmoArea {
+    /**
+     * Which area geometry to draw.
+     */
+    type: 'box' | 'sphere' | 'shape';
+
+    /**
+     * World origin in metres; defaults to zero.
+     */
+    position?: GizmoPoint | undefined;
+
+    /**
+     * Local-to-world quaternion, normalized on input; defaults to identity. Plain {x,y,z,w} objects work.
+     */
+    rotation?: { x: number; y: number; z: number; w: number } | undefined;
+
+    /**
+     * Box minimum in local space; defaults to {-1,-1,-1}. Each component must be less than max.
+     */
+    min?: GizmoPoint | undefined;
+
+    /**
+     * Box maximum in local space; defaults to {1,1,1}.
+     */
+    max?: GizmoPoint | undefined;
+
+    /**
+     * Required for spheres: radius in metres, greater than zero and less than 16384.
+     */
+    radius?: number | undefined;
+
+    /**
+     * Required for shapes: 3 to 256 local points, forming a closed polygon.
+     */
+    points?: GizmoPoint[] | undefined;
+
+    /**
+     * Shape height above its lowest transformed point, 0 to less than 16384 metres. Zero (default) draws one ring at the points' own heights.
+     */
+    height?: number | undefined;
+  }
+
+  /**
+   * Client debug line geometry.
+   */
+  interface GizmoLine {
+    /**
+     * Primitive kind.
+     */
+    type: 'line';
+
+    /**
+     * World start.
+     */
+    from: GizmoPoint;
+
+    /**
+     * World end.
+     */
+    to: GizmoPoint;
+  }
+
+  /**
+   * Client debug arrow geometry.
+   */
+  interface GizmoArrow {
+    /**
+     * Primitive kind.
+     */
+    type: 'arrow';
+
+    /**
+     * World start.
+     */
+    from: GizmoPoint;
+
+    /**
+     * World tip.
+     */
+    to: GizmoPoint;
+
+    /**
+     * Head length in metres, greater than zero and no longer than the arrow. Defaults to the smaller of 0.5 and a quarter of the arrow length.
+     */
+    headLength?: number | undefined;
+  }
+
+  /**
+   * Client debug capsule/cone/cylinder geometry.
+   */
+  interface GizmoRoundVolume {
+    /**
+     * Primitive kind.
+     */
+    type: 'capsule' | 'cone' | 'cylinder';
+
+    /**
+     * Capsule lower hemisphere center, or cone/cylinder base center.
+     */
+    from: GizmoPoint;
+
+    /**
+     * Capsule upper hemisphere center, cone tip or cylinder top center. Capsule endpoints may coincide for a sphere.
+     */
+    to: GizmoPoint;
+
+    /**
+     * Radius in metres, 0.001 to 16384.
+     */
+    radius: number;
+
+    /**
+     * Integer radial segments, 8 to 64; default 24.
+     */
+    segments?: number | undefined;
+  }
+
+  /**
+   * Client debug circle geometry.
+   */
+  interface GizmoCircle {
+    /**
+     * Primitive kind.
+     */
+    type: 'circle';
+
+    /**
+     * World center.
+     */
+    position: GizmoPoint;
+
+    /**
+     * Non-zero plane normal; default {x:0,y:0,z:1}.
+     */
+    normal?: GizmoPoint | undefined;
+
+    /**
+     * Radius in metres, 0.001 to 16384.
+     */
+    radius: number;
+
+    /**
+     * Integer radial segments, 8 to 64; default 24.
+     */
+    segments?: number | undefined;
+  }
+
+  /**
+   * Client debug grid geometry.
+   */
+  interface GizmoGrid {
+    /**
+     * Primitive kind.
+     */
+    type: 'grid';
+
+    /**
+     * World center.
+     */
+    position: GizmoPoint;
+
+    /**
+     * Non-zero plane normal; default {x:0,y:0,z:1}.
+     */
+    normal?: GizmoPoint | undefined;
+
+    /**
+     * Square side length in metres, 0.001 to 16384; default 10.
+     */
+    size?: number | undefined;
+
+    /**
+     * Integer subdivisions on each side, 1 to 64; default 10.
+     */
+    divisions?: number | undefined;
+  }
+
+  /**
+   * Client debug axes geometry.
+   */
+  interface GizmoAxes {
+    /**
+     * Primitive kind.
+     */
+    type: 'axes';
+
+    /**
+     * World origin.
+     */
+    position: GizmoPoint;
+
+    /**
+     * Local-to-world quaternion, normalized on input; default identity.
+     */
+    rotation?: { x: number; y: number; z: number; w: number } | undefined;
+
+    /**
+     * Axis length in metres, 0.001 to 16384; default 1. X is red, Y green and Z blue; these fixed colors override style.color.
+     */
+    size?: number | undefined;
+  }
+
+  /**
+   * Client debug polyline geometry.
+   */
+  interface GizmoPolyline {
+    /**
+     * Primitive kind.
+     */
+    type: 'polyline';
+
+    /**
+     * 2 to 256 world positions.
+     */
+    points: GizmoPoint[];
+
+    /**
+     * Join last to first; default false.
+     */
+    closed?: boolean | undefined;
+  }
+
+  /**
+   * Client debug mesh geometry.
+   */
+  interface GizmoMesh {
+    /**
+     * Primitive kind.
+     */
+    type: 'mesh';
+
+    /**
+     * 3 to 1024 world positions.
+     */
+    points: GizmoPoint[];
+
+    /**
+     * 3 to 3072 integer vertex indices in triangle triples, each from 0 to points.length - 1. Both triangle sides render.
+     */
+    indices: number[];
+
+    /**
+     * Draw triangle edges with style.color and width; default true. Set fillColor to draw faces.
+     */
+    wireframe?: boolean | undefined;
+  }
+
+  /**
+   * Resource-owned native debug geometry visible only on this client, without opening World Builder. Scene depth testing is on by default; depthTest: false opts out. Stop/error, disconnect and moving to another level clear drawings; reloading a save of the same level keeps them. No replication or input capture.
+   */
+  const Gizmos: {
+    /**
+     * Creates or replaces a named primitive owned by this resource. Finite input coordinates within +/-16384 metres. IDs are 1 to 128 UTF-8 bytes. Limit: 128 IDs per resource, 16384 geometry units across resources (one per line, three per triangle). Throws on invalid input or budget overflow and preserves the previous drawing. Copies geometry and reapplies style defaults; use setTransform to move it.
+     */
+    set(id: string, primitive: GizmoArea | GizmoLine | GizmoArrow | GizmoRoundVolume | GizmoCircle | GizmoGrid | GizmoAxes | GizmoPolyline | GizmoMesh, style?: GizmoStyle): void;
+
+    /**
+     * Moves this resource's named drawing without rebuilding it: every authored point p is drawn at position + rotation * p. Author the geometry around the origin to move it as a whole. The rotation is normalized and defaults to identity. set() resets the transform to identity.
+     * @returns True if the drawing exists; false if this resource has no drawing with that ID.
+     */
+    setTransform(id: string, position: GizmoPoint, rotation?: { x: number; y: number; z: number; w: number }): boolean;
+
+    /**
+     * Removes this resource's named drawing. Throws for an invalid ID or unknown resource.
+     * @returns True if removed; false if this resource has no drawing with that ID.
+     */
+    remove(id: string): boolean;
+
+    /**
+     * Removes all drawings owned by this resource. Other resources are unaffected. Throws if the caller's resource cannot be identified.
+     */
+    clear(): void;
+  };
+
   /**
    * The box a ghost occupies, in world space.
    */
@@ -2168,6 +2536,37 @@ declare global {
     on(event: "move" | "confirm" | "rejected" | "cancel" | "end", handler: PlacementHandler<PlacementPose>): Unsubscribe;
   };
 
+  /**
+   * The world builder: a free camera, the game's mesh catalog as an asset library, a placement brush, a gizmo that moves anything, and maps saved to and loaded from files.
+   * 
+   * No key opens it. A resource decides when it does, and only on a server whose `server.json` sets `mod.map_editor` to true; anywhere else `open` refuses. While it is open it holds the one free camera, so a `NoClip` flight in progress ends and `NoClip.enable` refuses. The player can still close it from its own window.
+   */
+  const MapEditor: {
+    /**
+     * Opens the editor.
+     * @returns `opened` when it opened. `alreadyOpen` when it was open already. `disabled` when the server has not turned `mod.map_editor` on, which includes no session at all.
+     */
+    open(): "opened" | "alreadyOpen" | "disabled";
+
+    /**
+     * Closes the editor and hands the camera back. Doing nothing when it is closed is not an error.
+     * @returns Nothing.
+     */
+    close(): void;
+
+    /**
+     * Whether the editor is open at this client.
+     * @returns True while it is open.
+     */
+    isOpen(): boolean;
+
+    /**
+     * Whether the connected server lets the editor open.
+     * @returns True when its `server.json` sets `mod.map_editor` to true.
+     */
+    isEnabled(): boolean;
+  };
+
   /**
    * A screen composed inside one of the game's own Scaleform movies.
    */
@@ -2560,6 +2959,20 @@ declare global {
    * The game's own Scaleform UI, opened from script. This is the second way to draw a UI at this client, beside `Web`: a web view is a browser and lays out anything, a native screen is composed out of the game's own movies, sits inside the game's own layer stack and is navigable with a controller.
    */
   const NativeUI: {
+    /**
+     * Prevents a vanilla menu from opening or being selected through native navigation. An already-open disabled menu closes on the next client tick. Requests are idempotent and resource-owned: a menu stays disabled while any resource disables it. Restrictions clear when the resource stops or the session ends. Key bindings are unchanged. Tab labels remain in the native screen. The custom character creator can still use the player stage.
+     * @param menu The vanilla menu, including its detail pages.
+     * @param enabled False prevents opening the menu; true releases this resource's restriction. All menus are enabled by default.
+     */
+    setMenuEnabled(menu: "inventory" | "player" | "map" | "codex" | "journal" | "crafting", enabled: boolean): void;
+
+    /**
+     * Whether every resource permits this vanilla menu. Native gameplay rules may still prevent it from opening. Throws for unknown menu names.
+     * @param menu The vanilla menu to query.
+     * @returns True when no resource disables the menu.
+     */
+    isMenuEnabled(menu: "inventory" | "player" | "map" | "codex" | "journal" | "crafting"): boolean;
+
     /**
      * Opens a screen. It is composed a few frames later, when its movie reports ready -- listen for `ready` rather than drawing into it straight away.
      * @param options `library` names which of the game's movies the screen may attach exported sprites from, empty for the default. `movie` is a path inside this resource to a movie it ships, which opens a screen in that instead. `assets` are further files that movie loads, and `layer` is where it sits in the game's own stack.
@@ -2722,32 +3135,32 @@ declare global {
     /**
      * 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;
+    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;
+    type?: number | undefined;
 
     /**
      * How ornate the pages are, 1 plain to 7 embellished. Defaults to 1.
      */
-    visual: number | undefined;
+    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;
+    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;
+    texture?: string | undefined;
 
     /**
      * Pictures for the skill-book and map layouts. Inline pictures go in the page text as `<img>` instead.
      */
-    images: BookPageImage[] | undefined;
+    images?: BookPageImage[] | undefined;
   }
 
   /**
@@ -2807,17 +3220,17 @@ declare global {
     /**
      * 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;
+    appearance?: Appearance | undefined;
 
     /**
      * Which bodies the player may choose between; `both` (the default) lets them switch.
      */
-    genders: "male" | "female" | "both" | undefined;
+    genders?: "male" | "female" | "both" | undefined;
 
     /**
      * The panel's heading, at most 64 bytes. Defaults to `Character`.
      */
-    title: string | undefined;
+    title?: string | undefined;
   }
 
   /**
@@ -4204,6 +4617,13 @@ declare global {
    * Client-only, resource-owned physical key bindings exposed as the global Key.
    */
   const Key: {
+    /**
+     * Returns the current layout's label for a physical key, even while UI owns input. Query again when refreshing prompts. Throws for unknown keys or non-string arguments.
+     * @param key Case-insensitive physical key name, using the same names as bind.
+     * @returns Uppercase printable text, or an English name such as Enter or Mouse 1. Falls back to the uppercase canonical key name when translation is unavailable.
+     */
+    getLabel(key: string): string;
+
     /**
      * Binds a resource-owned handler that fires while the game has foreground input and no UI is capturing it.
      * @param key Case-insensitive supported keyboard or mouse key name.