xray16 1.5.4 → 1.6.0

package/types/xr_object/script/xr_script_interface.d.ts

@@ -1,3 +1,5 @@
+import type { Nillable } from "../../internal";
+
 declare module "xray16" {
   /**
    * Cover point returned by cover search helpers.
@@ -94,146 +96,182 @@ declare module "xray16" {
      * Default x-ray 16 callbacks.
      */
     public static readonly trade_start: 0;
+
     /**
      * Engine enum value for `callback.trade_stop`.
      */
     public static readonly trade_stop: 1;
+
     /**
      * Engine enum value for `callback.trade_sell_buy_item`.
      */
     public static readonly trade_sell_buy_item: 2;
+
     /**
      * Engine enum value for `callback.trade_perform_operation`.
      */
     public static readonly trade_perform_operation: 3;
+
     /**
      * Engine enum value for `callback.zone_enter`.
      */
     public static readonly zone_enter: 4;
+
     /**
      * Engine enum value for `callback.zone_exit`.
      */
     public static readonly zone_exit: 5;
+
     /**
      * Engine enum value for `callback.level_border_exit`.
      */
     public static readonly level_border_exit: 6;
+
     /**
      * Engine enum value for `callback.level_border_enter`.
      */
     public static readonly level_border_enter: 7;
+
     /**
      * Engine enum value for `callback.death`.
      */
     public static readonly death: 8;
+
     /**
      * Engine enum value for `callback.patrol_path_in_point`.
      */
     public static readonly patrol_path_in_point: 9;
+
     /**
      * Engine enum value for `callback.inventory_pda`.
      */
     public static readonly inventory_pda: 10;
+
     /**
      * Engine enum value for `callback.inventory_info`.
      */
     public static readonly inventory_info: 11;
+
     /**
      * Engine enum value for `callback.article_info`.
      */
     public static readonly article_info: 12;
+
     /**
      * Engine enum value for `callback.task_state`.
      */
     public static readonly task_state: 13;
+
     /**
      * Engine enum value for `callback.map_location_added`.
      */
     public static readonly map_location_added: 14;
+
     /**
      * Engine enum value for `callback.use_object`.
      */
     public static readonly use_object: 15;
+
     /**
      * Engine enum value for `callback.hit`.
      */
     public static readonly hit: 16;
+
     /**
      * Engine enum value for `callback.sound`.
      */
     public static readonly sound: 17;
+
     /**
      * Engine enum value for `callback.action_movement`.
      */
     public static readonly action_movement: 18;
+
     /**
      * Engine enum value for `callback.action_watch`.
      */
     public static readonly action_watch: 19;
+
     /**
      * Engine enum value for `callback.action_removed`.
      */
     public static readonly action_removed: 20;
+
     /**
      * Engine enum value for `callback.action_animation`.
      */
     public static readonly action_animation: 21;
+
     /**
      * Engine enum value for `callback.action_sound`.
      */
     public static readonly action_sound: 22;
+
     /**
      * Engine enum value for `callback.action_particle`.
      */
     public static readonly action_particle: 23;
+
     /**
      * Engine enum value for `callback.action_object`.
      */
     public static readonly action_object: 24;
+
     /**
      * Engine enum value for `callback.actor_sleep`.
      */
     public static readonly actor_sleep: 25;
+
     /**
      * Engine enum value for `callback.helicopter_on_point`.
      */
     public static readonly helicopter_on_point: 26;
+
     /**
      * Engine enum value for `callback.helicopter_on_hit`.
      */
     public static readonly helicopter_on_hit: 27;
+
     /**
      * Engine enum value for `callback.on_item_take`.
      */
     public static readonly on_item_take: 28;
+
     /**
      * Engine enum value for `callback.on_item_drop`.
      */
     public static readonly on_item_drop: 29;
+
     /**
      * Engine enum value for `callback.script_animation`.
      */
     public static readonly script_animation: 30;
+
     /**
      * Engine enum value for `callback.trader_global_anim_request`.
      */
     public static readonly trader_global_anim_request: 31;
+
     /**
      * Engine enum value for `callback.trader_head_anim_request`.
      */
     public static readonly trader_head_anim_request: 32;
+
     /**
      * Engine enum value for `callback.trader_sound_end`.
      */
     public static readonly trader_sound_end: 33;
+
     /**
      * Engine enum value for `callback.take_item_from_box`.
      */
     public static readonly take_item_from_box: 34;
+
     /**
      * Engine enum value for `callback.weapon_no_ammo`.
      */
     public static readonly weapon_no_ammo: 35;
+
     /**
      * Engine enum value for `callback.hud_animation_end`.
      */
@@ -242,83 +280,102 @@ declare module "xray16" {
     /**
      * Engine enum value for `callback.key_press`.
      */
-    public static readonly key_press: 37;
+    public static readonly key_press: 123;
+
     /**
      * Engine enum value for `callback.key_release`.
      */
-    public static readonly key_release: 38;
+    public static readonly key_release: 124;
+
     /**
      * Engine enum value for `callback.key_hold`.
      */
-    public static readonly key_hold: 39;
+    public static readonly key_hold: 125;
+
     /**
      * Engine enum value for `callback.mouse_move`.
      */
-    public static readonly mouse_move: 40;
+    public static readonly mouse_move: 127;
+
     /**
      * Engine enum value for `callback.mouse_wheel`.
      */
-    public static readonly mouse_wheel: 41;
+    public static readonly mouse_wheel: 126;
+
     /**
      * Engine enum value for `callback.controller_press`.
      */
-    public static readonly controller_press: 42;
+    public static readonly controller_press: 48;
+
     /**
      * Engine enum value for `callback.controller_release`.
      */
-    public static readonly controller_release: 43;
+    public static readonly controller_release: 49;
+
     /**
      * Engine enum value for `callback.controller_hold`.
      */
-    public static readonly controller_hold: 44;
-    // Public static readonly controller_attitude_change: 45;
+    public static readonly controller_hold: 50;
+
+    /**
+     * Engine enum value for `callback.controller_attitude_change`.
+     */
+    public static readonly controller_attitude_change: 51;
 
     /**
      * Engine enum value for `callback.item_to_belt`.
      */
-    public static readonly item_to_belt: 46;
+    public static readonly item_to_belt: 37;
+
     /**
      * Engine enum value for `callback.item_to_slot`.
      */
-    public static readonly item_to_slot: 47;
+    public static readonly item_to_slot: 38;
+
     /**
      * Engine enum value for `callback.item_to_ruck`.
      */
-    public static readonly item_to_ruck: 48;
+    public static readonly item_to_ruck: 39;
 
     /**
      * Engine enum value for `callback.weapon_zoom_in`.
      */
-    public static readonly weapon_zoom_in: 49;
+    public static readonly weapon_zoom_in: 40;
+
     /**
      * Engine enum value for `callback.weapon_zoom_out`.
      */
-    public static readonly weapon_zoom_out: 50;
+    public static readonly weapon_zoom_out: 41;
+
     /**
      * Engine enum value for `callback.weapon_jammed`.
      */
-    public static readonly weapon_jammed: 51;
+    public static readonly weapon_jammed: 42;
+
     /**
      * Engine enum value for `callback.weapon_magazine_empty`.
      */
-    public static readonly weapon_magazine_empty: 52;
+    public static readonly weapon_magazine_empty: 43;
 
     /**
      * Engine enum value for `callback.actor_before_death`.
      */
-    public static readonly actor_before_death: 53;
+    public static readonly actor_before_death: 44;
+
     /**
      * Engine enum value for `callback.on_attach_vehicle`.
      */
-    public static readonly on_attach_vehicle: 54;
+    public static readonly on_attach_vehicle: 45;
+
     /**
      * Engine enum value for `callback.on_detach_vehicle`.
      */
-    public static readonly on_detach_vehicle: 55;
+    public static readonly on_detach_vehicle: 46;
+
     /**
      * Engine enum value for `callback.on_use_vehicle`.
      */
-    public static readonly on_use_vehicle: 56;
+    public static readonly on_use_vehicle: 47;
   }
 
   /**
@@ -332,447 +389,710 @@ declare module "xray16" {
   export type TXR_callback = EnumeratedStaticsValues<TXR_callbacks>;
 
   /**
-   * Custom extension.
-   * For reference: src/xrGame/script_game_object_script.cpp.
+   * `game_object.set_callback` overloads for Lua-visible game object callbacks.
    *
    * @group xr_script_interface
+   *
+   * @remarks
+   * When `object` is supplied, `CScriptCallbackEx` passes it as the first Lua callback argument.
    */
   class game_object_callbacks_implementation_base {
     /**
-     * Remove callback.
+     * Clear one callback registration.
+     *
+     * @remarks
+     * Uses the no-functor `CScriptGameObject::SetCallback(type)` overload, which clears the callback slot.
      *
-     * @param type - Type of callback.
-     * @param cb - Null to reset.
+     * @param type - Callback type to clear.
+     * @param cb - Nullish value used to select the clear overload.
      */
-    public set_callback(type: TXR_callback, cb: null): void;
+    public set_callback(type: TXR_callback, cb: Nillable<never>): void;
 
     /**
-     * 0 todo;.
+     * Fired when a trader starts a trade session.
+     *
+     * @source `src/xrGame/ai/trader/ai_trader.cpp`, `CAI_Trader::OnStartTrade`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["trade_start"],
-      cb?: ((this: void) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 1 todo;.
+     * Fired when a trader stops a trade session.
+     *
+     * @source `src/xrGame/ai/trader/ai_trader.cpp`, `CAI_Trader::OnStopTrade`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["trade_stop"],
-      cb?: ((this: void) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 2 todo;.
+     * Fired when an actor-involved trade transfers an item and money.
+     *
+     * @source `src/xrGame/trade2.cpp`, `CTrade::TransferItem`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["trade_sell_buy_item"],
-      cb?: ((this: void, item: game_object, money_direction: boolean, money: number) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<
+        (this: void, item: game_object, money_direction: boolean, money: number, partner: game_object) => void
+      >,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 3 todo;.
+     * Fired when a trader performs the money part of a trade operation.
+     *
+     * @source `src/xrGame/trade.cpp`, `CTrade::OnPerformTrade`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["trade_perform_operation"],
-      cb?: ((this: void, money_get: u32, money_put: u32) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, money_get: u32, money_put: u32) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 4 todo;
+     * Fired by a script zone when a game object enters it.
      *
-     * Works with script_zone objects.
+     * @source `src/xrGame/script_zone.cpp`, `CScriptZone::feel_touch_new`.
+     *
+     * @remarks
+     * The first callback argument is the zone object; the second is the entering object.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["zone_enter"],
-      cb?: ((this: void, zone: game_object, object: game_object) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, zone: game_object, object: game_object) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 5 todo;
+     * Fired by a script zone when a game object leaves it or is released while touching it.
+     *
+     * @source `src/xrGame/script_zone.cpp`, `CScriptZone::feel_touch_delete` and `CScriptZone::net_Relcase`.
      *
-     * Works with script_zone objects.
+     * @remarks
+     * The first callback argument is the zone object; the second is the leaving object.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["zone_exit"],
-      cb?: ((this: void, zone: game_object, object: game_object) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, zone: game_object, object: game_object) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 6 todo;.
+     * Fired when the actor leaves the playable level border.
+     *
+     * @source `src/xrGame/Actor.cpp`, `CActor::SwitchOutBorder`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["level_border_exit"],
-      cb?: ((this: void, xobject: game_object) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, object: game_object) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 7 todo;.
+     * Fired when the actor re-enters the playable level border.
+     *
+     * @source `src/xrGame/Actor.cpp`, `CActor::SwitchOutBorder`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["level_border_enter"],
-      cb?: ((this: void, xobject: game_object) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, object: game_object) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 8 todo;.
+     * Fired when the object dies or a destroyable physics object is destroyed.
+     *
+     * @source `src/xrGame/entity_alive.cpp`, `src/xrGame/DestroyablePhysicsObject.cpp`, and `src/xrGame/ai/crow/ai_crow.cpp`.
+     *
+     * @remarks
+     * The engine passes the victim and, when available, the killer object.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["death"],
       cb?: (this: void, target: game_object, killer: game_object) => void,
-      object?: Maybe<T>
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 9 todo;.
+     * Fired when an object reaches a patrol path point.
+     *
+     * @source `src/xrGame/patrol_path_manager.cpp`, `CPatrolPathManager::select_point`.
+     *
+     * @remarks
+     * The action type is `ScriptEntity::eActionTypeMovement`; `point_index` is the reached patrol vertex index.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["patrol_path_in_point"],
-      cb?: ((this: void, object: game_object, action_type: number, point_index: number) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, object: game_object, action_type: number, point_index: number) => void>,
+      object?: Nillable<T>
     ): void;
 
-    // 10 todo: inventory_pda -> implement in game engine
+    // The `inventory_pda` callback is registered in the enum, but no xray-16 call site was found.
 
     /**
-     * Callback executed when an NPC receives an info portion.
+     * Fired when the actor receives an info portion.
+     *
+     * @source `src/xrGame/actor_communication.cpp`, `CActor::OnReceiveInfo`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["inventory_info"],
-      cb?: ((this: void, npc: game_object, info_id: string) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, npc: game_object, info_id: string) => void>,
+      object?: Nillable<T>
+    ): void;
+
+    /**
+     * Fired when the actor receives an encyclopedia article from an info portion.
+     *
+     * @source `src/xrGame/actor_communication.cpp`, `CActor::AddEncyclopediaArticle`.
+     */
+    public set_callback<T extends AnyObject>(
+      type: TXR_callbacks["article_info"],
+      cb?: Nillable<(this: void, actor: game_object, group: string, name: string, article_type: i32) => void>,
+      object?: Nillable<T>
     ): void;
 
-    // 12 todo: article_info -> implement in game engine
+    /**
+     * Fired when an actor task state changes.
+     *
+     * @source `src/xrGame/GameTask.cpp`, `CGameTask::ChangeStateCallback` and `SGameTaskObjective::ChangeStateCallback`.
+     *
+     * @remarks
+     * Root task callbacks pass task and state. Objective callbacks are fired from the engine with parent task, objective, and state.
+     */
+    public set_callback<T extends AnyObject>(
+      type: TXR_callbacks["task_state"],
+      cb?: Nillable<(this: void, task: CGameTask, state: TXR_TaskState) => void>,
+      object?: Nillable<T>
+    ): void;
 
     /**
-     * 13 todo;.
+     * Fired when a task objective state changes.
+     *
+     * @source `src/xrGame/GameTask.cpp`, `SGameTaskObjective::ChangeStateCallback`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["task_state"],
-      cb?: ((this: void, task: CGameTask, state: TXR_TaskState) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, task: CGameTask, objective: SGameTaskObjective, state: TXR_TaskState) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 14 todo;.
+     * Fired when the single-player map manager adds an actor map location.
+     *
+     * @source `src/xrGame/map_manager.cpp`, `CMapManager::AddMapLocation`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["map_location_added"],
-      cb?: ((this: void, spot_type: string, id: u16) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, spot_type: string, id: u16) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 15 Use some object.
+     * Fired when the actor uses an inventory item.
+     *
+     * @source `src/xrGame/Inventory.cpp`, inventory item use path.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["use_object"],
-      cb?: ((this: void, object: game_object) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, object: game_object) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 15 Use some object with explicit user object.
+     * Fired when an object is used by another object.
+     *
+     * @source `src/xrGame/GameObject.cpp` and `src/xrGame/doors_door.cpp`.
+     *
+     * @remarks
+     * Door use callbacks pass the used object and the initiator when the initiator is available.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["use_object"],
-      cb?: ((this: void, object: game_object, who: game_object) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, object: game_object, who: game_object) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 16 Entity got hit.
+     * Fired when the actor receives a hit processed by the script hit path.
+     *
+     * @source `src/xrGame/Actor.cpp`, `CActor::Hit`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["hit"],
-      cb?:
-        | ((
-            this: void,
-            object: game_object,
-            damage: number,
-            direction: vector,
-            who: game_object,
-            bone_id: number
-          ) => void)
-        | null,
-      object?: Maybe<T>
+      cb?: Nillable<
+        (this: void, object: game_object, damage: number, direction: vector, who: game_object, bone_id: number) => void
+      >,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 17 todo;.
+     * Fired when a script entity processes a saved sound notification.
+     *
+     * @source `src/xrGame/script_entity.cpp`, `CScriptEntity::process_sound_callbacks`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["sound"],
-      cb?:
-        | ((
-            this: void,
-            object: game_object,
-            source_id: number,
-            sound_type: TXR_snd_type,
-            position: vector,
-            sound_power: number
-          ) => void)
-        | null,
-      object?: Maybe<T>
+      cb?: Nillable<
+        (
+          this: void,
+          object: game_object,
+          source_id: number,
+          sound_type: TXR_snd_type,
+          position: vector,
+          sound_power: number
+        ) => void
+      >,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 18 todo;.
+     * Fired when a script entity movement action completes.
+     *
+     * @source `src/xrGame/script_entity.cpp`, `CScriptEntity::ProcessScripts`.
+     *
+     * @remarks
+     * The engine passes `-1` as the third argument for this callback path.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["action_movement"],
-      cb?: ((this: void, object: game_object, movement_type: u32 /* EMovementType */, unknown: -1) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, object: game_object, movement_type: u32 /* EMovementType */, unknown: -1) => void>,
+      object?: Nillable<T>
     ): void;
 
