xray16 1.4.0 → 1.5.0

package/types/xr_lib/xr_animation.d.ts

@@ -1,81 +1,252 @@
 declare module "xray16" {
   /**
+   * Post-process double-vision offsets.
+   *
    * @source C++ class duality
    * @customConstructor duality
    * @group xr_animation
+   *
+   * @remarks
+   * These values are accumulated when several post-process effectors are active.
    */
   export class duality {
+    /**
+     * Vertical duality amount.
+     */
     public v: f32;
+
+    /**
+     * Horizontal duality amount.
+     */
     public h: f32;
 
+    /**
+     * Create zeroed duality settings.
+     */
     public constructor();
-    public constructor(v: f32, h: f32);
 
-    public set(v: f32, h: f32): duality;
+    /**
+     * Create duality settings with both offsets.
+     *
+     * @param h - Horizontal duality amount.
+     * @param v - Vertical duality amount.
+     */
+    public constructor(h: f32, v: f32);
+
+    /**
+     * Set both duality values.
+     *
+     * @param h - Horizontal duality amount.
+     * @param v - Vertical duality amount.
+     * @returns This object for chained setup.
+     */
+    public set(h: f32, v: f32): duality;
   }
 
   /**
+   * Post-process noise settings.
+   *
    * @source C++ class noise
    * @customConstructor noise
    * @group xr_animation
+   *
+   * @remarks
+   * Combined effectors keep the maximum intensity, grain, and FPS values.
    */
   export class noise {
+    /**
+     * Noise frame rate.
+     */
     public fps: f32;
+
+    /**
+     * Noise grain size.
+     */
     public grain: f32;
+
+    /**
+     * Noise intensity.
+     */
     public intensity: f32;
 
+    /**
+     * Create default noise settings.
+     *
+     * @remarks
+     * Defaults are intensity 0, grain 1, and 10 FPS.
+     */
     public constructor();
-    public constructor(fps: f32, grain: f32, intensity: f32);
 
-    public set(fps: f32, grain: f32, intensity: f32): noise;
+    /**
+     * Create noise settings with all values.
+     *
+     * @param intensity - Noise intensity.
+     * @param grain - Noise grain size.
+     * @param fps - Noise frame rate.
+     */
+    public constructor(intensity: f32, grain: f32, fps: f32);
+
+    /**
+     * Set all noise values.
+     *
+     * @param intensity - Noise intensity.
+     * @param grain - Noise grain size.
+     * @param fps - Noise frame rate.
+     * @returns This object for chained setup.
+     */
+    public set(intensity: f32, grain: f32, fps: f32): noise;
   }
 
   /**
+   * Script-controlled post-process effector.
+   *
    * @source C++ class effector
    * @customConstructor effector
    * @group xr_animation
+   *
+   * @remarks
+   * Subclass it from script and override {@link process}. The effector is tied to the actor camera stack.
    */
   export class effector extends EngineBinding {
-    public constructor(int: i32, float: f32);
-
+    /**
+     * @remarks
+     * Use a stable custom type id. {@link finish} removes the active effector by this type.
+     *
+     * @param type - Unique post-process effector type id.
+     * @param time - Effector lifetime in seconds.
+     */
+    public constructor(type: i32, time: f32);
+
+    /**
+     * Add the effector to the actor camera stack.
+     *
+     * @remarks
+     * Requires an active actor. This is intended for in-game actor post-processing, not menu/editor code.
+     */
     public start(): void;
 
-    public process(effector_params: effector_params): boolean;
-
+    /**
+     * Update post-process parameters for the current frame.
+     *
+     * @remarks
+     * Override this in script. Mutate `params` for the current frame and return `false` to stop the effector.
+     *
+     * @param params - Mutable post-process parameters.
+     * @returns Whether the effector should continue running.
+     */
+    public process(params: effector_params): boolean;
+
+    /**
+     * Remove the effector from the actor camera stack.
+     *
+     * @remarks
+     * Removes by effector type, so sharing a type id with another active effector can remove the wrong effect.
+     */
     public finish(): void;
   }
 
   /**
+   * Mutable post-process state passed to effectors.
+   *
    * @source C++ class effector_params
    * @customConstructor effector_params
    * @group xr_animation
+   *
+   * @remarks
+   * Defaults match the neutral post-process state: no blur, gray, duality, or noise intensity.
    */
   export class effector_params extends EngineBinding {
+    /**
+     * Additive color applied over the frame.
+     */
     public color_add: color;
+
+    /**
+     * Base color tint.
+     */
     public color_base: color;
+
+    /**
+     * Grayscale color tint.
+     */
     public color_gray: color;
+
+    /**
+     * Double-vision settings.
+     */
     public dual: duality;
+
+    /**
+     * Blur amount.
+     */
     public blur: f32;
+
+    /**
+     * Grayscale amount.
+     */
     public gray: f32;
+
+    /**
+     * Noise settings.
+     */
     public noise: noise;
 
+    /**
+     * Create default post-process parameters.
+     */
     public constructor();
 
-    public assign(effector_params: effector_params): void;
+    /**
+     * Copy all post-process values from another params object.
+     *
+     * @remarks
+     * Copies the current values. Later changes to `params` are not linked back to this object.
+     *
+     * @param params - Source values.
+     */
+    public assign(params: effector_params): void;
   }
 
   /**
+   * Evaluate a color animation by time.
+   *
    * @source C++ class color_animator
    * @customConstructor color_animator
    * @group xr_animation
+   *
+   * @remarks
+   * Animations are looked up in the loaded light-animation library (`lanims.xr`).
    */
   export class color_animator extends EngineBinding {
-    public constructor(value: string);
-
+    /**
+     * @param name - Color animation name.
+     */
+    public constructor(name: string);
+
+    /**
+     * @returns Animation length in milliseconds.
+     */
     public length(): u32;
 
-    public load(value: string): void;
-
-    public calculate(value: f32): fcolor;
+    /**
+     * Load another color animation.
+     *
+     * @remarks
+     * The native binding asserts when the animation name is missing or unknown.
+     *
+     * @param name - Color animation name.
+     */
+    public load(name: string): void;
+
+    /**
+     * Sample the animation.
+     *
+     * @remarks
+     * Time wraps over the animation length.
+     *
+     * @param time - Animation time in seconds.
+     * @returns Color at the requested time.
+     */
+    public calculate(time: f32): fcolor;
   }
 }

