xray16 1.4.0 → 1.5.0

package/types/xr_lib/xr_level.d.ts

@@ -11,6 +11,10 @@ declare module "xray16" {
     /**
      * Register a conditional level callback.
      *
+     * @remarks
+     * The physics commander polls this callback pair. Remove it with the same condition and action callbacks when the
+     * owner no longer needs it.
+     *
      * @param condition - Callback polled by the engine.
      * @param action - Callback called when the condition is satisfied.
      */
@@ -19,20 +23,21 @@ declare module "xray16" {
     /**
      * Register a conditional level callback owned by an object.
      *
+     * @remarks
+     * The owner is used only for callback lookup and bulk removal. Keep the object alive while the callback can run.
+     *
      * @param object - Owner object used for later removal.
      * @param condition - Callback polled by the engine.
      * @param action - Callback called when the condition is satisfied.
      */
-    add_call(
-      this: void,
-      object: object,
-      condition: (this: void) => boolean,
-      action: (this: void) => boolean
-    ): void;
+    add_call(this: void, object: object, condition: (this: void) => boolean, action: (this: void) => boolean): void;
 
     /**
      * Register named object methods as a conditional level callback.
      *
+     * @remarks
+     * This overload registers a unique callback pair for the object and method names.
+     *
      * @param object - Owner object used for callback lookup and removal.
      * @param condition - Method name used as condition callback.
      * @param action - Method name called when the condition is satisfied.
@@ -42,34 +47,40 @@ declare module "xray16" {
     /**
      * Start a camera effector.
      *
+     * @remarks
+     * Requires an actor. The binding adds the effector to `Actor().Cameras()`.
+     *
      * @param effect - Camera effector animation file.
      * @param id - Effector id used for replacement and removal.
      * @param is_cyclic - Whether the effector loops.
      * @param callback - Lua callback name called when the effector finishes.
+     * @returns Effector animation length.
      */
-    add_cam_effector(this: void, effect: string, id: i32, is_cyclic: boolean, callback: string): void;
+    add_cam_effector(this: void, effect: string, id: i32, is_cyclic: boolean, callback: string): f32;
 
     /**
      * Start a camera effector with custom field of view.
      *
+     * @since OpenXRay 2019-05-07, 2d1b946a, PR #382
+     *
+     * @remarks
+     * Requires an actor. The binding adds the effector to `Actor().Cameras()`.
+     *
      * @param effect - Camera effector animation file.
      * @param id - Effector id used for replacement and removal.
      * @param is_cyclic - Whether the effector loops.
      * @param callback - Lua callback name called when the effector finishes.
-     * @param camera_fov - Field of view for the effector.
+     * @param camera_fov - Optional field of view for the effector.
+     * @returns Effector animation length.
      */
-    add_cam_effector2(
-      this: void,
-      effect: string,
-      id: i32,
-      is_cyclic: boolean,
-      callback: string,
-      camera_fov: f32
-    ): void;
+    add_cam_effector2(this: void, effect: string, id: i32, is_cyclic: boolean, callback: string, camera_fov?: f32): f32;
 
     /**
      * Start a named complex effector.
      *
+     * @remarks
+     * Requires an actor. The effector is attached to the current actor object.
+     *
      * @param section - Effector section name.
      * @param id - Effector id used for replacement and removal.
      */
@@ -85,6 +96,9 @@ declare module "xray16" {
     /**
      * Start a post-process effector.
      *
+     * @remarks
+     * Requires an actor. The effector is attached to the actor camera manager.
+     *
      * @param file_name - Post-process effector file.
      * @param id - Effector id used for replacement and removal.
      * @param is_cyclic - Whether the effector loops.
@@ -94,6 +108,9 @@ declare module "xray16" {
     /**
      * Move game time forward.
      *
+     * @remarks
+     * Works only on a single-player server with ALife available. Otherwise the binding returns without changing time.
+     *
      * @param days - Days to add.
      * @param hours - Hours to add.
      * @param minutes - Minutes to add.
@@ -103,6 +120,9 @@ declare module "xray16" {
     /**
      * Validate a game object pointer in the engine.
      *
+     * @remarks
+     * Exported only in debug builds.
+     *
      * @param object - Object to check.
      */
     check_object(this: void, object: game_object): void;
@@ -117,6 +137,9 @@ declare module "xray16" {
     /**
      * Get actor object used by debug helpers.
      *
+     * @remarks
+     * Exported only in debug builds.
+     *
      * @returns Actor game object.
      */
     debug_actor(this: void): game_object;
@@ -124,6 +147,9 @@ declare module "xray16" {
     /**
      * Find an object by debug name.
      *
+     * @remarks
+     * Exported only in debug builds.
+     *
      * @param name - Object name.
      * @returns Matching game object.
      */
@@ -131,6 +157,9 @@ declare module "xray16" {
 
     /**
      * Disable player input.
+     *
+     * @remarks
+     * Does nothing while the actor exists and permanent god mode is enabled.
      */
     disable_input(this: void): void;
 
@@ -156,6 +185,11 @@ declare module "xray16" {
     /**
      * Get active camera id.
      *
+     * @since OpenXRay 2015-07-07, 6e703b4c
+     *
+     * @remarks
+     * Returns `255` when the current view entity is not an actor.
+     *
      * @returns Camera id.
      */
     get_active_cam(this: void): u8;
@@ -184,6 +218,8 @@ declare module "xray16" {
     /**
      * Get distance to the object or surface under the crosshair.
      *
+     * @since OpenXRay 2014-12-27, c82669625
+     *
      * @returns Target distance.
      */
     get_target_dist(this: void): f32;
@@ -191,6 +227,11 @@ declare module "xray16" {
     /**
      * Get targeted model element under the crosshair.
      *
+     * @since OpenXRay 2015-06-03, 7213550c
+     *
+     * @remarks
+     * Returns `0` when the current ray query has no model element.
+     *
      * @returns Target element id.
      */
     get_target_element(this: void): u32;
@@ -198,6 +239,8 @@ declare module "xray16" {
     /**
      * Get the object under the crosshair.
      *
+     * @since OpenXRay 2014-12-27, c82669625
+     *
      * @returns Target object, or `null` when nothing is targeted.
      */
     get_target_obj(this: void): game_object | null;
@@ -244,10 +287,20 @@ declare module "xray16" {
      */
     get_wfx_time(this: void): f32;
 
-    /** Hide HUD indicators. */
+    /**
+     * Hide HUD indicators.
+     *
+     * @remarks
+     * Also enables the runtime god-mode flag used while HUD indicators are hidden.
+     */
     hide_indicators(this: void): void;
 
-    /** Hide HUD indicators if the HUD is available. */
+    /**
+     * Hide HUD indicators if the HUD is available.
+     *
+     * @remarks
+     * Also enables the runtime god-mode flag used while HUD indicators are hidden.
+     */
     hide_indicators_safe(this: void): void;
 
     /**
@@ -269,6 +322,8 @@ declare module "xray16" {
     /**
      * Iterate objects currently online on the level.
      *
+     * @since OpenXRay 2019-04-28, 13c5c022
+     *
      * @param cb - Callback called for each online object.
      */
     iterate_online_objects(this: void, cb: (this: void, object: game_object) => void | boolean): void;
@@ -276,21 +331,35 @@ declare module "xray16" {
     /**
      * Iterate sounds from a sound collection.
      *
+     * @remarks
+     * `section` may contain a comma-separated list of base names. The callback receives each existing sound name found
+     * in `$game_sounds$`, including numbered variants from `0` up to `max_count - 1`.
+     *
      * @param section - Sound collection section.
-     * @param type - Sound type filter.
-     * @param cb - Callback called for each sound.
+     * @param max_count - Numbered suffixes to probe for each base name.
+     * @param cb - Callback called with each sound name.
      */
-    iterate_sounds(this: void, section: string, type: u32, cb: (this: void) => void): void;
+    iterate_sounds(this: void, section: string, max_count: u32, cb: (this: void, name: string) => void): void;
 
     /**
      * Iterate sounds from a sound collection with an owner object.
      *
+     * @remarks
+     * `section` may contain a comma-separated list of base names. The callback receives each existing sound name found
+     * in `$game_sounds$`, including numbered variants from `0` up to `max_count - 1`.
+     *
      * @param section - Sound collection section.
-     * @param type - Sound type filter.
+     * @param max_count - Numbered suffixes to probe for each base name.
      * @param object - Owner object.
-     * @param cb - Callback called for each sound.
+     * @param cb - Callback called with each sound name.
      */
-    iterate_sounds(this: void, section: string, type: u32, object: object, cb: (this: void) => void): void;
+    iterate_sounds(
+      this: void,
+      section: string,
+      max_count: u32,
+      object: object,
+      cb: (this: void, name: string) => void
+    ): void;
 
     /**
      * Sample low cover from a level vertex in a direction.
@@ -329,6 +398,9 @@ declare module "xray16" {
     /**
      * Change hint text for an object map spot.
      *
+     * @remarks
+     * Does nothing when the object does not have a matching map spot.
+     *
      * @param object_id - Target object id.
      * @param spot_type - Spot type from map spot config.
      * @param hint - New hint text.
@@ -406,6 +478,9 @@ declare module "xray16" {
     /**
      * Remove a conditional level callback.
      *
+     * @remarks
+     * The callbacks must match the original registered pair.
+     *
      * @param condition - Condition callback originally registered.
      * @param action - Action callback originally registered.
      */
@@ -414,20 +489,21 @@ declare module "xray16" {
     /**
      * Remove an object-owned conditional level callback.
      *
+     * @remarks
+     * The owner and callbacks must match the original registered pair.
+     *
      * @param object - Owner object.
      * @param condition - Condition callback originally registered.
      * @param action - Action callback originally registered.
      */
-    remove_call(
-      this: void,
-      object: object,
-      condition: (this: void) => boolean,
-      action: (this: void) => void
-    ): void;
+    remove_call(this: void, object: object, condition: (this: void) => boolean, action: (this: void) => void): void;
 
     /**
      * Remove named object methods registered as a level callback.
      *
+     * @remarks
+     * The owner and method names must match the original registered pair.
+     *
      * @param object - Owner object.
      * @param condition - Condition method name.
      * @param action - Action method name.
@@ -444,6 +520,9 @@ declare module "xray16" {
     /**
      * Stop a camera effector.
      *
+     * @remarks
+     * Requires an actor. The binding removes the effector from `Actor().Cameras()`.
+     *
      * @param id - Effector id.
      */
     remove_cam_effector(this: void, id: i32): void;
@@ -451,6 +530,9 @@ declare module "xray16" {
     /**
      * Stop a complex effector.
      *
+     * @remarks
+     * Requires an actor. The binding removes the effector from the current actor object.
+     *
      * @param id - Effector id.
      */
     remove_complex_effector(this: void, id: i32): void;
@@ -465,6 +547,9 @@ declare module "xray16" {
     /**
      * Stop a post-process effector.
      *
+     * @remarks
+     * Requires an actor. Does nothing when no post-process effector exists for the id.
+     *
      * @param id - Effector id.
      */
     remove_pp_effector(this: void, id: i32): void;
@@ -472,6 +557,8 @@ declare module "xray16" {
     /**
      * Send a network packet through the level.
      *
+     * @since OpenXRay 2014-12-27, c82669625
+     *
      * @param packet - Packet to send.
      * @param reliable - Whether the packet is reliable.
      * @param sequential - Whether the packet is sequential.
@@ -490,6 +577,11 @@ declare module "xray16" {
     /**
      * Set active camera id.
      *
+     * @since OpenXRay 2015-07-07, 6e703b4c
+     *
+     * @remarks
+     * Does nothing when the current view entity is not an actor or when the id is outside the actor camera range.
+     *
      * @param id - Camera id.
      */
     set_active_cam(this: void, id: u8): void;
@@ -497,6 +589,11 @@ declare module "xray16" {
     /**
      * Set active single-player difficulty.
      *
+     * @remarks
+     * Updates the global difficulty and notifies the active single-player game state.
+     *
+     * @throws If the active game state is not single-player.
+     *
      * @param difficulty - Difficulty id.
      */
     set_game_difficulty(this: void, difficulty: unknown /* Enum ESingleGameDifficulty */): void;
@@ -504,6 +601,9 @@ declare module "xray16" {
     /**
      * Set a post-process effector factor.
      *
+     * @remarks
+     * Requires an actor. Does nothing when no post-process effector exists for the id.
+     *
      * @param id - Effector id.
      * @param factor - Target factor.
      * @param speed - Optional transition speed.
@@ -513,6 +613,9 @@ declare module "xray16" {
     /**
      * Set sound volume.
      *
+     * @remarks
+     * The engine clamps the value to the `0..1` range.
+     *
      * @param volume - Sound volume.
      */
     set_snd_volume(this: void, volume: f32): void;
@@ -520,6 +623,9 @@ declare module "xray16" {
     /**
      * Set game time speed multiplier.
      *
+     * @remarks
+     * Works only on the server and outside editor mode. Otherwise the binding returns without changing the time factor.
+     *
      * @param factor - Time factor.
      */
     set_time_factor(this: void, factor: f32): void;
@@ -527,6 +633,9 @@ declare module "xray16" {
     /**
      * Change active game weather.
      *
+     * @remarks
+     * Does nothing in editor mode.
+     *
      * @param weather_name - Name of weather config to apply.
      * @param is_forced - Whether weather change should be forced.
      */
@@ -535,17 +644,28 @@ declare module "xray16" {
     /**
      * Start a weather effect by name.
      *
+     * @remarks
+     * Returns `false` in editor mode.
+     *
      * @param weather_fx_name - Weather effect config name.
      * @returns Whether the effect started.
      */
     set_weather_fx(this: void, weather_fx_name: string): boolean;
 
-    /** Show HUD indicators. */
+    /**
+     * Show HUD indicators.
+     *
+     * @remarks
+     * Clears the runtime god-mode flag set by `hide_indicators()` and `hide_indicators_safe()`.
+     */
     show_indicators(this: void): void;
 
     /**
      * Show or hide actor weapon.
      *
+     * @remarks
+     * Does nothing while the actor exists and permanent god mode is enabled.
+     *
      * @param is_visible - Whether weapon should be visible.
      */
     show_weapon(this: void, is_visible: boolean): void;
@@ -553,11 +673,17 @@ declare module "xray16" {
     /**
      * Spawn an item on the level.
      *
+     * @since OpenXRay 2015-01-18, 3ee7401d
+     *
+     * @remarks
+     * Uses the level spawn path, which is suitable for sections that are unsafe to create through `alife():create()`,
+     * such as bolts, phantoms, and ammo.
+     *
      * @param section - Item section name.
      * @param position - Spawn position.
      * @param level_vertex_id - Target level vertex.
      * @param parent_id - Parent object id, or `0xffff` for none.
-     * @param use_ai_locations - Whether to use AI locations.
+     * @param return_item - Engine spawn flag passed through to `Level().spawn_item`.
      */
     spawn_item(
       this: void,
@@ -565,7 +691,7 @@ declare module "xray16" {
       position: vector,
       level_vertex_id: u32,
       parent_id: u16,
-      use_ai_locations: boolean
+      return_item: boolean
     ): void;
 
     /**
@@ -578,34 +704,48 @@ declare module "xray16" {
     /**
      * Start or stop a menu dialog.
      *
+     * @remarks
+     * Hides the dialog when it is already shown. Otherwise shows it and applies `should_hide_indicators`.
+     *
      * @param dialog - Dialog window.
-     * @param is_active - Whether the dialog is active.
+     * @param should_hide_indicators - Whether showing the dialog should hide HUD indicators.
      */
-    start_stop_menu(this: void, dialog: CUIDialogWnd, is_active: boolean): void;
+    start_stop_menu(this: void, dialog: CUIDialogWnd, should_hide_indicators: boolean): void;
 
     /**
      * Start a weather effect from a specific time.
      *
+     * @remarks
+     * Returns `false` in editor mode.
+     *
      * @param weather_fx_name - Weather effect config name.
      * @param time - Start time.
      * @returns Whether the effect started.
      */
     start_weather_fx_from_time(this: void, weather_fx_name: string, time: f32): boolean;
 
-    /** Stop the active weather effect. */
+    /**
+     * Stop the active weather effect.
+     */
     stop_weather_fx(this: void): void;
 
     /**
      * Get nearest level vertex for a position.
      *
+     * @remarks
+     * The binding preserves original Lua behavior for invalid vertices and returns `4294967296` instead of `u32(-1)`.
+     *
      * @param position - World position.
      * @returns Level vertex id.
      */
-    vertex_id(this: void, position: vector): u32;
+    vertex_id(this: void, position: vector): u64;
 
     /**
      * Move from a level vertex in a direction.
      *
+     * @remarks
+     * Returns the original vertex when the engine cannot find a valid vertex in the requested direction.
+     *
      * @param vertex_id - Start level vertex id.
      * @param direction - Direction to move.
      * @param distance - Distance to move.
@@ -624,12 +764,15 @@ declare module "xray16" {
     /**
      * Cast a ray through the level collision world.
      *
+     * @remarks
+     * `result` is updated only when this returns `true`.
+     *
      * @param position - Ray origin.
      * @param direction - Ray direction.
      * @param range - Ray range.
      * @param target - Ray query target flags.
      * @param result - Ray query result placeholder.
-     * @param ignore_object - Object ignored by the query.
+     * @param ignore_object - Object ignored by the query, or `null`.
      * @returns Whether the ray hit anything.
      */
     ray_pick(
@@ -639,7 +782,7 @@ declare module "xray16" {
       range: f32,
       target: unknown,
       result: unknown,
-      ignore_object: game_object
+      ignore_object: game_object | null
     ): boolean;
   }
 

package/types/xr_lib/xr_luabind.d.ts

@@ -1,64 +1,90 @@
 declare module "xray16" {
   /**
-   * Base for bindings brought from LuaBind library.
-   * Includes base methods implemented with @LuabindClass decorator and overriding of operators.
+   * Base class for LuaBind-backed engine objects.
+   *
+   * Engine classes expose `__name` through the TypeScriptToLua LuaBind plugin so subclasses can be emitted as LuaBind
+   * classes instead of regular Lua tables.
    *
    * @source luabind
    * @group xr_luabind
    */
   export class EngineBinding {
     /**
-     * Name of luabind class constructor.
+     * LuaBind class constructor name.
      */
     public static readonly __name: string;
 
     /**
-     * Name of luabind class instance constructor.
+     * LuaBind instance constructor name.
      */
     public readonly __name: string;
   }
 
   /**
+   * Static members owned by `EngineBinding` and excluded from exported engine enum values.
+   *
    * @group xr_luabind
    */
   type TEngineBindingStaticMethods = keyof typeof EngineBinding;
 
   /**
-   * Decorator to mark classes as luabind transformed.
-   * Marked classes will be declared using luabind tools instead of default typescript-to-lua approach.
-   * Luabind variant is less flexible and has many limitations,
-   * but allows extension of engine exported classes and virtual methods.
+   * Mark a TypeScript class for LuaBind class transformation.
+   *
+   * Use this on classes that extend engine bindings and need LuaBind-compatible constructors, inheritance, or virtual
+   * methods in emitted Lua.
    *
    * @group xr_luabind
    *
-   * @returns Class decorator to mark class as luabind implementation.
+   * @returns Class decorator.
    */
   export function LuabindClass(): ClassDecorator;
 
   /**
+   * Runtime metadata for a LuaBind class.
+   *
    * @source C++ class class_info_data
    * @customConstructor class_info_data
    * @group xr_luabind
    */
   export class class_info_data extends EngineBinding {
+    /**
+     * Methods exposed by the LuaBind class.
+     */
     public readonly methods: LuaTable<string, (...args: Array<unknown>) => unknown>;
+
+    /**
+     * Attribute names exposed by the LuaBind class.
+     */
     public readonly attributes: LuaTable<number, string>;
+
+    /**
+     * LuaBind class name.
+     */
     public readonly name: string;
 
+    /**
+     * Engine-created LuaBind metadata.
+     */
     private constructor();
   }
 
   /**
+   * Get names of LuaBind classes registered in a Lua state.
+   *
    * @group xr_luabind
    *
-   * @param lua_state
+   * @param lua_state - Lua state to inspect.
+   * @returns Registered class names.
    */
   export function class_names(this: void, lua_state: unknown /* Lua_State*/): LuaTable<number, string>;
 
   /**
+   * Get LuaBind metadata for an object or class.
+   *
    * @group xr_luabind
    *
-   * @param target
+   * @param target - Object or class to inspect.
+   * @returns LuaBind class metadata.
    */
   export function class_info(this: void, target: unknown): class_info_data;
 }