-    // 19 todo: action_watch
+    /**
+     * Fired when a script entity watch action completes.
+     *
+     * @source `src/xrGame/script_entity.cpp`, `CScriptEntity::ProcessScripts`.
+     */
+    public set_callback<T extends AnyObject>(
+      type: TXR_callbacks["action_watch"],
+      cb?: Nillable<(this: void, object: game_object, action_type: u32) => void>,
+      object?: Nillable<T>
+    ): void;
 
-    // 20 todo: action_removed
+    /**
+     * Fired when a script entity action is removed from its queue.
+     *
+     * @source `src/xrGame/script_entity.cpp`, `CScriptEntity::ProcessScripts`.
+     */
+    public set_callback<T extends AnyObject>(
+      type: TXR_callbacks["action_removed"],
+      cb?: Nillable<(this: void, object: game_object, action_type: u32) => void>,
+      object?: Nillable<T>
+    ): void;
 
-    // 21 todo: action_animation
+    /**
+     * Fired when a script entity animation action completes.
+     *
+     * @source `src/xrGame/script_entity.cpp`, `ScriptCallBack`.
+     */
+    public set_callback<T extends AnyObject>(
+      type: TXR_callbacks["action_animation"],
+      cb?: Nillable<(this: void, object: game_object, action_type: u32) => void>,
+      object?: Nillable<T>
+    ): void;
 