package/types/xr_lib/xr_bitwise.d.ts

@@ -1,32 +1,44 @@
 declare module "xray16" {
   /**
+   * Apply bitwise AND to two signed integers.
+   *
    * @group xr_bitwise
    *
-   * @param left
-   * @param right
+   * @param left - Left operand.
+   * @param right - Right operand.
+   * @returns Result of `left & right`.
    */
   export function bit_and(this: void, left: i32, right: i32): i32;
 
   /**
+   * Apply bitwise OR to two signed integers.
+   *
    * @group xr_bitwise
    *
-   * @param first
-   * @param second
+   * @param left - Left operand.
+   * @param right - Right operand.
+   * @returns Result of `left | right`.
    */
-  export function bit_or(this: void, first: i32, second: i32): i32;
+  export function bit_or(this: void, left: i32, right: i32): i32;
 
   /**
+   * Invert all bits in a signed integer.
+   *
    * @group xr_bitwise
    *
-   * @param value
+   * @param value - Value to invert.
+   * @returns Result of `~value`.
    */
   export function bit_not(this: void, value: i32): i32;
 
   /**
+   * Apply bitwise XOR to two signed integers.
+   *
    * @group xr_bitwise
    *
-   * @param left
-   * @param right
+   * @param left - Left operand.
+   * @param right - Right operand.
+   * @returns Result of `left ^ right`.
    */
   export function bit_xor(this: void, left: i32, right: i32): i32;
 }

package/types/xr_lib/xr_color.d.ts

