xray16 1.3.4 → 1.5.0

package/types/xr_lib/xr_animation.d.ts

@@ -1,81 +1,252 @@
-declare module "xray16" {
-  /**
-   * @source C++ class duality
-   * @customConstructor duality
-   * @group xr_animation
-   */
-  export class duality {
-    public v: f32;
-    public h: f32;
-
-    public constructor();
-    public constructor(v: f32, h: f32);
-
-    public set(v: f32, h: f32): duality;
-  }
-
-  /**
-   * @source C++ class noise
-   * @customConstructor noise
-   * @group xr_animation
-   */
-  export class noise {
-    public fps: f32;
-    public grain: f32;
-    public intensity: f32;
-
-    public constructor();
-    public constructor(fps: f32, grain: f32, intensity: f32);
-
-    public set(fps: f32, grain: f32, intensity: f32): noise;
-  }
-
-  /**
-   * @source C++ class effector
-   * @customConstructor effector
-   * @group xr_animation
-   */
-  export class effector extends EngineBinding {
-    public constructor(int: i32, float: f32);
-
-    public start(): void;
-
-    public process(effector_params: effector_params): boolean;
-
-    public finish(): void;
-  }
-
-  /**
-   * @source C++ class effector_params
-   * @customConstructor effector_params
-   * @group xr_animation
-   */
-  export class effector_params extends EngineBinding {
-    public color_add: color;
-    public color_base: color;
-    public color_gray: color;
-    public dual: duality;
-    public blur: f32;
-    public gray: f32;
-    public noise: noise;
-
-    public constructor();
-
-    public assign(effector_params: effector_params): void;
-  }
-
-  /**
-   * @source C++ class color_animator
-   * @customConstructor color_animator
-   * @group xr_animation
-   */
-  export class color_animator extends EngineBinding {
-    public constructor(value: string);
-
-    public length(): u32;
-
-    public load(value: string): void;
-
-    public calculate(value: f32): fcolor;
-  }
-}
+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();
+
+    /**
+     * 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();
+
+    /**
+     * 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 {
+    /**
+     * @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;
+
+    /**
+     * 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();
+
+    /**
+     * 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 {
+    /**
+     * @param name - Color animation name.
+     */
+    public constructor(name: string);
+
+    /**
+     * @returns Animation length in milliseconds.
+     */
+    public length(): u32;
+
+    /**
+     * 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,21 +1,44 @@
-declare module "xray16" {
-  /**
-   * @group xr_bitwise
-   */
-  export function bit_and(this: void, left: i32, right: i32): i32;
-
-  /**
-   * @group xr_bitwise
-   */
-  export function bit_or(this: void, first: i32, second: i32): i32;
-
-  /**
-   * @group xr_bitwise
-   */
-  export function bit_not(this: void, value: i32): i32;
-
-  /**
-   * @group xr_bitwise
-   */
-  export function bit_xor(this: void, left: i32, right: i32): i32;
-}
+declare module "xray16" {
+  /**
+   * Apply bitwise AND to two signed integers.
+   *
+   * @group xr_bitwise
+   *
+   * @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 left - Left operand.
+   * @param right - Right operand.
+   * @returns Result of `left | right`.
+   */
+  export function bit_or(this: void, left: i32, right: i32): i32;
+
+  /**
+   * Invert all bits in a signed integer.
+   *
+   * @group xr_bitwise
+   *
+   * @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 - 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,40 +1,142 @@
-declare module "xray16" {
-  /**
-   * @source C++ class fcolor
-   * @customConstructor fcolor
-   * @group xr_color
-   */
-  export class fcolor extends EngineBinding {
-    public a: f32;
-    public b: f32;
-    public g: f32;
-    public r: f32;
-
-    public set(a: f32, b: f32, c: f32, d: f32): fcolor;
-
-    public set(it: fcolor): fcolor;
-
-    public set(value: u32): fcolor;
-  }
-
-  /**
-   * @source C++ class color
-   * @customConstructor color
-   * @group xr_color
-   */
-  export class color {
-    public b: f32;
-    public g: f32;
-    public r: f32;
-
-    public constructor();
-    public constructor(r: f32, g: f32, b: f32);
-
-    public set(r: f32, g: f32, b: f32): void;
-  }
-
-  /**
-   * @group xr_color
-   */
-  export function GetARGB(this: void, a: u16, r: u16, g: u16, b: u16): i32;
-}
+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;
+
+    /**
+     * 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;
+
+    /**
+     * 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
+   *
+   * @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;
+}