-    // 22 todo: action_sound
+    /**
+     * Fired when a script entity sound action completes.
+     *
+     * @source `src/xrGame/script_entity.cpp`, `CScriptEntity::ProcessScripts`.
+     */
+    public set_callback<T extends AnyObject>(
+      type: TXR_callbacks["action_sound"],
+      cb?: Nillable<(this: void, object: game_object, action_type: u32) => void>,
+      object?: Nillable<T>
+    ): void;
 
-    // 23 todo: action_particle
+    /**
+     * Fired when a script entity particle action completes.
+     *
+     * @source `src/xrGame/script_entity.cpp`, `CScriptEntity::ProcessScripts`.
+     */
+    public set_callback<T extends AnyObject>(
+      type: TXR_callbacks["action_particle"],
+      cb?: Nillable<(this: void, object: game_object, action_type: u32) => void>,
+      object?: Nillable<T>
+    ): void;
 
-    // 24 todo: action_object
+    /**
+     * Fired when a script entity object action completes.
+     *
+     * @source `src/xrGame/script_entity.cpp`, `CScriptEntity::ProcessScripts`.
+     */
+    public set_callback<T extends AnyObject>(
+      type: TXR_callbacks["action_object"],
+      cb?: Nillable<(this: void, object: game_object, action_type: u32) => void>,
+      object?: Nillable<T>
+    ): void;
 
