@kingdomsconnected/types 1.5.2 → 1.5.3

package/generated/server-api.d.ts

@@ -168,7 +168,7 @@ declare global {
     dialogueClosed: [session: number, player: Player, reason: number];
 
     /**
-     * Dispatched once a deal has settled: everything in it has already moved. `balance` is what the player came out with in money units -- positive when the vendor paid them. What the player sold does not join the vendor's stock; add it with `setStock` here if this vendor resells.
+     * Dispatched once a deal has settled: everything in it has already moved, in one commit on the player's inventory whose playerInventoryChanged reason is `trade`. `balance` is what the player came out with in money units -- positive when the vendor paid them. What the player sold does not join the vendor's stock; add it with `setStock` here if this vendor resells.
      */
     vendorTrade: [vendor: number, player: Player, bought: VendorTradeLine[], sold: VendorTradeLine[], balance: number];
 
@@ -249,6 +249,31 @@ declare global {
      */
     propDestroy: [prop: Prop];
 
+    /**
+     * Dispatched immediately after a cart is created and replicated, whether by `Cart.spawn`, the `/cart` command, or anything else.
+     */
+    cartSpawn: [cart: Cart];
+
+    /**
+     * Dispatched while a cart is being despawned, after everyone in it has been let out. The handle still resolves, so its blueprint and its pose can be read one last time.
+     */
+    cartDestroy: [cart: Cart];
+
+    /**
+     * Dispatched before a player is put in a seat -- by their own use of the cart's prompt, or `putPlayer`. Return `false` from a handler and the seat is refused: nothing changes, and the player's game never climbs in. Handlers run synchronously.
+     */
+    cartEntering: [cart: Cart, player: Player, seat: string];
+
+    /**
+     * Dispatched after a player is given a seat. `seat` is `driver` or `back`; a driver's client runs the cart from here on.
+     */
+    cartEnter: [cart: Cart, player: Player | null, seat: string];
+
+    /**
+     * Dispatched after a player leaves a seat: their own climb down, `removePlayer`, a disconnect, or the cart being destroyed.
+     */
+    cartExit: [cart: Cart, player: Player | null, seat: string];
+
     /**
      * Dispatched immediately after a replicated particle effect is placed, whether by `Vfx.spawn`, a command, or anything else.
      */
@@ -355,11 +380,11 @@ declare global {
     gatheringHarvested: [player: Player, event: GatheringHarvestedEvent];
 
     /**
-     * Dispatched when a player's client reports working a door, before the server applies it. `action` is `open`, `close`, `lock`, `unlock` or `lockpick`; a key turned in the same use as the push arrives as `unlock` and then `open`. `keySide` says whether the player stood on the side with the keyhole, which is where an unlock needs a key.
+     * Dispatched when a player's client reports working a door, before the server applies it. `action` is `open`, `close`, `unlock` or `lockpick`; a key turned in the same use as the push arrives as `unlock` and then `open`. `keySide` says whether the player stood on the side with the keyhole, which is where an unlock needs a key.
      * 
      * Return false to refuse it: the door is put back on every client, the player's included, and nobody else sees it happen. Every handler runs whatever an earlier one returned, and an async handler cannot refuse. The server has already refused what the game's own rules forbid -- a player out of reach, a door the server locked, opening a locked door, picking a door with no keyhole -- so this only sees what the game would allow.
      */
-    doorInteract: [player: Player, door: Door, action: "open" | "close" | "lock" | "unlock" | "lockpick", keySide: boolean];
+    doorInteract: [player: Player, door: Door, action: "open" | "close" | "unlock" | "lockpick", keySide: boolean];
 
     /**
      * A container now exists: one a script spawned, or one the level places, built in a virtual world the first time anything there asked for it. Every container starts empty; restore saved contents here with `setInventory`. The level's containers in the global world are built before any resource runs, so restore those from `resourceStart` by walking `Stash.all()`.
@@ -1540,7 +1565,7 @@ declare global {
     revision: number;
 
     /**
-     * `add`, `remove`, `properties`, `set`, `transfer`, `wear` when the player's game wore an item down in use, `use` for food, potions and ointments, `shot` for a fired round, `pickpocket`, `drop` for `player.dropInventory`, or the ground, stash and gathering reasons.
+     * `add`, `remove`, `properties`, `set`, `transfer`, `wear` when the player's game wore an item down in use, `use` for food, potions and ointments, `shot` for a fired round, `pickpocket`, `trade` for a vendor deal, `drop` for `player.dropInventory`, or the ground, stash and gathering reasons.
      */
     reason: string;
 
@@ -1989,7 +2014,7 @@ declare global {
     create(options?: VendorOptions): number;
 
     /**
-     * Closes every session at the vendor and forgets it. A deal already settling still completes.
+     * Closes every session at the vendor and forgets it. A deal settles the moment its basket arrives, so none is ever left half done.
      * @param vendor The vendor to remove.
      * @returns False when there was no such vendor.
      */
@@ -2697,6 +2722,124 @@ declare global {
 
   interface Prop extends Entity {}
 
+  /**
+   * Replicated cart or wagon handle.
+   */
+  class Cart {
+    /**
+     * Creates a script wrapper for an existing cart with this ID; use Cart.spawn() to spawn one.
+     * @param id Network entity identifier.
+     */
+    constructor(id: number);
+
+    /**
+     * The game prefab this cart was built from, e.g. `wagon_b_covered`. `Cart.blueprints()` lists them all.
+     */
+    readonly blueprint: string;
+
+    /**
+     * How many horses the cart is harnessed for: 2 for a wagon, 1 for the two-wheeled cart, 0 for `wagon_b_covered_empty`, whose chassis has nowhere to hitch one and so can be sat in but never pulled.
+     */
+    readonly horseCount: number;
+
+    /**
+     * The player at the reins, or null when nobody drives it.
+     */
+    readonly driver: Player | null;
+
+    /**
+     * How the driver last asked the cart to go: `stand`, `walk`, `trot` or `reverse`.
+     */
+    readonly pace: string;
+
+    /**
+     * Formats this cart handle for logging and debugging.
+     * @returns The cart ID, its blueprint, its driver and its pace.
+     */
+    toString(): string;
+
+    /**
+     * Despawns this cart on every client. Everyone in it is let out first, each with a `cartExit`, then `cartDestroy` is raised.
+     */
+    destroy(): void;
+
+    /**
+     * Puts a player in a seat. They are taken out of any cart they were in, their own game walks them to the seat and climbs in, and `cartEnter` follows; the driver's client runs the cart from then on. `cartEntering` handlers are asked first.
+     * @param player The player to seat.
+     * @param seat `driver` (the bench, holding the reins) or `back` (the right rail): the two seats the game animates a player in.
+     * @returns Whether the player was seated: false for a taken seat, a player that is not connected, or a handler's refusal.
+     */
+    putPlayer(player: Player, seat: string): boolean;
+
+    /**
+     * Lets a player out of this cart: their own game climbs down, and `cartExit` is raised.
+     * @param player The player to let out.
+     * @returns False when the player is not in this cart.
+     */
+    removePlayer(player: Player): boolean;
+
+    /**
+     * Who sits in a seat.
+     * @param seat `driver` or `back`.
+     * @returns The player in it, or null when it is empty.
+     */
+    getOccupant(seat: string): Player | null;
+
+    /**
+     * Where a player sits in this cart.
+     * @param player The player to look for.
+     * @returns `driver` or `back`, or null when they are not in it.
+     */
+    seatOf(player: Player): string | null;
+
+    /**
+     * Moves the cart outright, with everyone in it: every client rebuilds it on a new short road at the new pose, and a driver carries on from there.
+     * @param position Where the cart's front axle stands.
+     * @param rotation Which way it faces; omitted keeps its heading.
+     * @returns False for a pose that is not finite.
+     */
+    teleport(position: Vector3, rotation?: Vector3 | Quaternion): boolean;
+
+    /**
+     * Spawns and replicates a cart or wagon from the game's own prefabs, with its horses already in the shafts. It stands on a short straight road until somebody takes the reins.
+     * @param blueprint Which of the game's cart prefabs to build; omitted builds `wagon_b_covered`. `Cart.blueprints()` lists them.
+     * @param position Where the cart's front axle stands; omitted components default to zero.
+     * @param rotation Which way it faces: a Quaternion, or a Vector3 of Euler angles in degrees.
+     * @param virtualWorld Optional virtual world the cart belongs to; omitted puts it in the global one.
+     * @returns The newly spawned cart handle.
+     */
+    static spawn(blueprint?: string, position?: Vector3 | Partial<Vector3>, rotation?: Vector3 | Quaternion, virtualWorld?: number): Cart;
+
+    /**
+     * Lists the carts the server has.
+     * @param virtualWorld Optional virtual world to list; omitted lists every one.
+     * @returns One handle per live cart, in no particular order.
+     */
+    static all(virtualWorld?: number): Cart[];
+
+    /**
+     * Looks a cart up by its network entity ID.
+     * @param id Network entity identifier.
+     * @returns The cart's handle, or null when no live cart has that ID.
+     */
+    static getById(id: number): Cart | null;
+
+    /**
+     * Despawns carts, emitting cartDestroy for each one.
+     * @param virtualWorld Optional virtual world to clear; omitted clears every one of them.
+     * @returns How many carts were removed.
+     */
+    static destroyAll(virtualWorld?: number): number;
+
+    /**
+     * Names every cart prefab `Cart.spawn` can build.
+     * @returns The blueprint names, in catalog order.
+     */
+    static blueprints(): string[];
+  }
+
+  interface Cart extends Entity {}
+
   /**
    * Replicated particle effect handle.
    */
@@ -3388,30 +3531,44 @@ declare global {
      * @param objective The line, as text or as an object carrying its state.
      * @param announce Whether to raise the quest-updated toast; defaults to true.
      */
-    setObjective(index: number, objective: string | { text: string; progress?: 'active' | 'done' | 'failed'; optional?: boolean }, announce?: boolean): void;
+    setObjective(index: number, objective: string | { text: string; progress?: 'active' | 'done' | 'failed'; optional?: boolean; position?: Vector3 }, announce?: boolean): void;
 
     /**
      * Replaces the quest's objective list.
      * @param objectives The whole list, at most eight entries; anything past that is dropped.
      * @param announce Whether to raise the quest-updated toast; defaults to true.
      */
-    setObjectives(objectives: (string | { text: string; progress?: 'active' | 'done' | 'failed'; optional?: boolean })[], announce?: boolean): void;
+    setObjectives(objectives: (string | { text: string; progress?: 'active' | 'done' | 'failed'; optional?: boolean; position?: Vector3 })[], announce?: boolean): void;
 
     /**
      * Reads the quest's objectives back.
-     * @returns One entry per objective, in journal order.
+     * @returns One entry per objective, in journal order. `position` is present only on an objective that has one.
+     */
+    objectives(): { text: string; progress: 'active' | 'done' | 'failed' | 'none'; optional: boolean; position?: Vector3 }[];
+
+    /**
+     * Makes the game follow this quest, exactly as the journal's track button does: it is listed in the HUD tracker, and every active objective that has a `position` is drawn as the game's own quest marker on the map and the compass. It is an instruction, not a lock -- the player can untrack it from the journal -- and the outcome arrives as `questTrackingChanged` like any other change. A quest given a moment ago can be tracked at once; the client waits for it to arrive.
+     * @param player Network id of the player who should follow the quest. Omitted, everyone who has the quest follows it: its one owner, or every player in its world.
+     * @returns How many clients were told. Zero when the player does not have this quest.
+     */
+    track(player?: number): number;
+
+    /**
+     * Makes the game stop following this quest, which takes its markers off the map and the compass. The outcome arrives as `questTrackingChanged`.
+     * @param player Network id of the player who should stop following the quest. Omitted, everyone who has the quest stops.
+     * @returns How many clients were told.
      */
-    objectives(): { text: string; progress: 'active' | 'done' | 'failed' | 'none'; optional: boolean }[];
+    untrack(player?: number): number;
 
     /**
      * Writes a quest into the game's own journal. It is a replicated entity, so a player who joins late, reloads or walks away still finds it in their log -- which is what a quest needs and what a one-shot notification cannot do. What the player sees is the game's quest UI: its journal row, its diary page, its objective tracker and its quest-updated toast, all reading a quest node the client builds with the game's own constructor.
      * @param key What the quest is filed under: up to 64 letters, digits, underscores or dashes, unique within its virtual world.
      * @param title The line the journal row shows.
-     * @param options `description` is the diary page, `type` the journal section, `objectives` the lines under it, `player` the network id of the one player it belongs to, and `announce` whether to raise the toast.
+     * @param options `description` is the diary page, `type` the journal section, `objectives` the lines under it -- each with an optional world `position` the game marks on the map and compass while the quest is followed -- `player` the network id of the one player it belongs to, `announce` whether to raise the toast, and `track` whether its recipients start following it.
      * @param virtualWorld Optional virtual world the quest belongs to; omitted puts it in the global one.
      * @returns The newly written quest handle.
      */
-    static give(key: string, title: string, options?: { description?: string; type?: 'main' | 'side' | 'activity' | 'event' | 'micro' | 'racing'; objectives?: (string | { text: string; progress?: 'active' | 'done' | 'failed'; optional?: boolean })[]; player?: number; announce?: boolean }, virtualWorld?: number): Quest;
+    static give(key: string, title: string, options?: { description?: string; type?: 'main' | 'side' | 'activity' | 'event' | 'micro' | 'racing'; objectives?: (string | { text: string; progress?: 'active' | 'done' | 'failed'; optional?: boolean; position?: Vector3 })[]; player?: number; announce?: boolean; track?: boolean }, virtualWorld?: number): Quest;
 
     /**
      * Lists every replicated quest the server currently has.

package/package.json

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