@kingdomsconnected/types 1.6.0 → 1.6.2

package/generated/client-api.d.ts

@@ -37,6 +37,11 @@ declare global {
      */
     progressionPerkRefused: [perk: string, reason: "points" | "level" | "parent" | "exclusive" | "blocked" | "script" | "owned" | "hidden"];
 
+    /**
+     * Dispatched when a monologue line of the local character -- a photo-mode comment, the sharpening remark -- was kept silent and unsubtitled. `text` is localized; `textKey` is its localization key. Not raised while `Hud.setMonologueEnabled(true)` has released it. Handler promises are not awaited.
+     */
+    monologueSuppressed: [text: string, textKey: string];
+
     /**
      * Dispatched when this player starts or stops following a server quest in the game's journal, whichever way it happened: the track button, the game auto-tracking a quest that turns active, or the untrack that follows finishing or failing one. Local to this machine and raised before the server is told; the server raises its own `questTrackingChanged` when the report arrives. Repeats are filtered, so it only fires on an actual change. Handler promises are not awaited.
      */
@@ -94,6 +99,16 @@ declare global {
      */
     bookClosed: [bookId: number, reason: "player" | "script" | "failed" | "sessionOver"];
 
+    /**
+     * The local native follow action has entered. A successful start request may still fail before this event.
+     */
+    followStarted: [target: FollowTarget];
+
+    /**
+     * A queued or active scripted follow ended on this client.
+     */
+    followStopped: [target: FollowTarget, reason: "script" | "input" | "targetLost" | "mountChanged" | "teleported" | "unavailable" | "interrupted" | "failed" | "resourceStopped" | "sessionEnded" | "worldChanged"];
+
     /**
      * 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.
      */
@@ -178,6 +193,161 @@ declare global {
   /** Names of native events available in this scripting environment. */
   type EventName = keyof EventMap;
 
+  /**
+   * Writable player stats, in native units. Use getStat and the server's setStat.
+   */
+  const PlayerStat: {
+    /**
+     * Current health, in native units. Zero can kill.
+     */
+    readonly Health: "health";
+
+    /**
+     * Current stamina; the game continues spending and regenerating it.
+     */
+    readonly Stamina: "stamina";
+
+    /**
+     * Current energy reserve; higher means better rested.
+     */
+    readonly Exhaust: "exhaust";
+
+    /**
+     * Current nourishment; higher means better fed.
+     */
+    readonly Hunger: "hunger";
+  };
+
+  /**
+   * Read-only computed player stats. Use getDerivedStat; these values cannot be passed to setStat.
+   */
+  const DerivedPlayerStat: {
+    /**
+     * Total bleeding strength.
+     */
+    readonly Bleeding: "bleeding";
+
+    /**
+     * Sleepiness; above zero means asleep.
+     */
+    readonly Sleeping: "sleeping";
+
+    /**
+     * Consciousness; zero means knocked out.
+     */
+    readonly Consciousness: "consciousness";
+
+    /**
+     * Native drunkenness value.
+     */
+    readonly Drunkenness: "drunkenness";
+
+    /**
+     * Native poisoning value; not every named poison changes this value.
+     */
+    readonly Poisoning: "poisoning";
+
+    /**
+     * Effective charisma.
+     */
+    readonly Charisma: "charisma";
+
+    /**
+     * Effective visibility.
+     */
+    readonly Visibility: "visibility";
+
+    /**
+     * Effective conspicuousness.
+     */
+    readonly Conspicuousness: "conspicuousness";
+
+    /**
+     * Effective noise.
+     */
+    readonly Noise: "noise";
+
+    /**
+     * Native dirtiness reading; reading it does not clean the body or equipment.
+     */
+    readonly Dirtiness: "dirtiness";
+
+    /**
+     * Native bloodiness reading.
+     */
+    readonly Bloodiness: "bloodiness";
+
+    /**
+     * Native smell reading.
+     */
+    readonly Smell: "smell";
+
+    /**
+     * Native smell intensity.
+     */
+    readonly SmellIntensity: "smellIntensity";
+
+    /**
+     * Native fragrance reading.
+     */
+    readonly Fragrance: "fragrance";
+
+    /**
+     * Carried weight in the same units as InventoryCapacity.
+     */
+    readonly CarriedWeight: "carriedWeight";
+
+    /**
+     * Native carrying capacity, including applicable equipment effects.
+     */
+    readonly InventoryCapacity: "inventoryCapacity";
+
+    /**
+     * Native encumbrance reading.
+     */
+    readonly Encumbrance: "encumbrance";
+
+    /**
+     * Native hangover reading.
+     */
+    readonly Hangover: "hangover";
+
+    /**
+     * Computed alcoholism reading, not the persistent soul resource.
+     */
+    readonly Alcoholism: "alcoholism";
+
+    /**
+     * Effective armor rating.
+     */
+    readonly ArmorRating: "armorRating";
+
+    /**
+     * Overall armor defense.
+     */
+    readonly OverallArmorDefense: "overallArmorDefense";
+
+    /**
+     * Overall weapon attack.
+     */
+    readonly OverallWeaponAttack: "overallWeaponAttack";
+
+    /**
+     * Normalized run speed; not world-space velocity.
+     */
+    readonly NormalizedRunSpeed: "normalizedRunSpeed";
+
+    /**
+     * Native base run speed.
+     */
+    readonly RunSpeedBase: "runSpeedBase";
+
+    /**
+     * Native morale reading.
+     */
+    readonly Morale: "morale";
+  };
+
   /**
    * How a player's body looks: four of the game's own character-component names, and the gender whose catalog they come from.
    * 
@@ -670,12 +840,12 @@ declare global {
     readonly healthyStamina: number;
 
     /**
-     * Current tiredness, in the game's own units.
+     * Current energy reserve, in the game's own units. Higher means better rested.
      */
     readonly exhaust: number;
 
     /**
-     * Tiredness capacity, in the game's own units.
+     * Maximum energy reserve, in the game's own units.
      */
     readonly maxExhaust: number;
 
@@ -745,7 +915,7 @@ declare global {
     readonly relativeSkills: SoulSkills;
 
     /**
-     * The velocity the body's own animation was driven by this frame, not the one its physics settled on.
+     * On the owning machine, the velocity the body's own animation was driven by this frame, not the one its physics settled on. Everywhere else, measured from successive replicated positions.
      */
     readonly velocity: Vector3;
 
@@ -759,21 +929,6 @@ declare global {
      */
     readonly inAir: boolean;
 
-    /**
-     * The engine's own locomotion pace tag -- walk, jog, sprint -- as its animation system picked it. Raw Mannequin tag ids; 255 means nothing is set.
-     */
-    readonly moveSpeedTag: number;
-
-    /**
-     * The engine's own movement direction tag. Raw Mannequin tag ids; 255 means nothing is set.
-     */
-    readonly moveDirTag: number;
-
-    /**
-     * The engine's own stance tag -- upright, sneaking, sitting, lying. Raw Mannequin tag ids; 255 means nothing is set.
-     */
-    readonly stanceTag: number;
-
     /**
      * Whether this player is crouched, as their own game's crouch action reports it. False once their body is gone.
      */
@@ -830,12 +985,27 @@ declare global {
     readonly perks: string[];
 
     /**
-     * Whether this handle is the player sitting at this machine, rather than someone else's puppet.
+     * The locomotion pace tag -- walk, jog, sprint -- this machine's animation system picked for this body. Raw Mannequin tag ids; 255 means nothing is set.
+     */
+    readonly moveSpeedTag: number;
+
+    /**
+     * The movement direction tag this machine's animation system picked for this body. Raw Mannequin tag ids; 255 means nothing is set.
+     */
+    readonly moveDirTag: number;
+
+    /**
+     * The stance tag -- upright, sneaking, sitting, lying -- this machine's animation system picked for this body. Raw Mannequin tag ids; 255 means nothing is set.
+     */
+    readonly stanceTag: number;
+
+    /**
+     * Whether this handle is the player sitting at this machine, rather than someone else's copy.
      */
     readonly local: boolean;
 
     /**
-     * The engine entity this body was spawned as, or 0 across a level load and before the puppet exists. Not stable across a session: the engine reuses entity ids.
+     * The engine entity behind this player: the game's own player entity for the local player, otherwise the entity the copy was spawned as, or 0 across a level load and before it exists. Not stable across a session: the engine reuses entity ids.
      */
     readonly entityId: number;
 
@@ -862,6 +1032,18 @@ declare global {
      */
     toString(): string;
 
+    /**
+     * Reads the latest reported stat in native units. Returns zero when no valid body snapshot exists; check player.ready to distinguish that from a real zero. Throws for an unknown stat or invalid arguments.
+     * @param stat A PlayerStat value.
+     */
+    getStat(stat: "health" | "stamina" | "exhaust" | "hunger"): number;
+
+    /**
+     * Reads a computed stat from the latest body snapshot. Bleeding, Sleeping, Consciousness, Drunkenness and Poisoning follow the body as it changes; the others are sampled about every 250 ms to a hundredth of a native unit, then replicated. Values use native units and can be negative; they are not universally percentages. Returns zero without a valid snapshot. Throws for an unknown stat or invalid arguments. These readings do not override another player's native calculations.
+     * @param stat A DerivedPlayerStat value.
+     */
+    getDerivedStat(stat: "bleeding" | "sleeping" | "consciousness" | "drunkenness" | "poisoning" | "charisma" | "visibility" | "conspicuousness" | "noise" | "dirtiness" | "bloodiness" | "smell" | "smellIntensity" | "fragrance" | "carriedWeight" | "inventoryCapacity" | "encumbrance" | "hangover" | "alcoholism" | "armorRating" | "overallArmorDefense" | "overallWeaponAttack" | "normalizedRunSpeed" | "runSpeedBase" | "morale"): number;
+
     /**
      * Where the local player stands on one track: level, XP towards the next one, and unspent perk points. Only the local player carries XP and points; for anyone else this is null.
      * @param track A track name, from `Progression.tracks()`.
@@ -1043,6 +1225,18 @@ declare global {
      */
     isElementVisible(element: string): boolean;
 
+    /**
+     * The local character's own monologue -- photo-mode comments, the sharpening remark -- is spoken in Henry's voice and captioned with his name whoever is playing, so multiplayer suppresses it and raises each line as `monologueSuppressed`. Releasing it lasts until the session ends.
+     * @param enabled True lets the game voice and subtitle it again; false suppresses it.
+     */
+    setMonologueEnabled(enabled: boolean): void;
+
+    /**
+     * Whether the game voices and subtitles the local character's monologue.
+     * @returns False while multiplayer suppresses it, which is the default.
+     */
+    isMonologueEnabled(): boolean;
+
     /**
      * Every effect `addScreenEffect` accepts, with each parameter's range, default and neutral value.
      * @returns The effects, in a fixed order.
@@ -1093,6 +1287,13 @@ declare global {
      * @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;
+
+    /**
+     * Projects a world point through the camera this frame is drawn with, so a resource can pin its own overlay to the world.
+     * @param point World position to project.
+     * @returns Its screen position, or null when the point is behind the camera or there is no view to place it in.
+     */
+    worldToScreen(point: Vector3): ScreenPoint | null;
   };
 
   /**
@@ -1150,6 +1351,26 @@ declare global {
     params: ScreenEffectParam[];
   }
 
+  /**
+   * Where a world point lands on screen, in the pixels Web views are placed in.
+   */
+  interface ScreenPoint {
+    /**
+     * Pixels from the left edge of the window's client area.
+     */
+    x: number;
+
+    /**
+     * Pixels from the top edge of the window's client area.
+     */
+    y: number;
+
+    /**
+     * Whether the point is inside the view. One past an edge keeps its coordinates with this false.
+     */
+    onScreen: boolean;
+  }
+
   /**
    * 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.
    */
@@ -1228,7 +1449,7 @@ declare global {
   };
 
   /**
-   * 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`.
+   * 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 `playAnimation("", { clip })`.
    */
   const Assets: {
     /**
@@ -2539,12 +2760,12 @@ declare global {
   /**
    * 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.
+   * F7 or a client resource opens it. Multiplayer requires the server to grant this player access with `player.setWorldBuilderEnabled(true)`; single-player and offline editing are always allowed. 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.
+     * @returns `opened` when it opened. `alreadyOpen` when it was open already. `disabled` when this multiplayer connection has not been granted access.
      */
     open(): "opened" | "alreadyOpen" | "disabled";
 
@@ -2561,8 +2782,8 @@ declare global {
     isOpen(): boolean;
 
     /**
-     * Whether the connected server lets the editor open.
-     * @returns True when its `server.json` sets `mod.map_editor` to true.
+     * Whether this client may open World Builder.
+     * @returns True offline or when the server has granted this player access.
      */
     isEnabled(): boolean;
   };
@@ -3213,6 +3434,68 @@ declare global {
     image(path: string): string;
   };
 
+  /**
+   * A streamed player or human NPC. Its network identity is resolved again when follow starts; position and name are snapshots.
+   */
+  interface FollowTarget {
+    /**
+     * The target's network id.
+     */
+    id: number;
+
+    /**
+     * Which replicated entity the id identifies.
+     */
+    kind: "player" | "npc";
+
+    /**
+     * Player nickname or NPC name.
+     */
+    name: string;
+
+    /**
+     * Current native body position, in world-space metres.
+     */
+    position: Vector3;
+  }
+
+  /**
+   * Follow another player or a streamed human NPC using the local player's native walking or riding action. Native combat, interaction and mount restrictions still apply. Only one scripted follow can be queued or active. Movement input, target loss, mount changes and resource shutdown stop it. This controls only the local player; it does not command an NPC to follow.
+   */
+  const Follow: {
+    /**
+     * Lists streamed players and human NPCs within 20 metres. Use canStart to check whether one can currently be followed.
+     */
+    targets(): FollowTarget[];
+
+    /**
+     * Checks the target and native follow restrictions, including the game's start distance.
+     * @param target A remote player handle or a descriptor from targets().
+     */
+    canStart(target: Player | FollowTarget): boolean;
+
+    /**
+     * Queues native follow for the calling resource. True means queued; followStarted confirms entry. False means the request was refused.
+     * @param target Who the local player should follow.
+     */
+    start(target: Player | FollowTarget): boolean;
+
+    /**
+     * The active scripted follow target, or null while idle or pending.
+     */
+    getTarget(): FollowTarget | null;
+
+    /**
+     * Whether a scripted follow is queued but has not entered yet.
+     */
+    isPending(): boolean;
+
+    /**
+     * Cancels the calling resource's queued or active follow. Other resources' follow actions are left alone.
+     */
+    stop(): void;
+  };
+
   /**
    * What `CharacterCreator.open` shows.
    */
@@ -3266,7 +3549,7 @@ declare global {
    * 
    * 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.
+   * 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 normally leaves the game's own action on that key enabled. `chat_focus_follow_init` replaces the native focus/follow toggle while its hint is shown, so a scripted Follow action receives one press.
    * 
    * Client-only and local: a hint is shown to the player at this machine. Hints go when the resource that made them stops.
    */
@@ -4239,6 +4522,16 @@ declare global {
      * True in the authoritative server scripting runtime.
      */
     readonly isServer: boolean;
+
+    /**
+     * Local Framework release version.
+     */
+    readonly frameworkVersion: string;
+
+    /**
+     * Local mod version from InstanceOptions.modVersion; empty when unset.
+     */
+    readonly modVersion: string;
   };
 
   /**
@@ -4834,7 +5127,7 @@ declare global {
     update(): boolean;
 
     /**
-     * Clears the published Discord activity and resets staged state.
+     * Clears what scripts published and resets staged state.
      * @returns True when dispatched; false when Discord is unavailable.
      */
     clear(): boolean;
@@ -5107,6 +5400,8 @@ declare global {
    * Arbitrary key/value state attached to one replicated entity, reached as `entity.state`. Keys set on the server replicate to every client that can currently see the entity.
    */
   class StateBag {
+    private constructor();
+
     /**
      * Reads one key from this entity's state.
      * @param key Key to read.