-    // 25 todo: actor_sleep -> implement in game engine
+    // The `actor_sleep` callback is registered in the enum, but no xray-16 call site was found.
 
     /**
-     * 26 todo;.
+     * Fired when a helicopter reaches its current patrol path point or move target.
+     *
+     * @source `src/xrGame/HelicopterMovementManager.cpp`.
+     *
+     * @remarks
+     * Patrol-path movement passes the patrol vertex id. Direct movement passes `-1`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["helicopter_on_point"],
-      cb?: ((this: void, distance: number, current_position: vector, vertex_id: number) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, distance: number, current_position: vector, vertex_id: number) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 27 todo;.
+     * Fired when a helicopter is hit by the actor, stalker, or custom zone.
+     *
+     * @source `src/xrGame/Helicopter2.cpp`, `CHelicopter::Hit`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["helicopter_on_hit"],
-      cb?: ((this: void, damage: number, impulse: number, hit_type: number, who_id: number) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, damage: number, impulse: number, hit_type: number, who_id: number) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 28 todo;.
+     * Fired when an inventory owner takes an item.
+     *
+     * @source `src/xrGame/InventoryOwner.cpp`, `CInventoryOwner::OnItemTake`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["on_item_take"],
-      cb?: ((this: void, object: game_object, item: game_object) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, object: game_object, item: game_object) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 29 todo;.
+     * Fired when an inventory owner drops an item.
+     *
+     * @source `src/xrGame/InventoryOwner.cpp`, `CInventoryOwner::OnItemDrop`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["on_item_drop"],
-      cb?: ((this: void, object: game_object, item: game_object) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, object: game_object, item: game_object) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 30 todo;.
+     * Fired by script animation callback processing.
+     *
+     * @source `src/xrGame/stalker_animation_manager_update.cpp` and `src/xrGame/animation_script_callback.cpp`.
+     *
+     * @remarks
+     * Stalker animation manager callbacks can call this with no arguments; animation script callbacks pass whether the ended phase is being reported.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["script_animation"],
-      cb?: ((this: void, skip_multi_anim_check?: boolean) => void) | null,
-      object?: object | null
+      cb?: Nillable<(this: void, skip_multi_anim_check?: boolean) => void>,
+      object?: Nillable<object>
     ): void;
 
     /**
-     * 31 todo;.
+     * Fired when a trader needs a new global animation motion.
+     *
+     * @source `src/xrGame/ai/trader/trader_animation.cpp`, `CTraderAnimation::update_frame`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["trader_global_anim_request"],
-      cb?: ((this: void) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 32 todo;.
+     * Fired when a trader needs a new head animation motion while sound is playing.
+     *
+     * @source `src/xrGame/ai/trader/trader_animation.cpp`, `CTraderAnimation::update_frame`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["trader_head_anim_request"],
-      cb?: ((this: void) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 33 todo;.
+     * Fired when a trader sound finishes playing.
+     *
+     * @source `src/xrGame/ai/trader/trader_animation.cpp`, `CTraderAnimation::update_frame`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["trader_sound_end"],
-      cb?: ((this: void) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 34 todo;.
+     * Fired when the actor takes an item from an inventory box while the box is open.
+     *
+     * @source `src/xrGame/InventoryBox.cpp`, `CInventoryBox::TakeItem`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["take_item_from_box"],
-      cb?: ((this: void, object: game_object, box: game_object, item: game_object) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, object: game_object, box: game_object, item: game_object) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 35 Callback executed when weapon has no ammo to fire.
+     * Fired when an actor-owned weapon tries to reload and no suitable ammo is available.
+     *
+     * @source `src/xrGame/WeaponMagazined.cpp`, `CWeaponMagazined::TryReload`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["weapon_no_ammo"],
-      cb?: ((this: void, object: game_object, suitable_ammo_total: i32) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, object: game_object, suitable_ammo_total: i32) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 36 Callback executed on hud animation stop.
-     * Called from CHudItem class internals.
+     * Fired when a HUD item animation ends.
+     *
+     * @source `src/xrGame/HudItem.cpp`, `CHudItem::OnAnimationEnd`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["hud_animation_end"],
-      cb?:
-        | ((
-            this: void,
-            object: game_object,
-            hud_section: string,
-            current_motion: string,
-            state: u32,
-            animation_slot: u32
-          ) => void)
-        | null,
-      object?: Maybe<T>
+      cb?: Nillable<
+        (
+          this: void,
+          object: game_object,
+          hud_section: string,
+          current_motion: string,
+          state: u32,
+          animation_slot: u32
+        ) => void
+      >,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 37 todo;.
+     * Fired when the actor receives a keyboard press before UI and game input handling.
+     *
+     * @source `src/xrGame/Level_input.cpp`, `CLevel::IR_OnKeyboardPress`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["key_press"],
-      cb?: ((this: void, key: i32) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, key: i32) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 38 todo;.
+     * Fired when the actor receives a keyboard release before UI and game input handling.
+     *
+     * @source `src/xrGame/Level_input.cpp`, `CLevel::IR_OnKeyboardRelease`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["key_release"],
-      cb?: ((this: void, key: i32) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, key: i32) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 39 todo;.
+     * Fired when the actor receives a keyboard hold before normal input handling.
+     *
+     * @source `src/xrGame/Level_input.cpp`, `CLevel::IR_OnKeyboardHold`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["key_hold"],
-      cb?: ((this: void, key: i32) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, key: i32) => void>,
+      object?: Nillable<T>
     ): void;
 
-    // 40 todo: mouse_move
+    /**
+     * Fired when the actor receives a mouse movement event before normal input handling.
+     *
+     * @source `src/xrGame/Level_input.cpp`, `CLevel::IR_OnMouseMove`.
+     */
+    public set_callback<T extends AnyObject>(
+      type: TXR_callbacks["mouse_move"],
+      cb?: Nillable<(this: void, dx: i32, dy: i32) => void>,
+      object?: Nillable<T>
+    ): void;
 
