@kingdomsconnected/types 1.6.4 → 1.6.6

package/generated/client-api.d.ts

@@ -2192,7 +2192,7 @@ declare global {
   /**
    * The view this client is drawing through. Nothing here is replicated and nothing here is authority: it describes one machine's own camera at one moment.
    * 
-   * This is the game's camera, not a camera of the mod's own -- it follows the player, a dialogue, a cutscene or a free flight, whichever the game currently has. `NoClip` is what takes it over, and `setThirdPerson` puts it behind the player.
+   * This is the game's camera, not a camera of the mod's own -- it follows the player, a dialogue, a cutscene or a free flight, whichever the game currently has. `NoClip` is what takes it over, `setThirdPerson` puts it behind the player, and `setShot` stands it somewhere in the world.
    */
   const Camera: {
     /**
@@ -2211,7 +2211,7 @@ declare global {
     /**
      * Puts this player's camera behind them, for as long as it is on.
      * 
-     * The game has no third-person view to switch to, so this is a camera of the mod's own, placed every frame behind the body along the direction the player is looking. Nothing about their controls changes: they walk and turn as they did, and the mouse still turns the body. When a wall is behind them the camera comes in along the same line rather than going through it.
+     * The game has no third-person view to switch to, so this is a camera of the mod's own, placed every frame behind the body along the direction the player is looking. Nothing about their controls changes: they walk and turn as they did, and the mouse still turns the body. When a wall is behind them the camera comes in along the same line rather than going through it. Their head, which the game keeps out of its own first person, is drawn for as long as this camera is the one looking at them.
      * 
      * This is what a disguised player needs -- `player.setDisguise` hides the body the game's own camera sits in. It is this client's own view, so a gamemode turns it on from a client script, typically on an event the server sends the disguised player.
      * 
@@ -2225,6 +2225,31 @@ declare global {
      * @returns True from `setThirdPerson` until it is turned off, also while it waits for a body or for `NoClip`.
      */
     isThirdPerson(): boolean;
+
+    /**
+     * Films this player's view from a fixed point: what a cutscene, an intro or a kill cam is made of.
+     * 
+     * The camera holds there until `clearShot` -- or until another `setShot`, which glides on from wherever this one is. Nothing about the player's controls changes; a gamemode that wants them still says so through `Controls`. The player's head, which the game keeps out of its first person, is drawn for as long as the camera is looking at them from outside their eyes.
+     * 
+     * There is one view to draw through. A shot outranks `setThirdPerson`, which takes over again when the shot ends, and `NoClip` cannot start while it holds. The map, the inventory and the other pause-screen pages are filmed by the game's own camera, so the shot steps aside while one is open and comes back when it closes. A shot ends with the session.
+     * 
+     * The server can send the same shot with its own `Camera.setShot(player, options)`; whichever comes last wins.
+     * @param options `position` is where the camera stands and `lookAt` the point it faces, both in world space. `duration` is how long it takes to get there from wherever the view is now, in milliseconds: 0, the default, is a cut, and the most is 60000. `fov` is the vertical field of view in degrees, 20 to 120; leave it out to keep the player's own.
+     * @returns True, or false while `NoClip` is flying or when `position` and `lookAt` are the same point.
+     */
+    setShot(options: { position: Vector3; lookAt: Vector3; duration?: number; fov?: number }): boolean;
+
+    /**
+     * Gives the player their own view back. Does nothing without a shot.
+     * @param duration How long the glide back into the player's eyes takes, in milliseconds: 0, the default, is a cut, and the most is 60000. The glide follows the player if they move meanwhile. With `setThirdPerson` on, it ends behind them instead and their head stays drawn.
+     */
+    clearShot(duration?: number): void;
+
+    /**
+     * Whether a shot holds the view.
+     * @returns True from `setShot`, including its glide in, until `clearShot`; false already while gliding back.
+     */
+    isShotActive(): boolean;
   };
 
   /**
@@ -3592,6 +3617,61 @@ declare global {
     keys(): string[];
   };
 
+  /**
+   * A local inventory action intercepted before the game applies it. A snapshot, not permission to spend an item on the server.
+   */
+  interface InventoryUse {
+    /**
+     * Item class GUID, using the logical GUID for custom items.
+     */
+    item: string;
+
+    /**
+     * Native instance UID as a lossless decimal string. Local to this client; splits, merges and reprojection may replace it.
+     */
+    uid: string;
+
+    /**
+     * A server inventory row represented by the selected native item. Send this to a server resource to request consumption.
+     */
+    id: string;
+
+    /**
+     * The inventory revision at the time of the action. The server must validate it and current ownership.
+     */
+    revision: number;
+
+    /**
+     * Always 1. The override requests one use, even when a native row represents a stack.
+     */
+    amount: number;
+
+    /**
+     * Which native path was intercepted. Eat/Drink and Learn use secondary; primary also includes equipment actions; activate is the native equip-toggle path.
+     */
+    action: "primary" | "secondary" | "activate";
+  }
+
+  /**
+   * Client-side overrides for actions in the local player's native inventory. Register by catalog item name, class GUID, custom item id, or { uid } for one native instance. A matching handler replaces the action before native consumption or effects. Scripts run on the next feature update, outside the native detour; return values are ignored and errors do not restore the native action. Only owned, synchronized inventory items dispatch. Pending uses are discarded if their handler, native item, server row or inventory revision disappears or changes. Instance handlers take priority over class handlers; otherwise the newest matching registration wins. Removing it reveals the earlier handler. Resource stop and session end remove handlers. The server remains responsible for validating requests, consuming inventory and applying effects. This API does not intercept quick-slot actions outside the inventory.
+   */
+  const Inventory: {
+    /**
+     * Registers an inventory action override for this resource. Adds a Use action even for an item without a normal primary action. Duplicate presses on the same UID within one frame are combined.
+     * @param item Catalog name such as apple, a class GUID, a custom item id, or a native UID from InventoryUse.uid.
+     * @param handler Runs instead of the native action. No item is automatically consumed.
+     * @returns A registration id for offUse. Throws for an unknown class, invalid UID, missing resource or more than 256 active registrations.
+     */
+    onUse(item: string | { uid: string }, handler: (use: InventoryUse) => void): number;
+
+    /**
+     * Removes a handler owned by the calling resource and discards its pending uses.
+     * @param handlerId Id returned by onUse.
+     * @returns False if the registration is missing or belongs to another resource.
+     */
+    offUse(handlerId: number): boolean;
+  };
+
   /**
    * Mutable two-dimensional vector.
    */