xray16 1.3.4 → 1.5.0

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

@@ -1,98 +1,153 @@
-declare module "xray16" {
-  /**
-   * @source C++ class CArtefact : CGameObject
-   * @customConstructor CArtefact
-   * @group xr_artefact
-   */
-  export class CArtefact extends CGameObject {
-    public constructor();
-
-    public FollowByPath(a: string, b: i32, c: vector): void;
-    public GetAfRank(): u8;
-    public SwitchVisibility(to: boolean): void;
-  }
-
-  /**
-   * @source C++ class CZudaArtefact : CArtefact
-   * @customConstructor CZudaArtefact
-   * @group xr_artefact
-   */
-  export class CZudaArtefact extends CArtefact {}
-
-  /**
-   * @source C++ class CThornArtefact : CArtefact
-   * @customConstructor CThornArtefact
-   * @group xr_artefact
-   */
-  export class CThornArtefact extends CArtefact {}
-
-  /**
-   * @source C++ class CBastArtefact : CArtefact
-   * @customConstructor CBastArtefact
-   * @group xr_artefact
-   */
-  export class CBastArtefact extends CArtefact {}
-
-  /**
-   * @source C++ class CBlackDrops : CArtefact
-   * @customConstructor CBlackDrops
-   * @group xr_artefact
-   */
-  export class CBlackDrops extends CArtefact {}
-
-  /**
-   * @source C++ class CBlackGraviArtefact : CArtefact
-   * @customConstructor CBlackGraviArtefact
-   * @group xr_artefact
-   */
-  export class CBlackGraviArtefact extends CArtefact {}
-
-  /**
-   * @source C++ class CDummyArtefact : CArtefact
-   * @customConstructor CDummyArtefact
-   * @group xr_artefact
-   */
-  export class CDummyArtefact extends CArtefact {}
-
-  /**
-   * @source C++ class CElectricBall : CArtefact
-   * @customConstructor CElectricBall
-   * @group xr_artefact
-   */
-  export class CElectricBall extends CArtefact {}
-
-  /**
-   * @source C++ class CFadedBall : CArtefact
-   * @customConstructor CFadedBall
-   * @group xr_artefact
-   */
-  export class CFadedBall extends CArtefact {}
-
-  /**
-   * @source C++ class CGalantineArtefact : CArtefact
-   * @customConstructor CGalantineArtefact
-   * @group xr_artefact
-   */
-  export class CGalantineArtefact extends CArtefact {}
-
-  /**
-   * @source C++ class CGraviArtefact : CArtefact
-   * @customConstructor CGraviArtefact
-   * @group xr_artefact
-   */
-  export class CGraviArtefact extends CArtefact {}
-
-  /**
-   * @source C++ class CMercuryBall : CArtefact
-   * @customConstructor CMercuryBall
-   * @group xr_artefact
-   */
-  export class CMercuryBall extends CArtefact {}
-
-  /**
-   * @source C++ class CRustyHairArtefact : CArtefact
-   * @customConstructor CRustyHairArtefact
-   * @group xr_artefact
-   */
-  export class CRustyHairArtefact extends CArtefact {}
-}
+declare module "xray16" {
+  /**
+   * Client-side artefact object.
+   *
+   * @source C++ class CArtefact : CGameObject
+   * @customConstructor CArtefact
+   * @group xr_artefact
+   *
+   * @remarks
+   * Scripts usually reach this wrapper through `game_object.cast_Artefact()` after checking `is_artefact()`.
+   */
+  export class CArtefact extends CGameObject {
+    /**
+     * Create an artefact object wrapper.
+     */
+    public constructor();
+
+    /**
+     * Move the artefact along a patrol path.
+     *
+     * @remarks
+     * Requires a patrol path with the given name. The point index must refer to an existing path point.
+     *
+     * @param path_name - Patrol path name.
+     * @param point_index - Starting path point index.
+     * @param position - Initial position.
+     */
+    public FollowByPath(path_name: string, point_index: i32, position: vector): void;
+
+    /**
+     * @returns Artefact rank used by detectors and inventory UI.
+     */
+    public GetAfRank(): u8;
+
+    /**
+     * Show or hide the artefact.
+     *
+     * @remarks
+     * This changes the artefact's client visibility; it does not spawn or destroy the object.
+     *
+     * @param is_visible - New visibility state.
+     */
+    public SwitchVisibility(is_visible: boolean): void;
+  }
+
+  /**
+   * Client object binding for `CZudaArtefact` artefacts.
+   *
+   * @source C++ class CZudaArtefact : CArtefact
+   * @customConstructor CZudaArtefact
+   * @group xr_artefact
+   */
+  export class CZudaArtefact extends CArtefact {}
+
+  /**
+   * Client object binding for `CThornArtefact` artefacts.
+   *
+   * @source C++ class CThornArtefact : CArtefact
+   * @customConstructor CThornArtefact
+   * @group xr_artefact
+   */
+  export class CThornArtefact extends CArtefact {}
+
+  /**
+   * Client object binding for `CBastArtefact` artefacts.
+   *
+   * @source C++ class CBastArtefact : CArtefact
+   * @customConstructor CBastArtefact
+   * @group xr_artefact
+   */
+  export class CBastArtefact extends CArtefact {}
+
+  /**
+   * Client object binding for `CBlackDrops` artefacts.
+   *
+   * @source C++ class CBlackDrops : CArtefact
+   * @customConstructor CBlackDrops
+   * @group xr_artefact
+   */
+  export class CBlackDrops extends CArtefact {}
+
+  /**
+   * Client object binding for `CBlackGraviArtefact` artefacts.
+   *
+   * @source C++ class CBlackGraviArtefact : CArtefact
+   * @customConstructor CBlackGraviArtefact
+   * @group xr_artefact
+   */
+  export class CBlackGraviArtefact extends CArtefact {}
+
+  /**
+   * Client object binding for `CDummyArtefact` artefacts.
+   *
+   * @source C++ class CDummyArtefact : CArtefact
+   * @customConstructor CDummyArtefact
+   * @group xr_artefact
+   */
+  export class CDummyArtefact extends CArtefact {}
+
+  /**
+   * Client object binding for `CElectricBall` artefacts.
+   *
+   * @source C++ class CElectricBall : CArtefact
+   * @customConstructor CElectricBall
+   * @group xr_artefact
+   */
+  export class CElectricBall extends CArtefact {}
+
+  /**
+   * Client object binding for `CFadedBall` artefacts.
+   *
+   * @source C++ class CFadedBall : CArtefact
+   * @customConstructor CFadedBall
+   * @group xr_artefact
+   */
+  export class CFadedBall extends CArtefact {}
+
+  /**
+   * Client object binding for `CGalantineArtefact` artefacts.
+   *
+   * @source C++ class CGalantineArtefact : CArtefact
+   * @customConstructor CGalantineArtefact
+   * @group xr_artefact
+   */
+  export class CGalantineArtefact extends CArtefact {}
+
+  /**
+   * Client object binding for `CGraviArtefact` artefacts.
+   *
+   * @source C++ class CGraviArtefact : CArtefact
+   * @customConstructor CGraviArtefact
+   * @group xr_artefact
+   */
+  export class CGraviArtefact extends CArtefact {}
+
+  /**
+   * Client object binding for `CMercuryBall` artefacts.
+   *
+   * @source C++ class CMercuryBall : CArtefact
+   * @customConstructor CMercuryBall
+   * @group xr_artefact
+   */
+  export class CMercuryBall extends CArtefact {}
+
+  /**
+   * Client object binding for `CRustyHairArtefact` artefacts.
+   *
+   * @source C++ class CRustyHairArtefact : CArtefact
+   * @customConstructor CRustyHairArtefact
+   * @group xr_artefact
+   */
+  export class CRustyHairArtefact extends CArtefact {}
+}

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