-    // 41 todo: mouse_wheel
+    /**
+     * Fired when the actor receives a mouse wheel event before normal input handling.
+     *
+     * @source `src/xrGame/Level_input.cpp`, `CLevel::IR_OnMouseWheel`.
+     *
+     * @remarks
+     * The engine passes wheel deltas as `(y, x)`.
+     */
+    public set_callback<T extends AnyObject>(
+      type: TXR_callbacks["mouse_wheel"],
+      cb?: Nillable<(this: void, y: number, x: number) => void>,
+      object?: Nillable<T>
+    ): void;
 
-    // 42 todo: controller_press
+    /**
+     * Fired when the actor receives a controller press event before normal input handling.
+     *
+     * @source `src/xrGame/Level_input.cpp`, `CLevel::IR_OnControllerPress`.
+     */
+    public set_callback<T extends AnyObject>(
+      type: TXR_callbacks["controller_press"],
+      cb?: Nillable<(this: void, key: i32, state: AnyObject) => void>,
+      object?: Nillable<T>
+    ): void;
 
-    // 43 todo: controller_release
+    /**
+     * Fired when the actor receives a controller release event before normal input handling.
+     *
+     * @source `src/xrGame/Level_input.cpp`, `CLevel::IR_OnControllerRelease`.
+     */
+    public set_callback<T extends AnyObject>(
+      type: TXR_callbacks["controller_release"],
+      cb?: Nillable<(this: void, key: i32, state: AnyObject) => void>,
+      object?: Nillable<T>
+    ): void;
 
