@kingdomsconnected/types 1.5.3 → 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

@@ -386,6 +386,16 @@ declare global {
      */
     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()`.
      */
@@ -948,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.
      */
@@ -1435,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.
@@ -3156,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.
    */
@@ -3862,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.
      */
@@ -3902,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.
      * 
@@ -4028,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.3",
+  "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": [