@kingdomsconnected/types 1.5.2 → 1.5.4

package/generated/client-api.d.ts

@@ -604,6 +604,11 @@ declare global {
      */
     readonly appearance: Appearance;
 
+    /**
+     * The prop-catalog mesh this player's body is drawn as, by its `objects/...cgf` path, or null while they look like themselves. Published by their own client, so it follows `setDisguise` once they have actually put it on.
+     */
+    readonly disguise: string | null;
+
     /**
      * Whether this player's body has both a pose and a soul, which is what everyone else waits for before spawning a puppet for them. False for the first moments of a connection.
      */
@@ -1304,6 +1309,11 @@ declare global {
      * This machine's own handle for it. Local to this client and to this session -- it is not the network ID and it is not portable, so store `entityGuid` instead. Null for terrain and static geometry.
      */
     entityId: number | null;
+
+    /**
+     * The player whose body it was -- the local player's own included, when `ignoreSelf` is off -- or null for anything else. Found through the body's own entity, so it holds for a disguised player too: their collider is the mesh's size, and a trace that meets the mesh names them.
+     */
+    player: Player | null;
   }
 
   /**
@@ -1782,7 +1792,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.
+   * 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.
    */
   const Camera: {
     /**
@@ -1797,6 +1807,24 @@ declare global {
      * @returns The ray, or null when there is no active view.
      */
     screenRay(options?: { x?: number; y?: number; range?: number }): CameraRay | null;
+
+    /**
+     * 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.
+     * 
+     * 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.
+     * 
+     * There is one view to draw through: `NoClip` cannot start while this holds it, and while `NoClip` flies this waits. It lasts until the session ends.
+     * @param options Where the camera sits, in metres: `distance` back from the body along where the player looks (3.5 by default, 0.3 to 20), `height` of the point it orbits above the body's feet (1.6, up to 5 either way), and `shoulder` to the right of it, negative for the left (0, up to 3 either way). Null hands the view back to the game's own camera. Called again while on, it only moves the camera.
+     */
+    setThirdPerson(options?: { distance?: number; height?: number; shoulder?: number } | null): void;
+
+    /**
+     * Whether `setThirdPerson` is on.
+     * @returns True from `setThirdPerson` until it is turned off, also while it waits for a body or for `NoClip`.
+     */
+    isThirdPerson(): boolean;
   };
 
   /**

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,21 @@ 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];
+
+    /**
+     * Dispatched when a body comes to be inside an enabled area: it walked or rode in, or the area was created, moved, reshaped or enabled around it. The server decides this itself from the pose it already replicates, by the game's own rule for that kind of area, so a client cannot claim it. `matchingVirtualWorld` is false when a script area bound to one world is crossed by a body in another; a level area is in every world.
+     */
+    areaEnter: [area: Area, entity: Player | Horse | Cart | Npc, matchingVirtualWorld: boolean];
+
+    /**
+     * Dispatched when a body stops being inside an area: it walked out, or the area was moved, reshaped, disabled or destroyed. A body that leaves the server entirely -- a player disconnecting, a horse despawned -- raises nothing here; its own event already says it is gone.
+     */
+    areaExit: [area: Area, entity: Player | Horse | Cart | Npc, matchingVirtualWorld: 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()`.
@@ -923,6 +958,11 @@ declare global {
      */
     readonly appearance: Appearance;
 
+    /**
+     * The prop-catalog mesh this player's body is drawn as, by its `objects/...cgf` path, or null while they look like themselves. Published by their own client, so it follows `setDisguise` once they have actually put it on.
+     */
+    readonly disguise: string | null;
+
     /**
      * Whether this player's body has both a pose and a soul, which is what everyone else waits for before spawning a puppet for them. False for the first moments of a connection.
      */
@@ -1410,6 +1450,19 @@ declare global {
      */
     heal(options?: { health?: number | boolean; injuries?: boolean; poisons?: boolean; bleeding?: boolean }): boolean;
 
+    /**
+     * Draws this player as a static mesh instead of themselves -- a barrel, a haystack, a cart wheel -- on their own screen and on everybody else's. It is state: a player who streams in or joins sees it too, and it lasts until the next call.
+     * 
+     * Only the look and the collision change. The body is hidden rather than replaced, and its collision cylinder is resized around the mesh, so the player walks and is traced against in roughly the mesh's shape -- a client's `World.raycast` with `mode: "anything"` finds them where the mesh is drawn, and says which player it found. The mesh turns with the body. They keep everything else a person has: they can still be hurt, bleed and die, and nothing stops them drawing a weapon, which a gamemode that does not want that has to take away.
+     * 
+     * The game's own camera sits in the head, which the mesh now covers: pair this with the client's `Camera.setThirdPerson` for the disguised player. Nametags are not touched; `setNametagVisible` is the call for that. NPCs still see a person.
+     * 
+     * The owning client is authoritative for its body, so this is a request that lands on their next frame; `player.disguise` reads what they actually have on.
+     * @param model A mesh from the prop catalog, by its `objects/...cgf` path or its file stem -- anything `Prop.spawn` takes. Null puts the player back in their own body.
+     * @returns True when the request went out; false for a player with no connection to ask. Throws for a model the catalog does not carry.
+     */
+    setDisguise(model: string | null): boolean;
+
     /**
      * Takes this player out of whatever saddle they are in: their own client gets them off, and `horseDismount` is raised.
      * @returns The horse they were taken off, or null when they were not riding one.
@@ -1540,7 +1593,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 +2042,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 +2750,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.
    */
@@ -3013,6 +3184,173 @@ declare global {
 
   interface Blip extends Entity {}
 
+  /** */
+  interface LevelEditDefinition {
+    /**
+     * What the object is; a brush when omitted. A brush has no identity of its own, so it is found by its mesh and where the level put it; a level entity by its EntityGuid.
+     */
+    kind: 'brush' | 'entity' | undefined;
+
+    /**
+     * A brush's mesh path, `objects/...cgf`, as the World Builder shows it; required for a brush. An entity's name, kept for reading only.
+     */
+    name: string | undefined;
+
+    /**
+     * An entity's level EntityGuid as sixteen hex digits; required for an entity.
+     */
+    guid: string | undefined;
+
+    /**
+     * An entity's class, kept for reading only.
+     */
+    class: string | undefined;
+
+    /**
+     * Where the level put the object: its pivot, matched within 5 cm. A brush's key, with its mesh.
+     */
+    at: Vector3 | number[];
+
+    /**
+     * Whether it is taken out of the world: not drawn and not solid.
+     */
+    hidden: boolean | undefined;
+
+    /**
+     * Where it stands instead; present, the edit is a move.
+     */
+    position: Vector3 | number[] | undefined;
+
+    /**
+     * A move's orientation: a Quaternion, {x, y, z, w} or [x, y, z, w]. None when omitted.
+     */
+    rotation: Quaternion | number[] | undefined;
+
+    /**
+     * A move's scale per axis, from 0.01 to 100. None when omitted.
+     */
+    scale: Vector3 | number[] | undefined;
+  }
+
+  /**
+   * One change the server makes, for every player, to an object the level itself placed -- a brush or a level entity taken out of the world, moved, or both. It is what a World Builder map's `world` array carries.
+   */
+  class LevelEdit {
+    /**
+     * Wraps an edit the server already holds; use LevelEdit.apply or LevelEdit.applyMap to make one.
+     * @param id Network entity identifier.
+     */
+    constructor(id: number);
+
+    /**
+     * Immutable network entity identifier.
+     */
+    readonly id: number;
+
+    /**
+     * False once the edit has been restored; every other read then returns its empty value.
+     */
+    readonly exists: boolean;
+
+    /**
+     * Whether the object is a brush, found by its mesh and where the level put it, or a level entity, found by its EntityGuid.
+     */
+    readonly kind: 'brush' | 'entity';
+
+    /**
+     * A brush's mesh path, or the name the level gives the entity.
+     */
+    readonly name: string;
+
+    /**
+     * An entity's level EntityGuid as sixteen lowercase hex digits; empty for a brush.
+     */
+    readonly guid: string;
+
+    /**
+     * The virtual world whose players see the edit, fixed when it was applied.
+     */
+    readonly virtualWorld: number;
+
+    /**
+     * Whether the object is taken out of the world: not drawn and not solid. Assignment takes it out or puts it back for every player, keeping any move.
+     */
+    hidden: boolean;
+
+    /**
+     * Whether the object stands somewhere other than where the level placed it; `move` and `clearMove` change it.
+     */
+    readonly moved: boolean;
+
+    /**
+     * Formats this edit for logging and debugging.
+     * @returns Its id, kind, object and what it does to it.
+     */
+    toString(): string;
+
+    /**
+     * Moves the object for every player, collision included.
+     * @param position Where the object stands instead.
+     * @param rotation Its orientation: a Quaternion, or Euler angles in degrees. Left out, it keeps the last move's.
+     * @param scale A uniform scale or one per axis, from 0.01 to 100. Left out, it keeps the last move's.
+     * @returns False for a gone edit or a transform that is not finite.
+     */
+    move(position: Vector3, rotation?: Quaternion | Vector3, scale?: number | Vector3): boolean;
+
+    /**
+     * Puts the object back where the level placed it, keeping it out of the world if the edit takes it out.
+     */
+    clearMove(): void;
+
+    /**
+     * Drops the edit: every player gets the object back exactly as the level had it, collision included.
+     */
+    restore(): void;
+
+    /**
+     * The definition `LevelEdit.apply` takes to make this edit again, which is what a script saves: the server keeps nothing past a restart. It is one entry of a World Builder map's `world` array.
+     * @returns Null once the edit is gone.
+     */
+    toJSON(): LevelEditDefinition | null;
+
+    /**
+     * Takes an object the level placed out of the world, or moves it, for every player in the virtual world -- whenever they join, and however far away they are. Collision goes with it. An edit already made to the same object in that world is restated rather than doubled, so applying one twice changes nothing. Kept in memory only: apply it again on boot.
+     * @param definition The object and what to do to it, in the format of one entry of a World Builder map's `world` array.
+     * @param virtualWorld Optional virtual world whose players see it; the global one when omitted.
+     * @returns The edit. Throws for a definition no client could find the object by.
+     */
+    static apply(definition: LevelEditDefinition, virtualWorld?: number): LevelEdit;
+
+    /**
+     * Applies every entry of a map's `world` array, which is how edits made in the World Builder reach every player instead of being loaded by hand on each.
+     * @param map A World Builder map saved from the editor, as its JSON text or the parsed object. Only its `world` array is read: its placed objects are `Prop.spawn`'s, its areas `Area.create`'s.
+     * @param virtualWorld Optional virtual world whose players see the edits; the global one when omitted.
+     * @returns One edit per entry, in the map's order. Throws, naming the entry, for one no client could find the object by.
+     */
+    static applyMap(map: string | Record<string, unknown>, virtualWorld?: number): LevelEdit[];
+
+    /**
+     * Lists every edit the server currently has.
+     * @param virtualWorld Optional virtual world to list; omitted lists every one of them.
+     * @returns One handle per live edit, in no particular order.
+     */
+    static all(virtualWorld?: number): LevelEdit[];
+
+    /**
+     * Looks an edit up by its network entity ID.
+     * @param id Network entity identifier.
+     * @returns The edit, or null when no live edit has that ID.
+     */
+    static getById(id: number): LevelEdit | null;
+
+    /**
+     * Drops edits, giving every player the objects back as the level had them.
+     * @param virtualWorld Optional virtual world to clear; omitted clears every one of them.
+     * @returns How many edits were dropped.
+     */
+    static restoreAll(virtualWorld?: number): number;
+  }
+
   /**
    * A server-owned NPC: spawned by a resource, simulated by whichever client is nearest.
    */
@@ -3388,30 +3726,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.
@@ -3705,6 +4057,11 @@ declare global {
      */
     readonly lockpickable: boolean;
 
+    /**
+     * The level areas that link this door as one of their `crime_door`s -- the house, workshop or storage room it belongs to, as the level itself records it. Nothing is inferred from where the door stands.
+     */
+    readonly areas: Area[];
+
     /**
      * Whether the level builds this door locked, which is the state it has at boot.
      */
@@ -3745,6 +4102,13 @@ declare global {
      */
     static find(guid: string, virtualWorld?: number): Door | null;
 
+    /**
+     * Lists the doors the level links to an area as its `crime_door`s, with their GUID, name, position and link type, straight from the level catalog -- so a door that no client has reported yet is listed too. Pass a `guid` to `Door.find` for the live handle and its `locked` state. Only native links: a script area has none.
+     * @param areaId The area's id, as `area.id` prints it.
+     * @returns The doors; empty for an unknown area or one with no links.
+     */
+    static getForArea(areaId: string): AreaDoor[];
+
     /**
      * Asks a player's client which door their body is standing at. The server knows every door the level places but has no world to measure distances in, so this is how a command finds the door in front of a player, and the answer is what that client sees now rather than what the replica last carried.
      * 
@@ -3871,6 +4235,294 @@ declare global {
 
   interface Gate extends Entity {}
 
+  /** */
+  interface AreaDefinition {
+    /**
+     * The area's identity, unique among script areas. It may not be sixteen hex digits, which is how a level area's GUID reads.
+     */
+    id: string;
+
+    /**
+     * A readable name; the id when omitted.
+     */
+    name: string | undefined;
+
+    /**
+     * CryEngine's own area shapes: `AreaBox`, `AreaShape` (a closed polygon with a height) and `AreaSphere`.
+     */
+    type: 'box' | 'shape' | 'sphere';
+
+    /**
+     * Where the shape is placed from; the origin when omitted.
+     */
+    position: Vector3 | undefined;
+
+    /**
+     * The shape's orientation: a Quaternion or {x, y, z, w}, or Euler angles in degrees.
+     */
+    rotation: Quaternion | Vector3 | undefined;
+
+    /**
+     * box: the corner nearest negative infinity, relative to `position` before rotation.
+     */
+    min: Vector3 | undefined;
+
+    /**
+     * box: the opposite corner. Every component must be above `min`'s.
+     */
+    max: Vector3 | undefined;
+
+    /**
+     * shape: 3 to 256 corners relative to `position` before rotation, closed back to the first. As in the engine, the floor is the lowest corner.
+     */
+    points: Vector3[] | undefined;
+
+    /**
+     * shape: how far above its lowest corner the area reaches; 0, the default, for no ceiling.
+     */
+    height: number | undefined;
+
+    /**
+     * sphere: its radius around `position`.
+     */
+    radius: number | undefined;
+
+    /**
+     * Free-form labels, found again with `Area.withLabel`.
+     */
+    labels: string[] | undefined;
+
+    /**
+     * Anything JSON can hold, kept on the area for scripts.
+     */
+    metadata: Record<string, unknown> | undefined;
+
+    /**
+     * The one virtual world it belongs to; every world when omitted.
+     */
+    virtualWorld: number | undefined;
+
+    /**
+     * Whether it starts enabled; true when omitted.
+     */
+    enabled: boolean | undefined;
+  }
+
+  /** */
+  interface AreaDoor {
+    /**
+     * The door's level EntityGuid as hex, which `Door.find` takes.
+     */
+    guid: string;
+
+    /**
+     * The entity name the level gives the door.
+     */
+    name: string;
+
+    /**
+     * Where the level places the door.
+     */
+    position: Vector3;
+
+    /**
+     * The `crime_doorKind` the level gives the link: the way in, an inner door, or a storage room's.
+     */
+    link: 'entrance' | 'basic' | 'storage';
+  }
+
+  /**
+   * Handle for one area: one of the level's own gameplay areas, or one a script or the World Builder drew. The server tests who is inside itself, by the game's own rule for that kind of area.
+   */
+  class Area {
+    /**
+     * Wraps an area handle the server already holds; use Area.create, Area.getById or the lookups to get one.
+     * @param handle Internal area handle.
+     */
+    constructor(handle: number);
+
+    /**
+     * False once a script area has been destroyed; every other read then returns its empty value.
+     */
+    readonly exists: boolean;
+
+    /**
+     * The stable identity to store an area under. A level area's is its EntityGuid as sixteen lowercase hex digits, the same on every machine and every boot, as `door.guid` prints a door's; a script area's is the id it was created with.
+     */
+    readonly id: string;
+
+    /**
+     * Whether the level placed it or a script built it.
+     */
+    readonly kind: 'level' | 'script';
+
+    /**
+     * A level area's entity class -- a `TriggerArea` prism, an `AreaUnion` of them, or a `SmartAreaShape` -- or a script area's shape.
+     */
+    readonly type: 'TriggerArea' | 'AreaUnion' | 'SmartAreaShape' | 'box' | 'shape' | 'sphere';
+
+    /**
+     * The level's entity name, or the script area's name. Only a script area's can be changed.
+     */
+    name: string;
+
+    /**
+     * The level's own `Label` values -- `private`, `personal`, `interior`, `prohibited`, `castle` and the rest the game's AI reads -- or a script area's labels. Only a script area's can be changed.
+     */
+    labels: string[];
+
+    /**
+     * Whatever a script keeps on a script area: ownership, a type, rules. Stored as JSON, so read it, change it and assign it back. Always empty on a level area.
+     */
+    metadata: Record<string, unknown>;
+
+    /**
+     * Whether crossings are raised and the lookups find it. Switching it off raises `areaExit` for everyone inside on the next tick; switching it on, `areaEnter`. Works on level areas too.
+     */
+    enabled: boolean;
+
+    /**
+     * The one virtual world a script area belongs to, or null for all of them. A body in another world still crosses it, with `matchingVirtualWorld` false. A level area is in every world.
+     */
+    virtualWorld: number | null;
+
+    /**
+     * A script area's origin, which its shape is placed from; assignment moves it. A level area's is the centre of its bounds.
+     */
+    position: Vector3;
+
+    /**
+     * A script area's orientation; assignment turns it. A level area's shape is already in world space, so its rotation is the identity.
+     */
+    rotation: Quaternion;
+
+    /**
+     * How far above its lowest point a prism reaches, in metres; 0 for a shape with no ceiling. A TriggerArea's comes from the level's baked prism.
+     */
+    readonly height: number;
+
+    /**
+     * For a SmartAreaShape bound to one of the game's map locations, that location's English name, e.g. a settlement. Empty otherwise.
+     */
+    readonly location: string;
+
+    /**
+     * The world box around the area. An area with no ceiling reaches far above and below.
+     */
+    readonly bounds: { min: Vector3; max: Vector3 };
+
+    /**
+     * For an AreaUnion, the TriggerAreas it joins; it contains whatever one of them does. Empty otherwise.
+     */
+    readonly members: Area[];
+
+    /**
+     * The doors the level itself links to this area as its `crime_door`s, which is how the game knows a house's doors. Only native links: nothing is inferred from where a door stands.
+     */
+    readonly doors: AreaDoor[];
+
+    /**
+     * Every player inside as of the last tick, in any world.
+     */
+    readonly players: Player[];
+
+    /**
+     * Every body inside as of the last tick: players, horses, carts and server NPCs.
+     */
+    readonly occupants: (Player | Horse | Cart | Npc)[];
+
+    /**
+     * Formats this area for logging and debugging.
+     * @returns Its id, kind, type and name.
+     */
+    toString(): string;
+
+    /**
+     * Tests a position the way the game tests its own areas, whether or not the area is enabled and in whatever world.
+     * @param position The world position to test.
+     * @returns True when the position is inside.
+     */
+    contains(position: Vector3): boolean;
+
+    /**
+     * Tests where a body stands right now, and in which world: an area bound to another virtual world does not contain it. This is containment only -- whether the game considers the player to be trespassing is decided by its own crime system on the player's client.
+     * @param player The body to test; a player who has not reported a pose yet is never inside.
+     * @returns True when the body is inside.
+     */
+    containsPlayer(player: Player | Horse | Cart | Npc): boolean;
+
+    /**
+     * Moves, turns or reshapes a script area. Bodies standing where it now is, or was, get their `areaEnter` and `areaExit` on the next tick. A level area cannot be reshaped.
+     * @param definition The shape fields to change; any left out keep their value. `id`, `labels`, `metadata` and the rest are ignored here.
+     * @returns False for a level area, a gone one, or a shape the engine could not build.
+     */
+    setShape(definition: Partial<AreaDefinition>): boolean;
+
+    /**
+     * Removes a script area. Every body still inside gets its `areaExit` first, while the handle still resolves.
+     * @returns False for a level area or one already gone.
+     */
+    destroy(): boolean;
+
+    /**
+     * The definition `Area.create` takes to build this area again, which is what a script saves: the server keeps nothing past a restart. It is the format the World Builder exports too.
+     * @returns Null for a level area, which the level always builds.
+     */
+    toJSON(): AreaDefinition | null;
+
+    /**
+     * Builds a script area. Bodies already standing in it get `areaEnter` on the next tick. Kept in memory only: save `area.toJSON()` wherever the resource keeps its data, and create it again on boot.
+     * @param definition The area to build, in the format `area.toJSON()` and the World Builder export write.
+     * @returns The new area. Throws for an id already taken or a shape the engine could not build.
+     */
+    static create(definition: AreaDefinition): Area;
+
+    /**
+     * Looks an area up by its stable identity.
+     * @param id A script area's id, or a level area's GUID in hex as `area.definition.id` prints it.
+     * @returns The area, or null when there is none.
+     */
+    static getById(id: string): Area | null;
+
+    /**
+     * Every enabled area containing a position, level and script alike.
+     * @param position The world position to test.
+     * @param virtualWorld Optional world; when given, a script area bound to another world is left out.
+     * @returns The areas, in no particular order.
+     */
+    static getAt(position: Vector3, virtualWorld?: number): Area[];
+
+    /**
+     * Every enabled area the body stands in right now, in its own world.
+     * @param player The body whose position and world to test.
+     * @returns The areas; empty for a player who has not reported a pose yet.
+     */
+    static getAtPlayer(player: Player | Horse | Cart | Npc): Area[];
+
+    /**
+     * Every area whose bounds come within a radius of a position, enabled or not.
+     * @param position Where to look from.
+     * @param radius How far, in metres, from the area's bounds.
+     * @param virtualWorld Optional world; when given, a script area bound to another world is left out.
+     * @returns The areas, nearest first.
+     */
+    static nearby(position: Vector3, radius: number, virtualWorld?: number): Area[];
+
+    /**
+     * Every area carrying a label, such as `private` or `castle`.
+     * @param label The label, compared without regard to case.
+     * @returns The areas, level ones first.
+     */
+    static withLabel(label: string): Area[];
+
+    /**
+     * Every area the server knows.
+     * @param kind Optional: only the level's areas, or only script ones.
+     * @returns The areas, level ones first.
+     */
+    static all(kind?: 'level' | 'script'): Area[];
+  }
+
   /**
    * Replicated container handle: one a script spawned, or one the level places.
    */

package/package.json

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