xray16 1.4.0 → 1.5.0

package/types/xr_object/client/xr_client_object.d.ts

@@ -1,41 +1,110 @@
 declare module "xray16" {
   /**
+   * Base engine object exposed for compatibility with script binders.
+   *
    * @source C++ class DLL_Pure
    * @customConstructor DLL_Pure
    * @group xr_core
+   *
+   * @remarks
+   * Base for engine-owned client objects. Scripts normally receive derived objects from xray callbacks or casts.
    */
   export class DLL_Pure extends EngineBinding {
+    /**
+     * Engine-created base object.
+     */
     protected constructor();
   }
 
   /**
+   * Render visual handle for client objects.
+   *
    * @source C++ class IRender_Visual
    * @group xr_client_object
+   *
+   * @remarks
+   * Visual handles are owned by the object. Treat returned cast interfaces as borrowed engine references.
    */
   export interface IXR_IRender_Visual {
+    /**
+     * Cast the visual to animated kinematics when supported.
+     *
+     * @remarks
+     * Runtime can return `null` when the visual is not animated even though older declarations expose a non-null type.
+     *
+     * @returns Animated kinematics interface.
+     */
     dcast_PKinematicsAnimated(): IKinematicsAnimated;
   }
 
   /**
+   * Base client-side game object.
+   *
    * @source C++ class CGameObject : DLL_Pure, ISheduled, ICollidable, IRenderable
    * @customConstructor CGameObject
    * @group xr_client_object
+   *
+   * @remarks
+   * Client-side object state is engine-owned. Use this wrapper for low-level engine callbacks; gameplay scripts usually
+   * work with `game_object` instead.
    */
   export class CGameObject extends DLL_Pure {
+    /**
+     * @returns Render visual assigned to the object.
+     */
     public Visual(): IXR_IRender_Visual;
 
+    /**
+     * @returns Whether the object is enabled in the client object loop.
+     */
     public getEnabled(): boolean;
 
+    /**
+     * Construct engine-side object state.
+     *
+     * @remarks
+     * Lifecycle hook used by the engine. Calling it from gameplay scripts can reinitialize native state unexpectedly.
+     *
+     * @returns Constructed base object.
+     */
     public _construct(): DLL_Pure;
 
+    /**
+     * Import network state from a packet.
+     *
+     * @param net_packet - Source network packet.
+     */
     public net_Import(net_packet: net_packet): void;
 
+    /**
+     * @returns Whether the object is visible.
+     */
     public getVisible(): boolean;
 
+    /**
+     * Export network state to a packet.
+     *
+     * @param net_packet - Destination network packet.
+     */
     public net_Export(net_packet: net_packet): void;
 
+    /**
+     * Spawn the client object from its server object.
+     *
+     * @remarks
+     * Lifecycle hook used during network spawn. Return `false` to reject spawn in custom subclasses.
+     *
+     * @param cse_abstract - Server object used for spawn data.
+     * @returns Whether spawn succeeded.
+     */
     public net_Spawn(cse_abstract: cse_abstract): boolean;
 
+    /**
+     * Use another object through the engine interaction path.
+     *
+     * @param object - Object being used.
+     * @returns Whether the use action was handled.
+     */
     public use(object: CGameObject): boolean;
   }
 
@@ -45,32 +114,94 @@ declare module "xray16" {
    * @source C++ class object_binder
    * @customConstructor object_binder
    * @group xr_client_object
+   *
+   * @remarks
+   * Script binders are callbacks attached to a `game_object`. The engine calls lifecycle methods; scripts usually
+   * override them in subclasses instead of invoking them directly.
    */
   export class object_binder<T = game_object> extends EngineBinding {
+    /**
+     * Script game object controlled by this binder.
+     */
     public readonly object: T;
 
+    /**
+     * @param object - Script game object controlled by this binder.
+     */
     public constructor(object: T);
 
+    /**
+     * Save binder state.
+     *
+     * @param packet - Destination save packet.
+     */
     public save(packet: net_packet): void;
 
+    /**
+     * Load binder state.
+     *
+     * @param reader - Source save reader.
+     */
     public load(reader: reader): void;
 
+    /**
+     * Update binder logic.
+     *
+     * @param delta - Time since last update in milliseconds.
+     */
     public update(delta: u32): void;
 
+    /**
+     * Reload binder configuration.
+     *
+     * @param section - Object config section.
+     */
     public reload(section: string): void;
 
+    /**
+     * Reinitialize binder runtime state.
+     */
     public reinit(): void;
 
+    /**
+     * Export binder network state.
+     *
+     * @param net_packet - Destination network packet.
+     */
     public net_export(net_packet: net_packet): void;
 
+    /**
+     * Decide whether binder state should be saved over the network.
+     *
+     * @returns Whether the state is relevant for network save.
+     */
     public net_save_relevant(): boolean;
 
+    /**
+     * Handle client object destruction.
+     */
     public net_destroy(): void;
 
+    /**
+     * Release references to a game object.
+     *
+     * @param object - Object being released.
+     */
     public net_Relcase(object: T): void;
 
+    /**
+     * Handle network spawn.
+     *
+     * @param object - Server object used for spawn data.
+     * @returns Whether spawn succeeded.
+     */
     public net_spawn(object: cse_alife_object): boolean;
 
+    /**
+     * Import binder network state.
+     *
+     * @param net_packet - Source network packet.
+     */
     public net_import(net_packet: net_packet): void;
   }
 }

package/types/xr_object/client/xr_creature.d.ts

@@ -1,40 +1,71 @@
 declare module "xray16" {
   /**
+   * Client object binding for `CEntityAlive`.
+   *
    * @source C++ class CEntityAlive : public CEntity
    * @customConstructor CEntityAlive
    * @group xr_creature
+   *
+   * @remarks
+   * Base wrapper for alive objects. Use `game_object.is_entity_alive()` or a narrower predicate before calling
+   * alive-object methods from the shared `game_object` surface.
    */
   export class CEntityAlive extends CGameObject {}
 
   /**
+   * Client object binding for `CActor`.
+   *
    * @source C++ class CActor : CGameObject
    * @customConstructor CActor
    * @group xr_creature
+   *
+   * @remarks
+   * Actor-only APIs on `game_object` require the current object to be the player actor, not just any alive entity.
    */
   export class CActor extends CGameObject {}
 
   /**
+   * Client object binding for `CCustomMonster`.
+   *
    * @source C++ class CCustomMonster : CGameObject
    * @customConstructor CCustomMonster
    * @group xr_creature
+   *
+   * @remarks
+   * Base wrapper for custom monsters. Monster sound, range, memory, home, and enemy-transfer helpers require this
+   * family or one of its subclasses.
    */
   export class CCustomMonster extends CGameObject {}
 
   /**
+   * Client object binding for `CInventoryOwner`.
+   *
    * @source C++ class CInventoryOwner : CGameObject
    * @customConstructor CInventoryOwner
    * @group xr_creature
+   *
+   * @remarks
+   * Inventory-owner APIs cover NPCs, traders, corpses, boxes, and the actor depending on runtime class. Check the
+   * object kind before assuming dialog, trade, belt, or inventory-box behavior exists.
    */
   export class CInventoryOwner extends CGameObject {}
 
   /**
+   * Client object binding for `CInventoryItem`.
+   *
    * @source C++ class CInventoryItem : CGameObject
    * @customConstructor CInventoryItem
    * @group xr_creature
+   *
+   * @remarks
+   * Base wrapper for inventory items. Item condition, cost, upgrades, and slot behavior depend on the concrete item
+   * class.
    */
   export class CInventoryItem extends CGameObject {}
 
   /**
+   * Client object binding for `CZombie`.
+   *
    * @source C++ class CZombie : CGameObject
    * @customConstructor CZombie
    * @group xr_creature
@@ -42,6 +73,8 @@ declare module "xray16" {
   export class CZombie extends CGameObject {}
 
   /**
+   * Client object binding for `CController`.
+   *
    * @source C++ class CController : CGameObject
    * @customConstructor CController
    * @group xr_creature
@@ -49,6 +82,8 @@ declare module "xray16" {
   export class CController extends CGameObject {}
 
   /**
+   * Client object binding for `CTushkano`.
+   *
    * @source C++ class CTushkano : CGameObject
    * @customConstructor CTushkano
    * @group xr_creature
@@ -56,6 +91,8 @@ declare module "xray16" {
   export class CTushkano extends CGameObject {}
 
   /**
+   * Client object binding for `CBurer`.
+   *
    * @source C++ class CBurer : CGameObject
    * @customConstructor CBurer
    * @group xr_creature
@@ -63,6 +100,8 @@ declare module "xray16" {
   export class CBurer extends CGameObject {}
 
   /**
+   * Client object binding for `CCat`.
+   *
    * @source C++ class CCat : CGameObject
    * @customConstructor CCat
    * @group xr_creature
@@ -70,6 +109,8 @@ declare module "xray16" {
   export class CCat extends CGameObject {}
 
   /**
+   * Client object binding for `CChimera`.
+   *
    * @source C++ class CChimera : CGameObject
    * @customConstructor CChimera
    * @group xr_creature
@@ -77,6 +118,8 @@ declare module "xray16" {
   export class CChimera extends CGameObject {}
 
   /**
+   * Client object binding for `CPoltergeist`.
+   *
    * @source C++ class CPoltergeist : CGameObject
    * @customConstructor CPoltergeist
    * @group xr_creature
@@ -84,6 +127,8 @@ declare module "xray16" {
   export class CPoltergeist extends CGameObject {}
 
   /**
+   * Client object binding for `CPseudoGigant`.
+   *
    * @source C++ class CPseudoGigant : CGameObject
    * @customConstructor CPseudoGigant
    * @group xr_creature
@@ -91,6 +136,8 @@ declare module "xray16" {
   export class CPseudoGigant extends CGameObject {}
 
   /**
+   * Client object binding for `CPsyDog`.
+   *
    * @source C++ class CPsyDog : CGameObject
    * @customConstructor CPsyDog
    * @group xr_creature
@@ -98,6 +145,8 @@ declare module "xray16" {
   export class CPsyDog extends CGameObject {}
 
   /**
+   * Client object binding for `CPsyDogPhantom`.
+   *
    * @source C++ class CPsyDogPhantom : CGameObject
    * @customConstructor CPsyDogPhantom
    * @group xr_creature
@@ -105,15 +154,27 @@ declare module "xray16" {
   export class CPsyDogPhantom extends CGameObject {}
 
   /**
+   * Client object binding for `CAI_Bloodsucker`.
+   *
    * @source C++ class CAI_Bloodsucker : CGameObject
    * @customConstructor CAI_Bloodsucker
    * @group xr_creature
+   *
+   * @remarks
+   * Bloodsucker-specific visibility helpers are not valid for other custom monsters.
    */
   export class CAI_Bloodsucker extends CGameObject {
+    /**
+     * Override the bloodsucker visibility state.
+     *
+     * @param value - Visibility state id used by the monster implementation.
+     */
     public force_visibility_state(value: i32): void;
   }
 
   /**
+   * Client object binding for `CAI_Boar`.
+   *
    * @source C++ class CAI_Boar : CGameObject
    * @customConstructor CAI_Boar
    * @group xr_creature
@@ -121,6 +182,8 @@ declare module "xray16" {
   export class CAI_Boar extends CGameObject {}
 
   /**
+   * Client object binding for `CAI_Dog`.
+   *
    * @source C++ class CAI_Dog : CGameObject
    * @customConstructor CAI_Dog
    * @group xr_creature
@@ -128,6 +191,8 @@ declare module "xray16" {
   export class CAI_Dog extends CGameObject {}
 
   /**
+   * Client object binding for `CAI_Flesh`.
+   *
    * @source C++ class CAI_Flesh : CGameObject
    * @customConstructor CAI_Flesh
    * @group xr_creature
@@ -135,6 +200,8 @@ declare module "xray16" {
   export class CAI_Flesh extends CGameObject {}
 
   /**
+   * Client object binding for `CAI_PseudoDog`.
+   *
    * @source C++ class CAI_PseudoDog : CGameObject
    * @customConstructor CAI_PseudoDog
    * @group xr_creature
@@ -142,20 +209,32 @@ declare module "xray16" {
   export class CAI_PseudoDog extends CGameObject {}
 
   /**
+   * Client object binding for `CAI_Stalker`.
+   *
    * @source C++ class CAI_Stalker : CGameObject
    * @customConstructor CAI_Stalker
    * @group xr_creature
+   *
+   * @remarks
+   * Stalker movement, smart-cover, planner, weapon-selection, and dialog helpers require this runtime family.
    */
   export class CAI_Stalker extends CGameObject {}
 
   /**
+   * Client object binding for `CAI_Trader`.
+   *
    * @source C++ class CAI_Trader : CGameObject
    * @customConstructor CAI_Trader
    * @group xr_creature
+   *
+   * @remarks
+   * Trader wrappers are inventory owners with trader-specific animation and sound hooks.
    */
   export class CAI_Trader extends CGameObject {}
 
   /**
+   * Client object binding for `CSnork`.
+   *
    * @source C++ class CSnork : CGameObject
    * @customConstructor CSnork
    * @group xr_creature