@@ -1,76 +1,207 @@
-declare module "xray16" {
-  /**
-   * @source C++ class DLL_Pure
-   * @customConstructor DLL_Pure
-   * @group xr_core
-   */
-  export class DLL_Pure extends EngineBinding {
-    protected constructor();
-  }
-
-  /**
-   * @source C++ class IRender_Visual
-   * @group xr_client_object
-   */
-  export interface IXR_IRender_Visual {
-    dcast_PKinematicsAnimated(): IKinematicsAnimated;
-  }
-
-  /**
-   * @source C++ class CGameObject : DLL_Pure, ISheduled, ICollidable, IRenderable
-   * @customConstructor CGameObject
-   * @group xr_client_object
-   */
-  export class CGameObject extends DLL_Pure {
-    public Visual(): IXR_IRender_Visual;
-
-    public getEnabled(): boolean;
-
-    public _construct(): DLL_Pure;
-
-    public net_Import(net_packet: net_packet): void;
-
-    public getVisible(): boolean;
-
-    public net_Export(net_packet: net_packet): void;
-
-    public net_Spawn(cse_abstract: cse_abstract): boolean;
-
-    public use(object: CGameObject): boolean;
-  }
-
-  /**
-   * Class to link client side object with script object entity.
-   *
-   * @source C++ class object_binder
-   * @customConstructor object_binder
-   * @group xr_client_object
-   */
-  export class object_binder<T = game_object> extends EngineBinding {
-    public readonly object: T;
-
-    public constructor(object: T);
-
-    public save(packet: net_packet): void;
-
-    public load(reader: reader): void;
-
-    public update(delta: u32): void;
-
-    public reload(section: string): void;
-
-    public reinit(): void;
-
-    public net_export(net_packet: net_packet): void;
-
-    public net_save_relevant(): boolean;
-
-    public net_destroy(): void;
-
-    public net_Relcase(object: T): void;
-
-    public net_spawn(object: cse_alife_object): boolean;
-
-    public net_import(net_packet: net_packet): void;
-  }
-}
+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;
+  }
+
+  /**
+   * Class to link client side object with script object entity.
+   *
+   * @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;
+  }
+}