@kingdomsconnected/types 1.5.0 → 1.5.2

package/{client/index.d.ts → generated/client-api.d.ts}

@@ -5,6 +5,38 @@ declare global {
    * Native events dispatched through `Events.on`. Each property is the exact callback argument tuple for that event.
    */
   interface EventMap {
+    /**
+     * Dispatched once per session, when the local player can play: the session is established and the game has taken its own loading screen down. The game raises that moment itself -- it is its own gameplay-start signal, not a guess from timing.
+     * 
+     * Resources are running long before this, so it is not the moment a resource may start listening; it is the moment the player is looking at the world. Put what the player should see on arrival here -- a welcome, a first page -- rather than in `resourceStart`, which runs behind the loading screen. The server raises its own `playerReady` for this player right after.
+     */
+    playerReady: [player: Player];
+
+    /**
+     * Dispatched when the local player's XP on a track went up: after the server granted a gain and the game applied it, with its own multipliers. `xp` is what landed, in the game's own units.
+     */
+    progressionXpGained: [track: string, xp: number];
+
+    /**
+     * Dispatched when a track of the local player's reaches a new level. `perkPoints` is what that track's tree now has unspent.
+     */
+    progressionLevelUp: [track: string, level: number, perkPoints: number];
+
+    /**
+     * Dispatched when the local player gained a perk: learnt on the perk screen and granted by the server, given by a server resource, or granted by the game on its own.
+     */
+    progressionPerkAdded: [perk: string];
+
+    /**
+     * Dispatched when the local player lost a perk.
+     */
+    progressionPerkRemoved: [perk: string];
+
+    /**
+     * Dispatched when the server turned down a perk the local player confirmed on the perk screen. The game's own screen says nothing when that happens, so this is where a resource tells the player why.
+     */
+    progressionPerkRefused: [perk: string, reason: "points" | "level" | "parent" | "exclusive" | "blocked" | "script" | "owned" | "hidden"];
+
     /**
      * 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.
      */
@@ -320,6 +352,231 @@ declare global {
     source: "server" | "native";
   }
 
+  /**
+   * One skill or stat a player levels, as the game's own tables describe it.
+   */
+  interface TrackInfo {
+    /**
+     * The name every progression verb takes, as the game's tables spell it: `weapon_sword`, `thievery`, `strength`.
+     */
+    name: string;
+
+    /**
+     * Whether it is a skill or one of the stats the skills sit on.
+     */
+    kind: "skill" | "stat";
+
+    /**
+     * The highest level the game lets it reach.
+     */
+    cap: number;
+
+    /**
+     * True for fencing alone: it is never earned, the game derives it from the five weapon skills, so XP handed to it is refused.
+     */
+    induced: boolean;
+  }
+
+  /**
+   * One perk, as the game's own perk tables describe it.
+   */
+  interface PerkInfo {
+    /**
+     * The perk's `perk_name`, unique across the tables, and the spelling every perk verb takes alongside its GUID.
+     */
+    name: string;
+
+    /**
+     * The perk's GUID.
+     */
+    id: string;
+
+    /**
+     * The localisation key the perk screen shows, or empty for a perk it never shows.
+     */
+    uiName: string;
+
+    /**
+     * The track whose points pay for it: a track name, `main` for the main-level bank, or null for a perk no player's tree carries.
+     */
+    track: string | null;
+
+    /**
+     * The level that track has to reach before the perk can be learnt. 0 for none.
+     */
+    level: number;
+
+    /**
+     * The perk that has to be owned first, or null.
+     */
+    parent: string | null;
+
+    /**
+     * `visible` perks are the ones on the perk screen and the only ones a player can learn; `hidden` ones appear once something grants them; `system` ones implement game features and are never shown.
+     */
+    visibility: "system" | "hidden" | "visible" | "obsolete";
+
+    /**
+     * What the perk does when owned, from the game's side tables: `buff` (a real status effect), `script`, `technique` (a combat move), `ability`, `param` (rewrites a game rule), `companion` (the dog), `recipe`, `codex`. Empty for a perk that only gates others.
+     */
+    kinds: string[];
+
+    /**
+     * Whether the game grants it on its own once its requirements are met, rather than on the perk screen.
+     */
+    autolearnable: boolean;
+  }
+
+  /**
+   * Where a player stands on one track.
+   */
+  interface TrackProgress {
+    /**
+     * The level reached.
+     */
+    level: number;
+
+    /**
+     * XP earned towards the next level, in the game's own units.
+     */
+    xp: number;
+
+    /**
+     * XP the next level costs in total, from the start of this one. `xp / xpToNext` is the bar the character sheet draws.
+     */
+    xpToNext: number;
+
+    /**
+     * Unspent perk points in this track's tree.
+     */
+    perkPoints: number;
+  }
+
+  /**
+   * A player's level on every track, keyed by track name.
+   */
+  interface TrackLevels {
+    /**
+     * The level reached.
+     */
+    stealth: number;
+
+    /**
+     * The level reached.
+     */
+    horse_riding: number;
+
+    /**
+     * The level reached.
+     */
+    fencing: number;
+
+    /**
+     * The level reached.
+     */
+    thievery: number;
+
+    /**
+     * The level reached.
+     */
+    alchemy: number;
+
+    /**
+     * The level reached.
+     */
+    craftsmanship: number;
+
+    /**
+     * The level reached.
+     */
+    drinking: number;
+
+    /**
+     * The level reached.
+     */
+    survival: number;
+
+    /**
+     * The level reached.
+     */
+    weapon_sword: number;
+
+    /**
+     * The level reached.
+     */
+    heavy_weapons: number;
+
+    /**
+     * The level reached.
+     */
+    marksmanship: number;
+
+    /**
+     * The level reached.
+     */
+    weapon_large: number;
+
+    /**
+     * The level reached.
+     */
+    weapon_unarmed: number;
+
+    /**
+     * The level reached.
+     */
+    scholarship: number;
+
+    /**
+     * The level reached.
+     */
+    houndmaster: number;
+
+    /**
+     * The level reached.
+     */
+    strength: number;
+
+    /**
+     * The level reached.
+     */
+    agility: number;
+
+    /**
+     * The level reached.
+     */
+    vitality: number;
+
+    /**
+     * The level reached.
+     */
+    speech: number;
+
+    /**
+     * The level reached.
+     */
+    prestige: number;
+  }
+
+  /**
+   * Everything a server needs to put a player's progression back: plain JSON a resource can store however it likes. A player starts every session with a fresh character, so this is how progression outlives a disconnect.
+   */
+  interface ProgressionSnapshot {
+    /**
+     * Level and XP into the next level, per track name.
+     */
+    tracks: Record<string, { level: number; xp: number }>;
+
+    /**
+     * Every perk owned, by name.
+     */
+    perks: string[];
+
+    /**
+     * Unspent points per tree: track names, and `main`.
+     */
+    perkPoints: Record<string, number>;
+  }
+
   /**
    * A KCDC player this client can see, and the body they occupy.
    */
@@ -537,6 +794,21 @@ declare global {
      */
     readonly equipment: string[];
 
+    /**
+     * The player's main level, the one the game derives from the stats. 0 until known.
+     */
+    readonly level: number;
+
+    /**
+     * The level of every skill and stat, keyed by track name. The local player reads its own character; anyone else reads what the server last accepted from theirs, and all zero until it has.
+     */
+    readonly levels: TrackLevels;
+
+    /**
+     * Every perk the player owns, by name -- the perk screen's and the hidden ones the game grants on its own.
+     */
+    readonly perks: string[];
+
     /**
      * Whether this handle is the player sitting at this machine, rather than someone else's puppet.
      */
@@ -569,10 +841,57 @@ declare global {
      * @returns The player's network entity ID, nickname, and whether they are the local player.
      */
     toString(): string;
+
+    /**
+     * 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()`.
+     * @returns The progress, or null for any other player. Throws for a track name the tables do not carry.
+     */
+    getTrack(track: string): TrackProgress | null;
+
+    /**
+     * Whether the player owns a perk.
+     * @param perk A perk's name or GUID.
+     * @returns True when they do; false for a perk they do not own, or a name the tables do not carry.
+     */
+    hasPerk(perk: string): boolean;
   }
 
   interface Player extends BasePlayer {}
 
+  /**
+   * The game's skills, stats and perks. Read-only on the client: every change to a player's progression is the server's.
+   */
+  const Progression: {
+    /**
+     * Every skill and stat a player levels: the fifteen skills the character sheet shows, then strength, agility, vitality, speech and prestige.
+     * @returns The tracks, in that order.
+     */
+    tracks(): TrackInfo[];
+
+    /**
+     * Looks a perk up.
+     * @param query A perk's name, as the game's perk tables spell it, or its GUID.
+     * @returns What the tables say about it, or null for a name they do not carry.
+     */
+    findPerk(query: string): PerkInfo | null;
+
+    /**
+     * Lists the game's perks: 945 of them, most of them hidden system perks. `Progression.perks({ visibleOnly: true })` is the perk screen.
+     * @param filter `track` keeps the perks one tree pays for -- a track name, or `main`; `visibleOnly` keeps the perks the perk screen shows.
+     * @returns The perks, sorted by name.
+     */
+    perks(filter?: { track?: string; visibleOnly?: boolean }): PerkInfo[];
+
+    /**
+     * The total XP a track costs from level 0 to `level`, on the game's own curve: each level costs `base + diff * level`, with base and diff from the game's RPG tables.
+     * @param track A track name.
+     * @param level The level to reach.
+     * @returns The XP. Throws for a track name the tables do not carry.
+     */
+    xpForLevel(track: string, level: number): number;
+  };
+
   /**
    * 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 call returns false while there is no HUD, which is the case in the main menu and across a level load.
    */
@@ -3555,7 +3874,7 @@ declare global {
     send(text: string): void;
 
     /**
-     * Changes visibility of the native chat overlay without opening its input field.
+     * Changes visibility of the native chat overlay without opening its input field. Hidden, the overlay also stops opening on its key. The choice holds for the rest of the session and resets to visible on disconnect, so a resource that replaces the chat calls this once at startup.
      * @param visible Whether the chat overlay is rendered.
      */
     setUIVisible(visible: boolean): void;
@@ -3797,6 +4116,18 @@ declare global {
      */
     getRange(): number;
 
+    /**
+     * Switches how far this player's voice carries. A request: the server paces it, decides the radius, and may move the player itself.
+     * @param tier Voice tier: 0 whisper, 1 normal, 2 shout.
+     */
+    setTier(tier: number): void;
+
+    /**
+     * Reads the voice tier this player is on.
+     * @returns 0 whisper, 1 normal, 2 shout.
+     */
+    getTier(): number;
+
     /**
      * Rebinds push-to-talk. Unknown key names throw.
      * @param key Case-insensitive key name, using the same names as Key.bind.