xray16 1.4.0 → 1.5.0

package/types/xr_lib/xr_game.d.ts

@@ -25,22 +25,63 @@ declare module "xray16" {
    * @group xr_game
    */
   export class GAME_TYPE {
+    /**
+     * Engine enum value for `GAME_TYPE.eGameIDArtefactHunt`.
+     */
     public static readonly eGameIDArtefactHunt: 8;
+    /**
+     * Engine enum value for `GAME_TYPE.eGameIDCaptureTheArtefact`.
+     */
     public static readonly eGameIDCaptureTheArtefact: 16;
+    /**
+     * Engine enum value for `GAME_TYPE.eGameIDDeathmatch`.
+     */
     public static readonly eGameIDDeathmatch: 2;
+    /**
+     * Engine enum value for `GAME_TYPE.eGameIDTeamDeathmatch`.
+     */
     public static readonly eGameIDTeamDeathmatch: 4;
 
+    /**
+     * Engine enum value for `GAME_TYPE.GAME_UNKNOWN`.
+     */
     public static readonly GAME_UNKNOWN: -1;
+    /**
+     * Engine enum value for `GAME_TYPE.GAME_ANY`.
+     */
     public static readonly GAME_ANY: 0;
+    /**
+     * Engine enum value for `GAME_TYPE.GAME_SINGLE`.
+     */
     public static readonly GAME_SINGLE: 1;
+    /**
+     * Engine enum value for `GAME_TYPE.GAME_DEATHMATCH`.
+     */
     public static readonly GAME_DEATHMATCH: 2;
+
     //	GAME_CTF							= 3,
     //	GAME_ASSAULT						= 4,	// Team1 - assaulting, Team0 - Defending
+
+    /**
+     * Engine enum value for `GAME_TYPE.GAME_CS`.
+     */
     public static readonly GAME_CS: 5;
+    /**
+     * Engine enum value for `GAME_TYPE.GAME_TEAMDEATHMATCH`.
+     */
     public static readonly GAME_TEAMDEATHMATCH: 6;
+    /**
+     * Engine enum value for `GAME_TYPE.GAME_ARTEFACTHUNT`.
+     */
     public static readonly GAME_ARTEFACTHUNT: 7;
+    /**
+     * Engine enum value for `GAME_TYPE.GAME_CAPTURETHEARTEFACT`.
+     */
     public static readonly GAME_CAPTURETHEARTEFACT: 8;
     // Identifiers in range [100...254] are registered for script game type
+    /**
+     * Engine enum value for `GAME_TYPE.GAME_DUMMY`.
+     */
     public static readonly GAME_DUMMY: 255; // Temporary g
   }
 
@@ -57,9 +98,21 @@ declare module "xray16" {
    * @group xr_game
    */
   export class game_difficulty {
+    /**
+     * Engine enum value for `game_difficulty.novice`.
+     */
     public static readonly novice: 0;
+    /**
+     * Engine enum value for `game_difficulty.stalker`.
+     */
     public static readonly stalker: 1;
+    /**
+     * Engine enum value for `game_difficulty.veteran`.
+     */
     public static readonly veteran: 2;
+    /**
+     * Engine enum value for `game_difficulty.master`.
+     */
     public static readonly master: 3;
   }
 
@@ -83,6 +136,9 @@ declare module "xray16" {
     /**
      * Create a new game time value.
      *
+     * @remarks
+     * This is the same constructor exported as `CTime`.
+     *
      * @returns Empty `CTime` instance.
      */
     CTime: (this: void) => CTime;
@@ -90,6 +146,8 @@ declare module "xray16" {
     /**
      * Resolve a string table key for the current language.
      *
+     * @since OpenXRay 2022-08-09, a2d264fc, PR #1032
+     *
      * @param translation_key - String table key to translate.
      * @returns Localized text or the fallback string from the string table.
      */
@@ -98,30 +156,46 @@ declare module "xray16" {
     /**
      * Get current in-game time as seconds.
      *
+     * @remarks
+     * Returns the low 32 bits of the current game time counter.
+     *
      * @returns Game time counter.
      */
     time(this: void): u32;
 
     /**
      * Reload string table data for the active language.
+     *
+     * @since OpenXRay 2022-08-09, a2d264fc, PR #1032
      */
     reload_language(this: void): void;
 
     /**
      * Get current in-game calendar time.
      *
+     * @remarks
+     * Uses ALife game time when ALife is available, otherwise falls back to the current level game time.
+     *
      * @returns Current game time value.
      */
     get_game_time(this: void): CTime;
 
     /**
      * Write the current native stack trace to the engine log.
+     *
+     * @since OpenXRay 2022-08-09, a2d264fc, PR #1032
      */
     log_stack_trace(this: void): void;
 
     /**
      * Move the actor to another level by level name.
      *
+     * @since OpenXRay 2014-12-27, c82669625
+     *
+     * @remarks
+     * If the level name is not present in the game graph, the engine logs a script error and leaves the actor in the
+     * current level.
+     *
      * @param level_name - Target level name from the game graph.
      */
     jump_to_level(this: void, level_name: string): void;
@@ -129,6 +203,8 @@ declare module "xray16" {
     /**
      * Move the actor to another level graph point.
      *
+     * @since OpenXRay 2014-12-27, c82669625
+     *
      * @param position - Target position.
      * @param level_vertex_id - Target level vertex.
      * @param game_vertex_id - Target game graph vertex.
@@ -138,6 +214,8 @@ declare module "xray16" {
     /**
      * Move the actor to another level graph point and face a direction.
      *
+     * @since OpenXRay 2014-12-27, c82669625
+     *
      * @param position - Target position.
      * @param level_vertex_id - Target level vertex.
      * @param game_vertex_id - Target game graph vertex.
@@ -148,6 +226,10 @@ declare module "xray16" {
     /**
      * Start an in-game tutorial sequence.
      *
+     * @remarks
+     * Does nothing while the load screen is active. Starting a second tutorial stores the previous one as the fallback
+     * input receiver.
+     *
      * @param tutorial_id - Tutorial identifier.
      */
     start_tutorial(this: void, tutorial_id: string): void;
@@ -162,6 +244,11 @@ declare module "xray16" {
     /**
      * Get the active tutorial identifier.
      *
+     * @since OpenXRay 2022-08-09, a2d264fc, PR #1032
+     *
+     * @remarks
+     * Call only after `has_active_tutorial()` returns `true`; the binding dereferences the active tutorial directly.
+     *
      * @returns Active tutorial name.
      */
     active_tutorial_name(this: void): string;
@@ -219,7 +306,11 @@ declare module "xray16" {
   /**
    * Set the actor start position used by level transition logic.
    *
+   * @since OpenXRay 2022-08-22, 33f6da05, PR #1006
+   *
    * @group xr_game
+   * @remarks
+   * Updates the global start position consumed by ALife level-transition code.
    *
    * @param position - Target start position.
    */
@@ -228,8 +319,13 @@ declare module "xray16" {
   /**
    * Set the actor start game graph vertex.
    *
+   * @since OpenXRay 2022-08-22, 33f6da05, PR #1006
+   *
    * @group xr_game
    *
+   * @remarks
+   * Updates the global start game vertex consumed by ALife level-transition code.
+   *
    * @param game_vertex_id - Target game graph vertex.
    */
   export function set_start_game_vertex_id(this: void, game_vertex_id: i32): void;
@@ -239,6 +335,9 @@ declare module "xray16" {
    *
    * @group xr_game
    *
+   * @remarks
+   * On non-Windows builds this always returns `true`.
+   *
    * @returns Whether available address space is sufficient.
    */
   export function is_enough_address_space_available(this: void): boolean;
@@ -247,6 +346,8 @@ declare module "xray16" {
    * Ask the engine to verify that its watched thread is still running.
    *
    * @group xr_game
+   *
+   * @throws If called outside the active Lua thread.
    */
   export function verify_if_thread_is_running(this: void): void;
 

package/types/xr_lib/xr_hit.d.ts

@@ -1,31 +1,115 @@
 declare module "xray16" {
   /**
+   * Hit packet that can be sent to game objects.
+   *
    * @source C++ class hit
    * @customConstructor hit
    * @group xr_hit
+   *
+   * @remarks
+   * A new hit defaults to wound damage with power `100`, impulse `100`, direction `(1, 0, 0)`, and no draftsman.
    */
   export class hit {
+    /**
+     * Engine enum value for `hit.burn`.
+     */
     public static readonly burn = 0;
+    /**
+     * Engine enum value for `hit.chemical_burn`.
+     */
     public static readonly chemical_burn = 2;
+    /**
+     * Engine enum value for `hit.dummy`.
+     */
     public static readonly dummy = 12;
+    /**
+     * Engine enum value for `hit.explosion`.
+     */
     public static readonly explosion = 7;
+    /**
+     * Engine enum value for `hit.fire_wound`.
+     */
     public static readonly fire_wound = 8;
+    /**
+     * Engine enum value for `hit.light_burn`.
+     */
     public static readonly light_burn = 11;
+    /**
+     * Engine enum value for `hit.physic_strike`.
+     */
+    public static readonly physic_strike = 10;
+    /**
+     * Engine enum value for `hit.radiation`.
+     */
     public static readonly radiation = 3;
+    /**
+     * Engine enum value for `hit.shock`.
+     */
     public static readonly shock = 1;
+    /**
+     * Engine enum value for `hit.strike`.
+     */
     public static readonly strike = 5;
+    /**
+     * Engine enum value for `hit.telepatic`.
+     */
     public static readonly telepatic = 4;
+    /**
+     * Engine enum value for `hit.wound`.
+     */
     public static readonly wound = 6;
 
+    /**
+     * Hit direction.
+     */
     public direction: vector;
+
+    /**
+     * Object that caused the hit.
+     *
+     * @remarks
+     * Leave `null` for world or scripted damage that should not be attributed to a game object.
+     */
     public draftsman: game_object | null;
+
+    /**
+     * Physics impulse applied with the hit.
+     */
     public impulse: f32;
+
+    /**
+     * Hit damage power.
+     */
     public power: f32;
+
+    /**
+     * Hit damage type.
+     */
     public type: TXR_hit_type;
 
+    /**
+     * Create an empty hit packet.
+     *
+     * @remarks
+     * Uses the engine default values described on `hit`.
+     */
     public constructor();
+
+    /**
+     * Copy an existing hit packet.
+     *
+     * @param hit - Source hit.
+     */
     public constructor(hit: hit);
 
+    /**
+     * Target a model bone by name.
+     *
+     * @remarks
+     * Stores the bone name on the hit. The receiving object resolves it against its own model.
+     *
+     * @param bone - Bone name used by the receiver model.
+     */
     public bone(bone: string): void;
   }
 

package/types/xr_lib/xr_ini.d.ts

@@ -8,6 +8,10 @@ declare module "xray16" {
    * @source C++ class ini_file
    * @customConstructor ini_file
    * @group xr_ini
+   *
+   * @remarks
+   * Most typed read methods use the engine's strict config readers. Check `section_exist` and `line_exist` first when
+   * missing data is valid for your script.
    */
   export class ini_file {
     /**
@@ -16,9 +20,12 @@ declare module "xray16" {
     public constructor();
 
     /**
-     * Open an ini file from a game path.
+     * Open an ini file from the game config path.
+     *
+     * @remarks
+     * This constructor resolves `path` below `$game_config$`.
      *
-     * @param path - File name or path relative to game data.
+     * @param path - File name or path relative to `$game_config$`.
      */
     public constructor(path: string);
 
@@ -31,6 +38,9 @@ declare module "xray16" {
     public constructor(initial: string, path: string);
 
     /**
+     * @remarks
+     * Missing sections are an engine assertion path. The recoverable branch returns `0`.
+     *
      * @param section - Target section to check lines count.
      * @returns Count of lines for provided section.
      */
@@ -69,6 +79,8 @@ declare module "xray16" {
     /**
      * Read a floating-point value.
      *
+     * @throws If the section or field does not exist.
+     *
      * @param section - Section name.
      * @param field - Field name.
      * @returns Parsed number.
@@ -87,6 +99,8 @@ declare module "xray16" {
     /**
      * Read a signed 32-bit integer.
      *
+     * @throws If the section or field does not exist.
+     *
      * @param section - Section name.
      * @param field - Field name.
      * @returns Parsed integer.
@@ -96,6 +110,11 @@ declare module "xray16" {
     /**
      * Read text line from ini config file.
      *
+     * @remarks
+     * Returns `false` for an out-of-range line index. A missing section is a hard engine error.
+     *
+     * @throws If the section does not exist.
+     *
      * @param section - Section name.
      * @param line_number - Zero-based line index inside the section.
      * @param key - Placeholder for Lua out parameter.
@@ -122,6 +141,8 @@ declare module "xray16" {
     /**
      * Read a 3D vector.
      *
+     * @throws If the section or field does not exist.
+     *
      * @param section - Section name.
      * @param field - Field name.
      * @returns Parsed vector.
@@ -131,6 +152,8 @@ declare module "xray16" {
     /**
      * Read an unsigned 32-bit integer.
      *
+     * @throws If the section or field does not exist.
+     *
      * @param section - Section name.
      * @param field - Field name.
      * @returns Parsed integer.
@@ -140,6 +163,9 @@ declare module "xray16" {
     /**
      * Read a quoted string value.
      *
+     * @remarks
+     * Uses the same engine reader as `r_string_wb`; quoted values may keep spaces.
+     *
      * @param section - Section name.
      * @param field - Field name.
      * @returns Parsed string.
@@ -147,6 +173,9 @@ declare module "xray16" {
     public r_string_wq(section: string, field: string): string;
 
     /**
+     * @remarks
+     * Reads a string with blanks preserved by the engine parser.
+     *
      * @param section - Ini file section.
      * @param field - Ini section field.
      * @returns If quoted, parsed string data inside quotes including spaces, else is same data as with r_string.
@@ -154,6 +183,8 @@ declare module "xray16" {
     public r_string_wb(section: string, field: string): string;
 
     /**
+     * @throws If the section or field does not exist.
+     *
      * @param section - Ini file section.
      * @param field - Ini section field.
      * @returns Raw string from ltx file without spaces in it.
@@ -172,6 +203,8 @@ declare module "xray16" {
     /**
      * Write a 2D vector value.
      *
+     * @since OpenXRay 2014-12-30, 565b39e5
+     *
      * @param section - Section name.
      * @param field - Field name.
      * @param vector - Value to write.
@@ -182,6 +215,8 @@ declare module "xray16" {
     /**
      * Write a 3D vector value.
      *
+     * @since OpenXRay 2014-12-30, 565b39e5
+     *
      * @param section - Section name.
      * @param field - Field name.
      * @param vector - Value to write.
@@ -192,6 +227,8 @@ declare module "xray16" {
     /**
      * Write a 4D vector value.
      *
+     * @since OpenXRay 2014-12-30, 565b39e5
+     *
      * @param section - Section name.
      * @param field - Field name.
      * @param vector - Value to write.
@@ -348,6 +385,8 @@ declare module "xray16" {
     /**
      * Enable or disable section override name handling.
      *
+     * @since OpenXRay 2014-12-30, 565b39e5
+     *
      * @param override - Whether override names should be used.
      */
     public set_override_names(override: boolean): void;
@@ -355,6 +394,8 @@ declare module "xray16" {
     /**
      * Save this ini file to a path.
      *
+     * @throws If `path` is missing.
+     *
      * @param path - Destination path.
      * @returns Whether saving succeeded.
      */
@@ -363,6 +404,10 @@ declare module "xray16" {
     /**
      * Adjust saving on file closing/destructor calls.
      *
+     * @remarks
+     * Intended for script-created or script-owned ini files. Be careful using it on engine-owned singletons returned
+     * by `game_ini` or `system_ini`.
+     *
      * @param should_save - Whether ini file should be saved when destructor is called.
      */
     public save_at_end(should_save: boolean): void;
@@ -381,6 +426,9 @@ declare module "xray16" {
    *
    * @group xr_ini
    *
+   * @remarks
+   * Parses the string through an in-memory reader using `$game_config$` as the base include path.
+   *
    * @param content - String value to be read as ini file.
    * @returns New ini file instance based on provided content.
    */
@@ -391,6 +439,9 @@ declare module "xray16" {
    *
    * @group xr_ini
    *
+   * @remarks
+   * Returns the engine-owned `pGameIni` singleton.
+   *
    * @returns Current game ini file.
    */
   export function game_ini(this: void): ini_file;
@@ -400,6 +451,9 @@ declare module "xray16" {
    *
    * @group xr_ini
    *
+   * @remarks
+   * Returns the engine-owned `pSettings` singleton.
+   *
    * @returns Current system ini file.
    */
   export function system_ini(this: void): ini_file;
@@ -409,6 +463,10 @@ declare module "xray16" {
    *
    * @group xr_ini
    *
+   * @remarks
+   * Destroys the current `pSettings` instance and reloads `system.ltx` from `$game_config$`. Avoid keeping old
+   * `system_ini()` references across this call.
+   *
    * @returns Reloaded system ini file.
    */
   export function reload_system_ini(this: void): ini_file;