xray16 1.4.0 → 1.5.0

package/types/xr_lib/xr_task.d.ts

@@ -1,17 +1,47 @@
 declare module "xray16" {
   /**
+   * Task state and task type constants.
+   *
    * @source C++ class task
    * @customConstructor task
    * @group xr_task
+   *
+   * @remarks
+   * State and type constants share one native export. Use the matching subset for each API.
    */
   export class task {
+    /**
+     * Engine enum value for `task.additional`.
+     */
     public static readonly additional: 1;
+    /**
+     * Engine enum value for `task.completed`.
+     */
     public static readonly completed: 2;
+    /**
+     * Engine enum value for `task.fail`.
+     */
     public static readonly fail: 0;
+    /**
+     * Engine enum value for `task.in_progress`.
+     */
     public static readonly in_progress: 1;
+    /**
+     * Engine enum value for `task.insignificant`.
+     */
+    public static readonly insignificant: 2;
+    /**
+     * Engine enum value for `task.storyline`.
+     */
     public static readonly storyline: 0;
+    /**
+     * Engine enum value for `task.task_dummy`.
+     */
     public static readonly task_dummy: 65535;
 
+    /**
+     * Engine-owned task constants.
+     */
     private constructor();
   }
 
@@ -28,49 +58,191 @@ declare module "xray16" {
   export type TXR_TaskState = EnumeratedStaticsValues<typeof task>;
 
   /**
+   * One objective inside a game task.
+   *
    * @source C++ class SGameTaskObjective
    * @customConstructor SGameTaskObjective
    * @group xr_task
+   *
+   * @remarks
+   * Objective `0` is the task root objective. Additional objectives start at `1`.
    */
   export class SGameTaskObjective {
+    /**
+     * Whether the default map location should be visible for this objective.
+     *
+     * @remarks
+     * This mirrors the native `def_ml_enabled` field used by loaded task objectives.
+     */
+    public def_ml_enabled: boolean;
+
+    /**
+     * @remarks
+     * The objective stores a pointer to `task`; keep the parent task alive while using this objective.
+     *
+     * @param task - Parent task.
+     * @param id - Objective index.
+     */
     public constructor(task: CGameTask, id: i32);
 
+    /**
+     * Get objective index inside the parent task.
+     *
+     * @returns Objective index.
+     */
+    public get_idx(): u16;
+
+    /**
+     * Set objective icon texture.
+     *
+     * @param icon_name - Icon texture or string table id.
+     */
     public set_icon_name(icon_name: string): void;
 
+    /**
+     * @returns Objective icon name, or null when none is set.
+     */
     public get_icon_name<T extends string = string>(): T | null;
 
+    /**
+     * Set objective description text.
+     *
+     * @param description - Description text or string table id.
+     */
     public set_description(description: string): void;
 
+    /**
+     * @returns Objective description text or string table id.
+     */
     public get_description(): string;
 
+    /**
+     * Set objective title.
+     *
+     * @param title - Title text or string table id.
+     */
     public set_title(title: string): void;
 
+    /**
+     * @returns Objective title.
+     */
     public get_title(): string;
 
+    /**
+     * Set encyclopedia article id unlocked with this objective.
+     *
+     * @param id - Encyclopedia article id.
+     */
+    public set_article_id(id: string): void;
+
+    /**
+     * Set encyclopedia article key for this objective.
+     *
+     * @param key - Article key.
+     */
+    public set_article_key(key: string): void;
+
+    /**
+     * Set map spot type used by this objective.
+     *
+     * @param location - Map location type.
+     */
     public set_map_location(location: string): void;
 
+    /**
+     * Add a script function called after objective completion.
+     *
+     * @remarks
+     * Function names are resolved when a script-created objective is added to a task. Missing functions are logged and
+     * then skipped by the engine.
+     *
+     * @param function_name - Script function name.
+     */
     public add_on_complete_func(function_name: string): void;
 
+    /**
+     * Require an info portion for objective completion.
+     *
+     * @param value - Info portion id.
+     */
     public add_complete_info(value: string): void;
 
+    /**
+     * Give an info portion when objective fails.
+     *
+     * @param value - Info portion id.
+     */
     public add_on_fail_info(value: string): void;
 
+    /**
+     * Add a script function called after objective failure.
+     *
+     * @remarks
+     * Function names are resolved when a script-created objective is added to a task. Missing functions are logged and
+     * then skipped by the engine.
+     *
+     * @param function_name - Script function name.
+     */
     public add_on_fail_func(function_name: string): void;
 
+    /**
+     * Give an info portion when objective completes.
+     *
+     * @param value - Info portion id.
+     */
     public add_on_complete_info(value: string): void;
 
+    /**
+     * Add a script predicate used to decide objective completion.
+     *
+     * @remarks
+     * Function names are resolved when a script-created objective is added to a task. Missing functions are logged and
+     * then skipped by the engine.
+     *
+     * @param function_name - Script function name.
+     */
     public add_complete_func(function_name: string): void;
 
+    /**
+     * Add a script predicate used to decide objective failure.
+     *
+     * @remarks
+     * Function names are resolved when a script-created objective is added to a task. Missing functions are logged and
+     * then skipped by the engine.
+     *
+     * @param function_name - Script function name.
+     */
     public add_fail_func(function_name: string): void;
 
+    /**
+     * Require an info portion for objective failure.
+     *
+     * @param value - Info portion id.
+     */
     public add_fail_info(value: string): void;
 
+    /**
+     * @returns Current objective state.
+     */
     public get_state(): TXR_TaskState;
 
+    /**
+     * @returns Task type, such as `task.storyline` or `task.additional`.
+     */
     public get_type(): number; /* ETaskType */
 
+    /**
+     * Set task type.
+     *
+     * @param type - Task type, such as `task.storyline` or `task.additional`.
+     */
     public set_type(type: i32 /* ETaskType */): void;
 
+    /**
+     * Set hint text for the linked map location.
+     *
+     * @param hint - Hint text or string table id.
+     */
     public set_map_hint(hint: string): void;
 
     /**
@@ -83,29 +255,134 @@ declare module "xray16" {
      */
     public get_map_object_id(): u16;
 
+    /**
+     * Replace linked map location data and recreate the spot.
+     *
+     * @remarks
+     * Removes the current linked spot, sets the objective back to `task.in_progress`, then creates a new map spot.
+     *
+     * @param new_map_location - New map location type.
+     * @param new_map_object_id - New target object id.
+     */
     public change_map_location(new_map_location: string, new_map_object_id: u16): void;
 
+    /**
+     * Remove linked map locations.
+     *
+     * @remarks
+     * When `notify` is `false`, the linked map location is removed from the level map manager. The objective then clears
+     * its stored location type and object id.
+     *
+     * @param notify - Whether to notify task manager that the location was released.
+     */
     public remove_map_locations(notify: boolean): void;
 
+    /**
+     * Create the linked map location if the objective has a spot type and object id.
+     *
+     * @remarks
+     * During load, the objective tries to reattach to an existing serializable spot owned by the task. During normal
+     * creation, it creates a new serializable spot and disables its pointer. The objective must already have a map
+     * location type and a valid game object id.
+     *
+     * @param on_load - Whether creation happens during save loading.
+     */
     public create_map_location(on_load: boolean): void;
 
+    /**
+     * Set object id tracked by the objective map spot.
+     *
+     * @param id - Game object id.
+     */
     public set_map_object_id(id: i32): void;
+
+    /**
+     * Shadow of Chernobyl alias for `set_map_object_id`.
+     *
+     * @param id - Game object id.
+     */
+    public set_object_id(id: i32): void;
   }
 
   /**
+   * Game task with one or more objectives.
+   *
    * @source C++ class CGameTask : SGameTaskObjective
    * @customConstructor CGameTask
    * @group xr_task
+   *
+   * @remarks
+   * A task is also its root objective. Methods inherited from `SGameTaskObjective` operate on that root objective.
    */
   export class CGameTask extends SGameTaskObjective {
+    /**
+     * Create an empty game task.
+     */
     public constructor();
 
+    /**
+     * Load task data from configs.
+     *
+     * @remarks
+     * Reads from `gameplay/game_tasks.xml`. Task XML function names are resolved immediately.
+     *
+     * @throws If the task id is missing from `game_tasks.xml` or a referenced task function cannot be resolved.
+     *
+     * @param id - Task id.
+     */
+    public load(id: string): void;
+
+    /**
+     * @returns Task id.
+     */
     public get_id(): string;
 
+    /**
+     * Set task priority used by task UI ordering.
+     *
+     * @param priority - New priority.
+     */
     public set_priority(priority: i32): void;
 
+    /**
+     * Set task id.
+     *
+     * @param id - Task id.
+     */
     public set_id(id: string): void;
 
+    /**
+     * @returns Task priority.
+     */
     public get_priority(): u32;
+
+    /**
+     * Add an objective to this task.
+     *
+     * @remarks
+     * The native binding adopts the objective and copies its current data into the task objective list. Mutating the
+     * original objective after this call does not update the stored copy.
+     *
+     * @param objective - Objective to adopt into the task.
+     */
+    public add_objective(objective: SGameTaskObjective): void;
+
+    /**
+     * Get objective by index.
+     *
+     * @remarks
+     * Index `0` returns the root objective. Other indices access native storage without a bounds check.
+     *
+     * @param objective_id - Objective index.
+     * @returns Objective instance.
+     */
+    public get_objective(objective_id: i32): SGameTaskObjective;
+
+    /**
+     * Count task objectives including the root objective.
+     *
+     * @returns Objective count.
+     */
+    public get_objectives_cnt(): u32;
   }
 }

package/types/xr_lib/xr_time.d.ts

@@ -7,6 +7,8 @@ declare module "xray16" {
    * @source C++ class CTime
    * @customConstructor CTime
    * @group xr_time
+   * @remarks
+   * Methods such as `add`, `sub`, `set`, and `setHMS` mutate the current instance.
    */
   export class CTime extends EngineBinding {
     /**
@@ -131,6 +133,9 @@ declare module "xray16" {
     /**
      * Subtract another time value from this one.
      *
+     * @remarks
+     * The result is clamped at zero when `time` is greater than the current value.
+     *
      * @param time - Time span to subtract.
      */
     public sub(time: CTime): void;
@@ -149,6 +154,9 @@ declare module "xray16" {
    *
    * @group xr_time
    *
+   * @remarks
+   * Reads `Device.dwTimeGlobal`, the frame-updated engine clock.
+   *
    * @example 0, 1000, 60000
    *
    * @returns Milliseconds from game executable start.
@@ -160,6 +168,9 @@ declare module "xray16" {
    *
    * @group xr_time
    *
+   * @remarks
+   * Reads the asynchronous multimedia timer, so it can advance outside the frame-updated `time_global` value.
+   *
    * @returns Milliseconds from game executable start.
    */
   export function time_global_async(this: void): u32;

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

@@ -1,19 +1,31 @@
 declare module "xray16" {
   /**
+   * Client object binding for `CMosquitoBald` anomaly objects.
+   *
    * @source C++ class CMosquitoBald : CGameObject
    * @customConstructor CMosquitoBald
    * @group xr_anomaly
+   *
+   * @remarks
+   * Concrete anomaly wrapper. Generic anomaly helpers are usually available through `CCustomZone`/`game_object`.
    */
   export class CMosquitoBald extends CGameObject {}
 
   /**
+   * Client object binding for torch items.
+   *
    * @source C++ class CTorch : CGameObject
    * @customConstructor CTorch
    * @group xr_anomaly
+   *
+   * @remarks
+   * Torch-specific night-vision helpers on `game_object` require this runtime object.
    */
   export class CTorch extends CGameObject {}
 
   /**
+   * Client object binding for `CTorridZone` anomaly objects.
+   *
    * @source C++ class CTorridZone : CGameObject
    * @customConstructor CTorridZone
    * @group xr_anomaly
@@ -21,6 +33,8 @@ declare module "xray16" {
   export class CTorridZone extends CGameObject {}
 
   /**
+   * Client object binding for `CRadioactiveZone` anomaly objects.
+   *
    * @source C++ class CRadioactiveZone : CGameObject
    * @customConstructor CRadioactiveZone
    * @group xr_anomaly
@@ -28,6 +42,8 @@ declare module "xray16" {
   export class CRadioactiveZone extends CGameObject {}
 
   /**
+   * Client object binding for `CMincer` anomaly objects.
+   *
    * @source C++ class CMincer : CGameObject
    * @customConstructor CMincer
    * @group xr_anomaly
@@ -35,6 +51,8 @@ declare module "xray16" {
   export class CMincer extends CGameObject {}
 
   /**
+   * Client object binding for `CFracture` anomaly objects.
+   *
    * @source C++ class CFracture : CGameObject
    * @customConstructor CFracture
    * @group xr_anomaly
@@ -42,6 +60,8 @@ declare module "xray16" {
   export class CFracture extends CGameObject {}
 
   /**
+   * Client object binding for `CHairsZone` anomaly objects.
+   *
    * @source C++ class CHairsZone : CGameObject
    * @customConstructor CHairsZone
    * @group xr_anomaly

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

@@ -1,18 +1,51 @@
 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();
 
-    public FollowByPath(a: string, b: i32, c: vector): void;
+    /**
+     * 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;
-    public SwitchVisibility(to: boolean): void;
+
+    /**
+     * 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
@@ -20,6 +53,8 @@ declare module "xray16" {
   export class CZudaArtefact extends CArtefact {}
 
   /**
+   * Client object binding for `CThornArtefact` artefacts.
+   *
    * @source C++ class CThornArtefact : CArtefact
    * @customConstructor CThornArtefact
    * @group xr_artefact
@@ -27,6 +62,8 @@ declare module "xray16" {
   export class CThornArtefact extends CArtefact {}
 
   /**
+   * Client object binding for `CBastArtefact` artefacts.
+   *
    * @source C++ class CBastArtefact : CArtefact
    * @customConstructor CBastArtefact
    * @group xr_artefact
@@ -34,6 +71,8 @@ declare module "xray16" {
   export class CBastArtefact extends CArtefact {}
 
   /**
+   * Client object binding for `CBlackDrops` artefacts.
+   *
    * @source C++ class CBlackDrops : CArtefact
    * @customConstructor CBlackDrops
    * @group xr_artefact
@@ -41,6 +80,8 @@ declare module "xray16" {
   export class CBlackDrops extends CArtefact {}
 
   /**
+   * Client object binding for `CBlackGraviArtefact` artefacts.
+   *
    * @source C++ class CBlackGraviArtefact : CArtefact
    * @customConstructor CBlackGraviArtefact
    * @group xr_artefact
@@ -48,6 +89,8 @@ declare module "xray16" {
   export class CBlackGraviArtefact extends CArtefact {}
 
   /**
+   * Client object binding for `CDummyArtefact` artefacts.
+   *
    * @source C++ class CDummyArtefact : CArtefact
    * @customConstructor CDummyArtefact
    * @group xr_artefact
@@ -55,6 +98,8 @@ declare module "xray16" {
   export class CDummyArtefact extends CArtefact {}
 
   /**
+   * Client object binding for `CElectricBall` artefacts.
+   *
    * @source C++ class CElectricBall : CArtefact
    * @customConstructor CElectricBall
    * @group xr_artefact
@@ -62,6 +107,8 @@ declare module "xray16" {
   export class CElectricBall extends CArtefact {}
 
   /**
+   * Client object binding for `CFadedBall` artefacts.
+   *
    * @source C++ class CFadedBall : CArtefact
    * @customConstructor CFadedBall
    * @group xr_artefact
@@ -69,6 +116,8 @@ declare module "xray16" {
   export class CFadedBall extends CArtefact {}
 
   /**
+   * Client object binding for `CGalantineArtefact` artefacts.
+   *
    * @source C++ class CGalantineArtefact : CArtefact
    * @customConstructor CGalantineArtefact
    * @group xr_artefact
@@ -76,6 +125,8 @@ declare module "xray16" {
   export class CGalantineArtefact extends CArtefact {}
 
   /**
+   * Client object binding for `CGraviArtefact` artefacts.
+   *
    * @source C++ class CGraviArtefact : CArtefact
    * @customConstructor CGraviArtefact
    * @group xr_artefact
@@ -83,6 +134,8 @@ declare module "xray16" {
   export class CGraviArtefact extends CArtefact {}
 
   /**
+   * Client object binding for `CMercuryBall` artefacts.
+   *
    * @source C++ class CMercuryBall : CArtefact
    * @customConstructor CMercuryBall
    * @group xr_artefact
@@ -90,6 +143,8 @@ declare module "xray16" {
   export class CMercuryBall extends CArtefact {}
 
   /**
+   * Client object binding for `CRustyHairArtefact` artefacts.
+   *
    * @source C++ class CRustyHairArtefact : CArtefact
    * @customConstructor CRustyHairArtefact
    * @group xr_artefact