@@ -1,45 +1,142 @@
 declare module "xray16" {
   /**
+   * Mutable RGBA color with float components.
+   *
+   * Components are exposed as `r`, `g`, `b`, and `a`.
+   *
    * @source C++ class fcolor
    * @customConstructor fcolor
    * @group xr_color
+   *
+   * @remarks
+   * Float components are normally used in the `0..1` range. `set()` mutates this color and returns it.
    */
   export class fcolor extends EngineBinding {
+    /**
+     * Alpha component.
+     */
     public a: f32;
+
+    /**
+     * Blue component.
+     */
     public b: f32;
+
+    /**
+     * Green component.
+     */
     public g: f32;
+
+    /**
+     * Red component.
+     */
     public r: f32;
 
-    public set(a: f32, b: f32, c: f32, d: f32): fcolor;
+    /**
+     * Create an empty color.
+     *
+     * @remarks
+     * Call `set()` before reading components when you need a known value.
+     */
+    public constructor();
+
+    /**
+     * Set RGBA components.
+     *
+     * @param r - Red component.
+     * @param g - Green component.
+     * @param b - Blue component.
+     * @param a - Alpha component.
+     * @returns This color.
+     */
+    public set(r: f32, g: f32, b: f32, a: f32): fcolor;
 
-    public set(it: fcolor): fcolor;
+    /**
+     * Copy another float color.
+     *
+     * @param color - Source color.
+     * @returns This color.
+     */
+    public set(color: fcolor): fcolor;
 
+    /**
+     * Decode packed ARGB color into float components.
+     *
+     * @remarks
+     * Channels are decoded from 8-bit ARGB into normalized float components.
+     *
+     * @param value - Packed ARGB value.
+     * @returns This color.
+     */
     public set(value: u32): fcolor;
   }
 
   /**
+   * Mutable RGB color with float components.
+   *
    * @source C++ class color
    * @customConstructor color
    * @group xr_color
+   *
+   * @remarks
+   * This is the postprocess RGB color helper used by effector parameters. It has no alpha channel.
    */
   export class color {
+    /**
+     * Blue component.
+     */
     public b: f32;
+
+    /**
+     * Green component.
+     */
     public g: f32;
+
+    /**
+     * Red component.
+     */
     public r: f32;
 
+    /**
+     * Create a black color.
+     *
+     * @remarks
+     * Use the RGB constructor or `set()` when you need explicit component values.
+     */
     public constructor();
+
+    /**
+     * Create color from RGB components.
+     *
+     * @param r - Red component.
+     * @param g - Green component.
+     * @param b - Blue component.
+     */
     public constructor(r: f32, g: f32, b: f32);
 
+    /**
+     * Set RGB components.
+     *
+     * @param r - Red component.
+     * @param g - Green component.
+     * @param b - Blue component.
+     */
     public set(r: f32, g: f32, b: f32): void;
   }
 
   /**
+   * Pack alpha, red, green, and blue channels into an engine color value.
+   *
    * @group xr_color
    *
-   * @param a
-   * @param r
-   * @param g
-   * @param b
+   * @remarks
+   * Channels are packed as 8-bit ARGB. Values outside `0..255` keep only their low 8 bits.
+   *
+   * @param a - Alpha channel.
+   * @param r - Red channel.
+   * @param g - Green channel.
+   * @param b - Blue channel.
+   * @returns Packed ARGB color.
    */
   export function GetARGB(this: void, a: u16, r: u16, g: u16, b: u16): i32;
 }

package/types/xr_lib/xr_debug.d.ts