-    // 44 todo: controller_hold
+    /**
+     * Fired when the actor receives a controller hold event before normal input handling.
+     *
+     * @source `src/xrGame/Level_input.cpp`, `CLevel::IR_OnControllerHold`.
+     */
+    public set_callback<T extends AnyObject>(
+      type: TXR_callbacks["controller_hold"],
+      cb?: Nillable<(this: void, key: i32, state: AnyObject) => void>,
+      object?: Nillable<T>
+    ): void;
 
-    // 45 todo: controller_attitude_change
+    /**
+     * Fired when the actor receives a controller attitude change event before normal input handling.
+     *
+     * @source `src/xrGame/Level_input.cpp`, `CLevel::IR_OnControllerAttitudeChange`.
+     */
+    public set_callback<T extends AnyObject>(
+      type: TXR_callbacks["controller_attitude_change"],
+      cb?: Nillable<(this: void, change: vector) => void>,
+      object?: Nillable<T>
+    ): void;
 
     /**
-     * 46 todo: item_to_belt.
+     * Fired when an inventory owner moves an item to the belt.
+     *
+     * @source `src/xrGame/InventoryOwner.cpp`, `CInventoryOwner::OnItemBelt`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["item_to_belt"],
-      cb?: ((this: void, object: game_object) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, object: game_object) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 47 todo: item_to_slot.
+     * Fired when an inventory owner moves an item to a slot.
+     *
+     * @source `src/xrGame/InventoryOwner.cpp`, `CInventoryOwner::OnItemSlot`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["item_to_slot"],
-      cb?: ((this: void, object: game_object) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, object: game_object) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 48 todo: item_to_ruck.
+     * Fired when an inventory owner moves an item to the rucksack.
+     *
+     * @source `src/xrGame/InventoryOwner.cpp`, `CInventoryOwner::OnItemRuck`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["item_to_ruck"],
-      cb?: ((this: void, object: game_object) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, object: game_object) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 49 Callback executed when weapon is zoomed in.
+     * Fired when a weapon owner zooms in with a magazined weapon.
+     *
+     * @source `src/xrGame/WeaponMagazined.cpp`, `CWeaponMagazined::OnZoomIn`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["weapon_zoom_in"],
-      cb?: ((this: void, owner: game_object, weapon: game_object) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, owner: game_object, weapon: game_object) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 50 Callback executed when weapon is zoomed out.
+     * Fired when a weapon owner zooms out with a magazined weapon.
+     *
+     * @source `src/xrGame/WeaponMagazined.cpp`, `CWeaponMagazined::OnZoomOut`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["weapon_zoom_out"],
-      cb?: ((this: void, owner: game_object, weapon: game_object) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, owner: game_object, weapon: game_object) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 51 Callback executed when magazine ammo is elapsed and empty.
+     * Fired when a magazined weapon misfires.
+     *
+     * @source `src/xrGame/WeaponMagazined.cpp`, `CWeaponMagazined::OnShot` misfire path.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["weapon_jammed"],
-      cb?: ((this: void, owner: game_object, weapon: game_object) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, owner: game_object, weapon: game_object) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 52 Callback executed when magazine ammo is elapsed and empty.
+     * Fired when an actor-owned magazined weapon becomes empty or unloads its magazine.
+     *
+     * @source `src/xrGame/WeaponMagazined.cpp`, `CWeaponMagazined::OnMagazineEmpty` and `CWeaponMagazined::UnloadMagazine`.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["weapon_magazine_empty"],
-      cb?: ((this: void, object: game_object, suitable_ammo_total: i32) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, object: game_object, suitable_ammo_total: i32) => void>,
+      object?: Nillable<T>
     ): void;
 
     /**
-     * 53 todo: actor_before_death.
+     * Fired before actor death handling when the engine callback gate is enabled.
+     *
+     * @source `src/xrGame/Entity.cpp`, `CEntity::KillEntity` under `ACTOR_BEFORE_DEATH_CALLBACK`.
+     *
+     * @remarks
+     * The callback receives the id of the object that caused the actor death path.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["actor_before_death"],
-      cb?: ((this: void, killer_id: u16) => void) | null,
-      object?: Maybe<T>
+      cb?: Nillable<(this: void, killer_id: u16) => void>,
+      object?: Nillable<T>
     ): void;
 
-    // 54 todo: on_attach_vehicle
+    /**
+     * Fired when the actor attaches to a vehicle or mounted weapon.
+     *
+     * @source `src/xrGame/ActorVehicle.cpp` and `src/xrGame/ActorMountedWeapon.cpp`.
+     */
+    public set_callback<T extends AnyObject>(
+      type: TXR_callbacks["on_attach_vehicle"],
+      cb?: Nillable<(this: void, vehicle: game_object) => void>,
+      object?: Nillable<T>
+    ): void;
 
