@kingdomsconnected/types 1.6.1 → 1.6.3

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 behind this player: the game's own player entity for the local player, otherwise the entity the puppet was spawned as, or 0 across a level load and before it 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.
@@ -3240,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.
    */
@@ -3293,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.
    */
@@ -4266,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;
   };
 
   /**
@@ -4861,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;
@@ -5040,7 +5306,7 @@ declare global {
   };
 
   /**
-   * The local player's view of the nametags above other players: whether they draw at all, and whether they carry a health bar.
+   * The local player's view of the nametags above players: whether they draw at all, whether they carry a health bar, and whether their own is shown.
    */
   const Nametags: {
     /**
@@ -5067,6 +5333,18 @@ declare global {
      */
     isHealthVisible(): boolean;
 
+    /**
+     * Shows or hides this player's own nametag, drawn as others see it, with any label set on their own id.
+     * @param visible True to draw this player's own nametag, false (default) to leave it off.
+     */
+    setSelfVisible(visible: boolean): void;
+
+    /**
+     * Checks whether this player draws their own nametag.
+     * @returns False unless it was turned on locally.
+     */
+    isSelfVisible(): boolean;
+
     /**
      * Hangs a transient line on that entity's nametag, above its name -- speech, an emote, a status. It follows the body, fades with distance and hides behind cover exactly as the name does. Local to this player: the line is not replicated, and a nametag hidden with Nametags.setVisible draws neither. Player.setNametagText is the server-side counterpart for a lasting name.
      * @param entityId Network id of the entity to label (server-side `player.id`).