@@ -1,83 +1,181 @@
 declare module "xray16" {
   /**
+   * Engine console interface.
+   *
    * @source C++ class CConsole
    * @customConstructor CConsole
    * @group xr_debug
+   *
+   * @remarks
+   * Use `get_console()` to access the engine-owned console. Scripts do not create console instances.
    */
   export class CConsole extends EngineBinding {
+    /**
+     * Engine-owned console singleton.
+     */
     private constructor();
 
+    /**
+     * Execute console command immediately.
+     *
+     * @remarks
+     * Executes without adding the command to console history.
+     *
+     * @param command - Console command.
+     */
     public execute(command: string): void;
 
+    /**
+     * Queue console command for deferred execution.
+     *
+     * @remarks
+     * Schedules a `KERNEL:console` event, so the command runs later on the engine event queue.
+     *
+     * @param command - Console command.
+     */
     public execute_deferred(command: string): void;
 
+    /**
+     * Execute a config file through the console.
+     *
+     * @remarks
+     * The binding prepends `cfg_load` to the provided path.
+     *
+     * @param script - Config file path.
+     */
     public execute_script(script: string): void;
 
+    /**
+     * Show the console window.
+     */
     public show(): void;
 
+    /**
+     * Hide the console window.
+     */
     public hide(): void;
 
+    /**
+     * Read console variable as boolean.
+     *
+     * @remarks
+     * Returns `false` when the command is missing or is not a boolean-compatible mask/integer command.
+     *
+     * @param key - Console variable name.
+     * @returns Boolean value.
+     */
     public get_bool(key: string): boolean;
 
+    /**
+     * Read console variable as float.
+     *
+     * @remarks
+     * Returns `0` when the command is missing or is not a float command.
+     *
+     * @param key - Console variable name.
+     * @returns Float value.
+     */
     public get_float(key: string): f32;
 
+    /**
+     * Read console variable as integer.
+     *
+     * @remarks
+     * Mask commands are returned as `0` or `1`. Missing or incompatible commands return `0`.
+     *
+     * @param key - Console variable name.
+     * @returns Integer value.
+     */
     public get_integer(key: string): i32;
 
-    public get_string(key: string): string;
-
-    public get_token(key: string): string;
+    /**
+     * Read console variable as string.
+     *
+     * @remarks
+     * Returns `null` when the command does not exist.
+     *
+     * @param key - Console variable name.
+     * @returns String value.
+     */
+    public get_string(key: string): string | null;
+
+    /**
+     * Read console variable token text.
+     *
+     * @remarks
+     * Uses the same engine path as `get_string`, so missing commands return `null`.
+     *
+     * @param key - Console variable name.
+     * @returns Token text.
+     */
+    public get_token(key: string): string | null;
   }
 
   /**
-   * Log formatted message in game console and log file.
-   * Resulting message looks like "[LUA]  %s", where message is provided text parameter.
-   *
-   * Note: text length is limited and supplying too long value will crash the game. Todo: check exact limit..
+   * Log a message through the script log channel.
    *
    * @group xr_debug
    *
-   * @param text - String to print.
+   * @remarks
+   * In non-master builds the message is sent to `CScriptEngine::script_log`.
+   *
+   * @param text - Message to print.
    */
   export function log(this: void, text: string): void;
 
   /**
+   * Log an error message and print the current script stack.
+   *
    * @group xr_debug
    *
-   * @param text
+   * @remarks
+   * The C++ binding asserts after logging the message.
+   *
+   * @param text - Error message.
    */
   export function error_log(this: void, text: string): void;
 
   /**
+   * Print the current script stack to the log.
+   *
    * @group xr_debug
    */
   export function print_stack(this: void): void;
 
   /**
+   * Flush pending script log output in debug builds.
+   *
    * @group xr_debug
    */
   export function flush(this: void): void;
 
   /**
    * Get console object reference.
-   * Allows flushing logs / executing commands / getting global engine variables.
    *
    * @group xr_debug
    *
+   * @remarks
+   * Returns the global engine console pointer.
+   *
    * @returns Console object reference.
    */
   export function get_console(this: void): CConsole;
 
   /**
+   * Get process command-line parameters.
+   *
    * @group xr_debug
+   *
+   * @returns Engine command-line string.
    */
   export function command_line(this: void): string;
 
   /**
-   * Prefetch provided script before executing next lines.
+   * Load and compile a script before continuing execution.
    *
    * @group xr_global_declaration
    *
-   * @param path
+   * @param path - Script file path.
    */
   export function prefetch(this: void, path: string): void;
 }