-    // 55 todo: on_detach_vehicle
+    /**
+     * Fired when the actor detaches from a vehicle or mounted weapon.
+     *
+     * @source `src/xrGame/ActorVehicle.cpp` and `src/xrGame/ActorMountedWeapon.cpp`.
+     */
+    public set_callback<T extends AnyObject>(
+      type: TXR_callbacks["on_detach_vehicle"],
+      cb?: Nillable<(this: void, vehicle: game_object) => void>,
+      object?: Nillable<T>
+    ): void;
 
-    // 56 todo: on_use_vehicle
+    /**
+     * Fired when the actor uses a vehicle without attaching to it.
+     *
+     * @source `src/xrGame/ActorVehicle.cpp`, `CActor::use_Vehicle`.
+     */
+    public set_callback<T extends AnyObject>(
+      type: TXR_callbacks["on_use_vehicle"],
+      cb?: Nillable<(this: void, vehicle: game_object) => void>,
+      object?: Nillable<T>
+    ): void;
 
     /**
      * Clear all callbacks registered on this object.
@@ -806,7 +1126,7 @@ declare module "xray16" {
      * @param cb - Callback called with current patrol point index.
      * @param object - Optional Lua context.
      */
-    public set_patrol_extrapolate_callback(cb?: ((cur_pt: number) => boolean) | null, object?: object): void;
+    public set_patrol_extrapolate_callback(cb?: Nillable<(cur_pt: number) => boolean>, object?: object): void;
 
     /**
      * Set or clear smart-cover target selection callback.
@@ -814,6 +1134,9 @@ declare module "xray16" {
      * @param cb - Callback that receives this object when a smart-cover target is selected.
      * @param object - Optional Lua context.
      */
-    public set_smart_cover_target_selector(cb?: ((object: game_object) => void) | null, object?: object | null): void;
+    public set_smart_cover_target_selector(
+      cb?: Nillable<(object: game_object) => void>,
+      object?: Nillable<object>
+    ): void;
   }
 }