@kingdomsconnected/types 1.5.5 → 1.5.6

package/generated/client-api.d.ts

@@ -909,6 +909,8 @@ declare global {
 
   /**
    * 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 message call returns false while there is no HUD, which is the case in the main menu and across a level load.
+   * 
+   * The screen-effect verbs -- `addScreenEffect` and its siblings -- put full-screen post effects on this player's own picture. They are drawn by the game's renderer rather than the HUD, so they need no HUD and hiding HUD elements leaves them alone.
    */
   const Hud: {
     /**
@@ -1022,21 +1024,127 @@ declare global {
     clearNotifications(): boolean;
 
     /**
-     * Hides or shows one element of the game's HUD at this client, through the switch the game itself keeps for each. It can be called at any time, before the HUD has loaded included: the game re-applies the switch every time the HUD loads, across level loads too. Turning an element on does not force it up; the game still hides it where it would anyway, in dialogue or a menu, say. The player's own setting comes back when the resource that changed it stops.
+     * Retains a visibility request for one HUD element, including before the HUD is ready. Hidden clips are suppressed before each HUD render, across movie and level reloads. Turning an element on releases multiplayer suppression; the current native HUD rules still apply. Suppression is released when its owning resource stops or the session ends. No console variables are changed.
      * @param element The element, by the game's own name for it: `Stats` is the health, stamina and nourishment bars along the bottom. One of `Compass`, `Stats`, `QAMWeapon`, `QAMFood`, `Subtitles`, `InfoText`, `GameLog`, `Hints`, `DialogLeft`, `DialogRight`, `Cursor`, `Crime`, `Wanted`, `PopUpBackground`, `TutorialMessage`, `FancyEvent`, `SkillCheck`, `ItemTransfer`, `Buffs`, `CommonEvent`, `DiceCursor`, `Trespassing`, `RatioStrips`, `ShootingContest`, `Bubbles`, `TutorialInDialog`, `DiceContainer`, `Vignette`, compared exactly.
      * @param visible False hides the element, true lets the game show it again.
-     * @returns True when the switch took it; false only before the game has created its HUD switches, which it does at startup.
+     * @returns True when the request is retained; application waits for the native HUD when it is not ready yet.
      */
     setElementVisible(element: string, visible: boolean): boolean;
 
     /**
-     * Whether one element's switch is on. An element whose switch is on can still be hidden by the game at that moment.
+     * Whether multiplayer permits the element to show. True when no resource suppresses it; native gameplay rules can still hide it. This is not a pixel-visibility query.
      * @param element The element, by the game's own name for it, as `setElementVisible` takes it.
-     * @returns True while the element is allowed to show.
+     * @returns True while multiplayer allows the element to show.
      */
     isElementVisible(element: string): boolean;
+
+    /**
+     * Every effect `addScreenEffect` accepts, with each parameter's range, default and neutral value.
+     * @returns The effects, in a fixed order.
+     */
+    screenEffects(): ScreenEffect[];
+
+    /**
+     * Puts a full-screen effect on this player's own picture -- a colour grade, a blur, ghosting or the game's blood overlay, for intoxication, injury, poison, dreams or a place that should feel wrong -- owned by the calling resource. These are the game's own post-processing passes, driven with the parameters this build actually reads; they are not part of the HUD and showing or hiding HUD elements does not touch them.
+     * 
+     * This is presentation, not state. Nothing is replicated, nobody else sees it, and none of it makes a player drunk or hurt: whatever decides that -- usually the server -- keeps it, and a client script asks for the picture to match. Weather and time of day are shared world state and are not touched.
+     * 
+     * Effects from every resource combine rather than overwrite each other, on top of the game's own grade -- which already desaturates the screen as health runs low -- rather than in its place: brightness, contrast and saturation multiply, the colour cast and the hue shift add, and blur, ghosting and blood each draw the strongest one asked for. The result does not depend on which resource asked first, and removing one effect leaves the game's grade and every other effect as they were.
+     * 
+     * An effect belongs to the resource that created it: only that resource can change or remove it, and it goes when the resource stops, when the session ends or when the level changes. A cinematic that resets the game's post-processing clears the screen until the effect next changes. Up to 64 effects are kept across every resource.
+     * @param effect Which effect, as `screenEffects` names it.
+     * @param params Values for the effect's own parameters, each clamped into its range. A parameter left out takes its default; one the effect does not take is an error.
+     * @param options `fadeInMs` brings it up from nothing; `fadeOutMs` is how long it takes to go, when its duration runs out or when `removeScreenEffect` is called without a fade of its own; `durationMs` ends it on its own after that long, before its fade-out -- 0, the default, keeps it until it is removed. Fades are up to a minute.
+     * @returns A handle for `updateScreenEffect`, `removeScreenEffect` and `isScreenEffectActive`, or 0 when 64 effects are already on screen.
+     */
+    addScreenEffect(effect: "colorGrade" | "blur" | "ghosting" | "screenBlood", params?: { saturation?: number; brightness?: number; contrast?: number; cyan?: number; magenta?: number; yellow?: number; darkness?: number; hue?: number; amount?: number }, options?: { fadeInMs?: number; fadeOutMs?: number; durationMs?: number }): number;
+
+    /**
+     * Changes an effect while it is on screen -- a drunkenness that deepens with every drink, a wound that worsens.
+     * @param handle What `addScreenEffect` returned.
+     * @param params New values for some of the effect's parameters. The others keep theirs.
+     * @param options `fadeMs` moves the parameters to their new values over that long, from wherever they are now; 0, the default, moves them at once.
+     * @returns False when the handle is gone or belongs to another resource.
+     */
+    updateScreenEffect(handle: number, params: { saturation?: number; brightness?: number; contrast?: number; cyan?: number; magenta?: number; yellow?: number; darkness?: number; hue?: number; amount?: number }, options?: { fadeMs?: number }): boolean;
+
+    /**
+     * Takes an effect off the screen. An effect already fading out carries on from where it is.
+     * @param handle What `addScreenEffect` returned.
+     * @param options How long it takes to fade out. Left out, it fades over the `fadeOutMs` it was created with; 0 takes it off at once.
+     * @returns False when the handle is gone or belongs to another resource.
+     */
+    removeScreenEffect(handle: number, options?: { fadeOutMs?: number }): boolean;
+
+    /**
+     * Takes every effect the calling resource owns off the screen at once. Other resources' effects stay.
+     * @returns How many were removed.
+     */
+    removeAllScreenEffects(): number;
+
+    /**
+     * Whether an effect is still on screen, fading out included.
+     * @param handle What `addScreenEffect` returned.
+     * @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;
   };
 
+  /**
+   * One parameter a screen effect takes.
+   */
+  interface ScreenEffectParam {
+    /**
+     * The key to pass it under in a params bag.
+     */
+    name: string;
+
+    /**
+     * What it does to the picture.
+     */
+    description: string;
+
+    /**
+     * The lowest value it takes. Anything lower is clamped.
+     */
+    min: number;
+
+    /**
+     * The highest value it takes. Anything higher is clamped.
+     */
+    max: number;
+
+    /**
+     * What `addScreenEffect` uses when the parameter is not given.
+     */
+    default: number;
+
+    /**
+     * The value at which it leaves the picture alone, which is also where a fade starts and ends.
+     */
+    neutral: number;
+  }
+
+  /**
+   * One screen effect `Hud.addScreenEffect` accepts.
+   */
+  interface ScreenEffect {
+    /**
+     * What to pass to `addScreenEffect`.
+     */
+    name: string;
+
+    /**
+     * What it does, and how several of it combine.
+     */
+    description: string;
+
+    /**
+     * Every parameter it takes, with its range.
+     */
+    params: ScreenEffectParam[];
+  }
+
   /**
    * 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.
    */

package/generated/server-api.d.ts

@@ -194,6 +194,16 @@ declare global {
      */
     playerPickpocketCaught: [thief: Player, victim: Player];
 
+    /**
+     * Dispatched once a match has started and both players have been sent to the table. Which of them throws first is drawn at random.
+     */
+    diceMatchStart: [match: number, first: Player, second: Player, targetScore: number];
+
+    /**
+     * Dispatched once a match is over and both players have been told. `winner` is 0 when `first` won, 1 when `second` did, 255 when nobody did. `reason` is `won` (a player banked the target score), `gaveUp` (a player left the table), `left` (a player disconnected), `timedOut` (the player to throw did not move for three minutes), `failed` (a client could not play the table) or `stopped` (`Dice.stop`). A player who has gone since is null. Nothing changes hands on its own: what a match was played for is the gamemode's to settle here.
+     */
+    diceMatchEnd: [match: number, first: Player | null, second: Player | null, winner: number, reason: string, firstScore: number, secondScore: number];
+
     /**
      * A player asks to open an alchemy table, or to begin a smithing recipe. Every handler runs; one returning literal `false` refuses it. An async handler cannot refuse.
      */
@@ -375,7 +385,7 @@ declare global {
     gatheringHarvest: [player: Player, proposal: GatheringProposal];
 
     /**
-     * A player was given a herb, after the `playerInventoryChanged` it caused. The plant and the same-kind plants harvested with it are picked for everyone in the virtual world until they regrow; nothing about them survives a restart.
+     * A player was given a herb, after the `playerInventoryChanged` it caused. The plant and the same-kind plants harvested with it are picked for everyone in the virtual world until timed or scripted regrowth; nothing about them survives a restart.
      */
     gatheringHarvested: [player: Player, event: GatheringHarvestedEvent];
 
@@ -1639,7 +1649,7 @@ declare global {
     get(player: Player): InventoryState | null;
 
     /**
-     * Gives a player items of a class, 1 to 10000 at a time. Left-out properties mean quality 1 at full condition. The units join the row that already holds this class with these properties, if there is one.
+     * Gives a player items of a class, 1 to 10000 at a time. `item` is the class GUID or the exact name the game's own item tables use, the same spelling `giveItem` takes. Left-out properties mean quality 1 at full condition; `metadata.quality` asks for a higher tier, up to what the class is made in, and `invalidQuality` refuses one past it. The units join the row that already holds this class with these properties, if there is one.
      */
     add(player: Player, request: { item: string; amount: number; metadata?: Record<string, unknown>; revision?: number }): InventoryResult;
 
@@ -2145,6 +2155,46 @@ declare global {
     amount: number;
   }
 
+  /**
+   * How a dice match is played.
+   */
+  interface DiceMatchOptions {
+    /**
+     * The score that wins, banked at the end of a turn. 2000 when omitted, at most 100000.
+     */
+    targetScore: number | undefined;
+  }
+
+  /**
+   * Dice matches between two players on the game's own dice table.
+   * 
+   * Both players sit down at the dice table nearest them and play it as they would against an NPC, the other player's body opposite. Every throw is dealt and every move checked by the server, by the game's own scoring rules; badges and dice perks are off, so a match is decided by the dice and the decisions alone.
+   */
+  const Dice: {
+    /**
+     * Starts a match. Both players must stand together, within a few metres, at a dice table, and neither may be playing already. Throws an Error saying why when it cannot start.
+     * @param first NetworkID of the player on the table's first seat.
+     * @param second NetworkID of the player on the second seat.
+     * @param options The target score. Optional.
+     * @returns The match id.
+     */
+    start(first: number, second: number, options?: DiceMatchOptions): number;
+
+    /**
+     * Ends a match with nobody winning; both tables close.
+     * @param match The match to end.
+     * @returns False when it had already ended.
+     */
+    stop(match: number): boolean;
+
+    /**
+     * The match a player is in.
+     * @param player NetworkID of the player to ask about.
+     * @returns The match id, or 0.
+     */
+    matchOf(player: number): number;
+  };
+
   /**
    * A table a player is about to open, or a workpiece about to take its materials. Frozen: a handler can refuse it, not change it.
    */
@@ -4022,6 +4072,60 @@ declare global {
 
   interface GroundItem extends Entity {}
 
+  /**
+   * The server-wide override for herb regrowth, measured in game hours.
+   */
+  interface GatheringRespawnTime {
+    /**
+     * Lower bound, inclusive. Both bounds zero disable timed regrowth.
+     */
+    minHours: number;
+
+    /**
+     * Upper bound, inclusive. Equal positive bounds give a fixed duration.
+     */
+    maxHours: number;
+  }
+
+  /**
+   * Controls herb regrowth. Defaults are five times faster than the game's authored species timings. Changes are held in server memory.
+   */
+  const Gathering: {
+    /**
+     * Current frozen override, or null for the species defaults at one fifth of their authored duration.
+     */
+    readonly respawnTime: GatheringRespawnTime | null;
+
+    /**
+     * Restarts all active herb deadlines from now and sets the policy for future picks. Samples uniformly per plant. Equal bounds fix the duration; (0, 0) disables timed regrowth while manual respawn remains available. Applies to every virtual world.
+     * @param minHours Minimum game hours, from 0 to maxHours.
+     * @param maxHours Maximum game hours, up to 87600. Positive durations must reach at least one game millisecond.
+     * @returns True on success; false for non-finite, reversed or out-of-range bounds.
+     */
+    setRespawnTime(minHours: number, maxHours: number): boolean;
+
+    /**
+     * Restores five-times-faster species defaults and restarts all active herb timers from now.
+     */
+    resetRespawnTime(): void;
+
+    /**
+     * Respawns recorded harvested plants in a sphere, including plants with timed regrowth disabled. Restores client vegetation as well as server availability. Does not create new plants.
+     * @param position Centre of the sphere in world metres; finite coordinates within +/-100000.
+     * @param radius Inclusive 3D radius in metres, from 0 to 100000.
+     * @param virtualWorld Only this virtual world; defaults to 0.
+     * @returns Number of active harvested sources restored. Invalid arguments throw.
+     */
+    respawn(position: Vector3, radius: number, virtualWorld?: number): number;
+
+    /**
+     * Respawns every recorded harvested plant in one virtual world, including plants with timed regrowth disabled.
+     * @param virtualWorld Only this virtual world; defaults to 0.
+     * @returns Number of active harvested sources restored. Invalid arguments throw.
+     */
+    respawnAll(virtualWorld?: number): number;
+  };
+
   /**
    * A plant a player picked and what it is about to give them.
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kingdomsconnected/types",
-  "version": "1.5.5",
+  "version": "1.5.6",
   "description": "TypeScript declarations for the Kingdoms Connected scripting API, one entry per side: @kingdomsconnected/types/server and @kingdomsconnected/types/client",
   "license": "UNLICENSED",
   "keywords": [