xray16 1.6.3 → 1.6.4

package/xray16.d.ts

@@ -559,7 +559,12 @@ declare module "xray16" {
      * @param pathType - Detail path type id.
      * @param game_object - Target object.
      */
-    public constructor(bodyState: TXR_body_state, movementType: TXR_movement_type, pathType: TXR_detail_path_type, game_object: game_object);
+    public constructor(
+      bodyState: TXR_body_state,
+      movementType: TXR_movement_type,
+      pathType: TXR_detail_path_type,
+      game_object: game_object
+    );
 
     /**
      * Move toward an object with a speed value.
@@ -586,7 +591,12 @@ declare module "xray16" {
      * @param pathType - Detail path type id.
      * @param patrol - Patrol path parameters.
      */
-    public constructor(bodyState: TXR_body_state, movementType: TXR_movement_type, pathType: TXR_detail_path_type, patrol: patrol);
+    public constructor(
+      bodyState: TXR_body_state,
+      movementType: TXR_movement_type,
+      pathType: TXR_detail_path_type,
+      patrol: patrol
+    );
 
     /**
      * Move along a patrol path with a speed value.
@@ -597,7 +607,13 @@ declare module "xray16" {
      * @param patrol - Patrol path parameters.
      * @param value - Speed or distance value.
      */
-    public constructor(bodyState: TXR_body_state, movementType: TXR_movement_type, pathType: TXR_detail_path_type, patrol: patrol, value: f32);
+    public constructor(
+      bodyState: TXR_body_state,
+      movementType: TXR_movement_type,
+      pathType: TXR_detail_path_type,
+      patrol: patrol,
+      value: f32
+    );
 
     /**
      * Move toward a position.
@@ -607,7 +623,12 @@ declare module "xray16" {
      * @param pathType - Detail path type id.
      * @param vector - Target position.
      */
-    public constructor(bodyState: TXR_body_state, movementType: TXR_movement_type, pathType: TXR_detail_path_type, vector: vector);
+    public constructor(
+      bodyState: TXR_body_state,
+      movementType: TXR_movement_type,
+      pathType: TXR_detail_path_type,
+      vector: vector
+    );
 
     /**
      * Move toward a position with a speed value.
@@ -618,7 +639,13 @@ declare module "xray16" {
      * @param vector - Target position.
      * @param value - Speed or distance value.
      */
-    public constructor(bodyState: TXR_body_state, movementType: TXR_movement_type, pathType: TXR_detail_path_type, vector: vector, value: f32);
+    public constructor(
+      bodyState: TXR_body_state,
+      movementType: TXR_movement_type,
+      pathType: TXR_detail_path_type,
+      vector: vector,
+      value: f32
+    );
 
     /**
      * Move toward a position with distance.
@@ -3764,11 +3791,15 @@ declare module "xray16" {
   }
 
   /**
+   * Script-visible class id constant names from `clsid`.
+   *
    * @group xr_alife
    */
   export type TXR_class_key = EnumeratedStaticsKeys<typeof clsid>;
 
   /**
+   * Numeric engine class id values from `clsid`.
+   *
    * @group xr_alife
    */
   export type TXR_class_id = EnumeratedStaticsValues<typeof clsid>;
@@ -5501,47 +5532,47 @@ declare module "xray16" {
     /**
      * Engine enum value for `danger_object.attack_sound`.
      */
-    public static attack_sound: 1;
+    public static readonly attack_sound: 1;
     /**
      * Engine enum value for `danger_object.attacked`.
      */
-    public static attacked: 5;
+    public static readonly attacked: 5;
     /**
      * Engine enum value for `danger_object.bullet_ricochet`.
      */
-    public static bullet_ricochet: 0;
+    public static readonly bullet_ricochet: 0;
     /**
      * Engine enum value for `danger_object.enemy_sound`.
      */
-    public static enemy_sound: 7;
+    public static readonly enemy_sound: 7;
     /**
      * Engine enum value for `danger_object.entity_attacked`.
      */
-    public static entity_attacked: 2;
+    public static readonly entity_attacked: 2;
     /**
      * Engine enum value for `danger_object.entity_corpse`.
      */
-    public static entity_corpse: 4;
+    public static readonly entity_corpse: 4;
     /**
      * Engine enum value for `danger_object.entity_death`.
      */
-    public static entity_death: 3;
+    public static readonly entity_death: 3;
     /**
      * Engine enum value for `danger_object.grenade`.
      */
-    public static grenade: 6;
+    public static readonly grenade: 6;
     /**
      * Engine enum value for `danger_object.hit`.
      */
-    public static hit: 2;
+    public static readonly hit: 2;
     /**
      * Engine enum value for `danger_object.sound`.
      */
-    public static sound: 1;
+    public static readonly sound: 1;
     /**
      * Engine enum value for `danger_object.visual`.
      */
-    public static visual: 0;
+    public static readonly visual: 0;
 
     /**
      * @returns Danger type.
@@ -5590,7 +5621,8 @@ declare module "xray16" {
    * @source C++ enum CDangerObject::EDangerPerceiveType
    * @group xr_memory
    */
-  export type TXR_danger_perceive_type = typeof danger_object.visual | typeof danger_object.sound | typeof danger_object.hit;
+  export type TXR_danger_perceive_type =
+    typeof danger_object.visual | typeof danger_object.sound | typeof danger_object.hit;
   /**
    * @group xr_memory
    */
@@ -7212,67 +7244,67 @@ declare module "xray16" {
     /**
      * Clamp listed paths by extension.
      */
-    public static FS_ClampExt: 4;
+    public static readonly FS_ClampExt: 4;
 
     /**
      * List files.
      */
-    public static FS_ListFiles: 1;
+    public static readonly FS_ListFiles: 1;
 
     /**
      * List folders.
      */
-    public static FS_ListFolders: 2;
+    public static readonly FS_ListFolders: 2;
 
     /**
      * Do not recurse into subfolders.
      */
-    public static FS_RootOnly: 8;
+    public static readonly FS_RootOnly: 8;
 
     /**
      * Sort by modification time, newest first.
      */
-    public static FS_sort_by_modif_down: 5;
+    public static readonly FS_sort_by_modif_down: 5;
 
     /**
      * Sort by modification time, oldest first.
      */
-    public static FS_sort_by_modif_up: 4;
+    public static readonly FS_sort_by_modif_up: 4;
 
     /**
      * Sort by name descending.
      */
-    public static FS_sort_by_name_down: 1;
+    public static readonly FS_sort_by_name_down: 1;
 
     /**
      * Sort by name ascending.
      */
-    public static FS_sort_by_name_up: 0;
+    public static readonly FS_sort_by_name_up: 0;
 
     /**
      * Sort by size descending.
      */
-    public static FS_sort_by_size_down: 3;
+    public static readonly FS_sort_by_size_down: 3;
 
     /**
      * Sort by size ascending.
      */
-    public static FS_sort_by_size_up: 2;
+    public static readonly FS_sort_by_size_up: 2;
 
     /**
      * Search virtual registered files only.
      */
-    public static FSType_Virtual: 1;
+    public static readonly FSType_Virtual: 1;
 
     /**
      * Search external files only.
      */
-    public static FSType_External: 2;
+    public static readonly FSType_External: 2;
 
     /**
      * Search virtual and external files.
      */
-    public static FSType_Any: 3;
+    public static readonly FSType_Any: 3;
 
     /**
      * Delete a directory below a path alias.
@@ -7542,9 +7574,14 @@ declare module "xray16" {
   }
 
   /**
-   * Filesystem enum value accepted by filesystem queries.
+   * Filesystem scope accepted by `FS.exist()` and related path queries.
    *
+   * @source `src/xrGame/fs_registrator_script.cpp`, `FS.FSType` enum.
    * @group xr_fs
+   *
+   * @remarks
+   * `FSType_Virtual` searches mounted game paths, `FSType_External` searches external filesystem paths, and
+   * `FSType_Any` allows either source.
    */
   export type TXR_fs_type = typeof FS.FSType_Virtual | typeof FS.FSType_External | typeof FS.FSType_Any;
 
@@ -7579,7 +7616,7 @@ declare module "xray16" {
    * - eGameIDArtefactHunt = u32(1) << 3,
    * - eGameIDCaptureTheArtefact = u32(1) << 4,
    * - eGameIDDominationZone = u32(1) << 5,
-   * - eGameIDTeamDominationZone = u32(1) << 6,.
+   * - eGameIDTeamDominationZone = u32(1) << 6.
    *
    * @source C++ enum EGameIDs
    * @group xr_game
@@ -7655,7 +7692,13 @@ declare module "xray16" {
   }
 
   /**
+   * Legacy game type constants exposed through the `GAME_TYPE` Lua class.
+   *
    * @group xr_game
+   *
+   * @remarks
+   * `GAME_TYPE.GAME_*` values are UI/menu constants and are not the same set as the `EGameIDs` bitmask values returned
+   * by `level.game_id()`.
    */
   export type TXR_GAME_TYPE = EnumeratedStaticsValues<typeof GAME_TYPE>;
 
@@ -8576,9 +8619,14 @@ declare module "xray16" {
   }
 
   /**
-   * Ray query target bitmask value.
+   * Ray query target bitmask accepted by `level.ray_pick()` and `ray_pick.set_flags()`.
    *
+   * @source `src/xrGame/level_script.cpp`, `rq_target` binding.
    * @group xr_level
+   *
+   * @remarks
+   * Values are bit flags from `collide::rq_target`. Combined constants such as `rqtBoth` and `rqtDyn` are precomputed
+   * masks exported by the engine, not separate target categories.
    */
   export type TXR_rq_target = EnumeratedStaticsValues<typeof rq_target>;
 
@@ -8756,6 +8804,7 @@ declare module "xray16" {
      */
     public get_element(): i32;
   }
+
   /**
    * Global helpers for the currently loaded level.
    *
@@ -11656,91 +11705,91 @@ declare module "xray16" {
     /**
      * Engine enum value for `game_messages.GAME_EVENT_ARTEFACT_DESTROYED`.
      */
-    public static GAME_EVENT_ARTEFACT_DESTROYED: 17;
+    public static readonly GAME_EVENT_ARTEFACT_DESTROYED: 17;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_ARTEFACT_DROPPED`.
      */
-    public static GAME_EVENT_ARTEFACT_DROPPED: 19;
+    public static readonly GAME_EVENT_ARTEFACT_DROPPED: 19;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_ARTEFACT_ONBASE`.
      */
-    public static GAME_EVENT_ARTEFACT_ONBASE: 20;
+    public static readonly GAME_EVENT_ARTEFACT_ONBASE: 20;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_ARTEFACT_SPAWNED`.
      */
-    public static GAME_EVENT_ARTEFACT_SPAWNED: 16;
+    public static readonly GAME_EVENT_ARTEFACT_SPAWNED: 16;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_ARTEFACT_TAKEN`.
      */
-    public static GAME_EVENT_ARTEFACT_TAKEN: 18;
+    public static readonly GAME_EVENT_ARTEFACT_TAKEN: 18;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_BUY_MENU_CLOSED`.
      */
-    public static GAME_EVENT_BUY_MENU_CLOSED: 23;
+    public static readonly GAME_EVENT_BUY_MENU_CLOSED: 23;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_PLAYER_BUY_FINISHED`.
      */
-    public static GAME_EVENT_PLAYER_BUY_FINISHED: 2;
+    public static readonly GAME_EVENT_PLAYER_BUY_FINISHED: 2;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_PLAYER_CHANGE_SKIN`.
      */
-    public static GAME_EVENT_PLAYER_CHANGE_SKIN: 6;
+    public static readonly GAME_EVENT_PLAYER_CHANGE_SKIN: 6;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_PLAYER_CHANGE_TEAM`.
      */
-    public static GAME_EVENT_PLAYER_CHANGE_TEAM: 6;
+    public static readonly GAME_EVENT_PLAYER_CHANGE_TEAM: 6;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_PLAYER_CONNECTED`.
      */
-    public static GAME_EVENT_PLAYER_CONNECTED: 8;
+    public static readonly GAME_EVENT_PLAYER_CONNECTED: 8;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_PLAYER_DISCONNECTED`.
      */
-    public static GAME_EVENT_PLAYER_DISCONNECTED: 9;
+    public static readonly GAME_EVENT_PLAYER_DISCONNECTED: 9;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_PLAYER_ENTER_TEAM_BASE`.
      */
-    public static GAME_EVENT_PLAYER_ENTER_TEAM_BASE: 21;
+    public static readonly GAME_EVENT_PLAYER_ENTER_TEAM_BASE: 21;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_PLAYER_JOIN_TEAM`.
      */
-    public static GAME_EVENT_PLAYER_JOIN_TEAM: 13;
+    public static readonly GAME_EVENT_PLAYER_JOIN_TEAM: 13;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_PLAYER_KILL`.
      */
-    public static GAME_EVENT_PLAYER_KILL: 1;
+    public static readonly GAME_EVENT_PLAYER_KILL: 1;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_PLAYER_KILLED`.
      */
-    public static GAME_EVENT_PLAYER_KILLED: 11;
+    public static readonly GAME_EVENT_PLAYER_KILLED: 11;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_PLAYER_LEAVE_TEAM_BASE`.
      */
-    public static GAME_EVENT_PLAYER_LEAVE_TEAM_BASE: 22;
+    public static readonly GAME_EVENT_PLAYER_LEAVE_TEAM_BASE: 22;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_PLAYER_READY`.
      */
-    public static GAME_EVENT_PLAYER_READY: 0;
+    public static readonly GAME_EVENT_PLAYER_READY: 0;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_ROUND_END`.
      */
-    public static GAME_EVENT_ROUND_END: 15;
+    public static readonly GAME_EVENT_ROUND_END: 15;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_ROUND_STARTED`.
      */
-    public static GAME_EVENT_ROUND_STARTED: 14;
+    public static readonly GAME_EVENT_ROUND_STARTED: 14;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_SCRIPT_BEGINS_FROM`.
      */
-    public static GAME_EVENT_SCRIPT_BEGINS_FROM: 46;
+    public static readonly GAME_EVENT_SCRIPT_BEGINS_FROM: 46;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_SKIN_MENU_CLOSED`.
      */
-    public static GAME_EVENT_SKIN_MENU_CLOSED: 25;
+    public static readonly GAME_EVENT_SKIN_MENU_CLOSED: 25;
     /**
      * Engine enum value for `game_messages.GAME_EVENT_TEAM_MENU_CLOSED`.
      */
-    public static GAME_EVENT_TEAM_MENU_CLOSED: 24;
+    public static readonly GAME_EVENT_TEAM_MENU_CLOSED: 24;
 
     /**
      * Engine-owned multiplayer event constants.
@@ -11995,10 +12044,14 @@ declare module "xray16" {
   export const PROFILER_TYPE_SAMPLING: 2;
 
   /**
-   * Lua profiler mode accepted by `profiler.start`.
+   * Lua profiler mode accepted by `profiler.start()`.
    *
    * @source C++ enum CScriptProfilerType
    * @group xr_profiler
+   *
+   * @remarks
+   * Hook mode records Lua call/return events. Sampling mode uses the LuaJIT profiler. `PROFILER_TYPE_NONE` is exposed
+   * for status reporting and does not start profiling.
    */
   export type TXR_ProfilerType = typeof PROFILER_TYPE_NONE | typeof PROFILER_TYPE_HOOK | typeof PROFILER_TYPE_SAMPLING;
 
@@ -12548,14 +12601,38 @@ declare module "xray16" {
     /**
      * Create a runtime token list property bound to a string field.
      */
-    public create_list(items: prop_item_vec, key: string, object: object, name: string, tokens: rtoken_list): list_value;
+    public create_list(
+      items: prop_item_vec,
+      key: string,
+      object: object,
+      name: string,
+      tokens: rtoken_list
+    ): list_value;
 
     /**
      * Create token properties bound to integer fields.
      */
-    public create_token8(items: prop_item_vec, key: string, object: object, name: string, tokens: token_list): token8_value;
-    public create_token16(items: prop_item_vec, key: string, object: object, name: string, tokens: token_list): token16_value;
-    public create_token32(items: prop_item_vec, key: string, object: object, name: string, tokens: token_list): token32_value;
+    public create_token8(
+      items: prop_item_vec,
+      key: string,
+      object: object,
+      name: string,
+      tokens: token_list
+    ): token8_value;
+    public create_token16(
+      items: prop_item_vec,
+      key: string,
+      object: object,
+      name: string,
+      tokens: token_list
+    ): token16_value;
+    public create_token32(
+      items: prop_item_vec,
+      key: string,
+      object: object,
+      name: string,
+      tokens: token_list
+    ): token32_value;
 
     /**
      * Create flag properties bound to integer flag fields.
@@ -12623,7 +12700,15 @@ declare module "xray16" {
       increment?: f32,
       decimals?: i32
     ): float_value;
-    public create_u8(items: prop_item_vec, key: string, object: object, name: string, min?: u8, max?: u8, increment?: u8): u8_value;
+    public create_u8(
+      items: prop_item_vec,
+      key: string,
+      object: object,
+      name: string,
+      min?: u8,
+      max?: u8,
+      increment?: u8
+    ): u8_value;
     public create_u16(
       items: prop_item_vec,
       key: string,
@@ -13062,11 +13147,8 @@ declare module "xray16" {
    * `3` is the native `eRelationTypeWorstEnemy` value; it is not exported as a named Lua enum member.
    */
   export type TXR_relation =
-    | typeof game_object.dummy
-    | typeof game_object.friend
-    | typeof game_object.neutral
-    | typeof game_object.enemy
-    | 3;}
+    typeof game_object.dummy | typeof game_object.friend | typeof game_object.neutral | typeof game_object.enemy | 3;
+}
 
 declare module "xray16" {
   /**
@@ -14125,17 +14207,17 @@ declare module "xray16" {
     /**
      * Spatial 3D playback.
      */
-    public static s3d: 0;
+    public static readonly s3d: 0;
 
     /**
      * Keep playing until stopped.
      */
-    public static looped: 1;
+    public static readonly looped: 1;
 
     /**
      * Screen-space 2D playback.
      */
-    public static s2d: 2;
+    public static readonly s2d: 2;
 
     /**
      * Playback frequency multiplier.
@@ -14338,7 +14420,14 @@ declare module "xray16" {
   }
 
   /**
+   * Playback mode flag accepted by `sound_object.play()` and `play_at_pos()`.
+   *
+   * @source `src/xrGame/script_sound_script.cpp`, `sound_object.sound_play_type` enum.
    * @group xr_sound
+   *
+   * @remarks
+   * `sound_object.looped` keeps playback active until stopped, `sound_object.s2d` plays in screen space, and
+   * `sound_object.s3d` leaves playback spatial.
    */
   export type TXR_sound_object_type = EnumeratedStaticsValues<typeof sound_object>;
 
@@ -14353,187 +14442,187 @@ declare module "xray16" {
     /**
      * Engine enum value for `snd_type.ambient`.
      */
-    public static ambient: 128;
+    public static readonly ambient: 128;
     /**
      * Engine enum value for `snd_type.anomaly`.
      */
-    public static anomaly: 268435456;
+    public static readonly anomaly: 268435456;
     /**
      * Engine enum value for `snd_type.anomaly_idle`.
      */
-    public static anomaly_idle: 268437504;
+    public static readonly anomaly_idle: 268437504;
     /**
      * Engine enum value for `snd_type.attack`.
      */
-    public static attack: 8192;
+    public static readonly attack: 8192;
     /**
      * Engine enum value for `snd_type.bullet_hit`.
      */
-    public static bullet_hit: 524288;
+    public static readonly bullet_hit: 524288;
     /**
      * Engine enum value for `snd_type.die`.
      */
-    public static die: 131072;
+    public static readonly die: 131072;
     /**
      * Engine enum value for `snd_type.drop`.
      */
-    public static drop: 33554432;
+    public static readonly drop: 33554432;
     /**
      * Engine enum value for `snd_type.eat`.
      */
-    public static eat: 4096;
+    public static readonly eat: 4096;
     /**
      * Engine enum value for `snd_type.empty`.
      */
-    public static empty: 1048576;
+    public static readonly empty: 1048576;
     /**
      * Engine enum value for `snd_type.hide`.
      */
-    public static hide: 16777216;
+    public static readonly hide: 16777216;
     /**
      * Engine enum value for `snd_type.idle`.
      */
-    public static idle: 2048;
+    public static readonly idle: 2048;
     /**
      * Engine enum value for `snd_type.injure`.
      */
-    public static injure: 65536;
+    public static readonly injure: 65536;
     /**
      * Engine enum value for `snd_type.item`.
      */
-    public static item: 1073741824;
+    public static readonly item: 1073741824;
     /**
      * Engine enum value for `snd_type.item_drop`.
      */
-    public static item_drop: 1107296256;
+    public static readonly item_drop: 1107296256;
     /**
      * Engine enum value for `snd_type.item_hide`.
      */
-    public static item_hide: 1090519040;
+    public static readonly item_hide: 1090519040;
     /**
      * Engine enum value for `snd_type.item_pick_up`.
      */
-    public static item_pick_up: 1140850688;
+    public static readonly item_pick_up: 1140850688;
     /**
      * Engine enum value for `snd_type.item_take`.
      */
-    public static item_take: 1082130432;
+    public static readonly item_take: 1082130432;
     /**
      * Engine enum value for `snd_type.item_use`.
      */
-    public static item_use: 1077936128;
+    public static readonly item_use: 1077936128;
     /**
      * Engine enum value for `snd_type.monster`.
      */
-    public static monster: 536870912;
+    public static readonly monster: 536870912;
     /**
      * Engine enum value for `snd_type.monster_attack`.
      */
-    public static monster_attack: 536879104;
+    public static readonly monster_attack: 536879104;
     /**
      * Engine enum value for `snd_type.monster_die`.
      */
-    public static monster_die: 537001984;
+    public static readonly monster_die: 537001984;
     /**
      * Engine enum value for `snd_type.monster_eat`.
      */
-    public static monster_eat: 536875008;
+    public static readonly monster_eat: 536875008;
     /**
      * Engine enum value for `snd_type.monster_injure`.
      */
-    public static monster_injure: 536936448;
+    public static readonly monster_injure: 536936448;
     /**
      * Engine enum value for `snd_type.monster_step`.
      */
-    public static monster_step: 536903680;
+    public static readonly monster_step: 536903680;
     /**
      * Engine enum value for `snd_type.monster_talk`.
      */
-    public static monster_talk: 536887296;
+    public static readonly monster_talk: 536887296;
     /**
      * Engine enum value for `snd_type.no_sound`.
      */
-    public static no_sound: 0;
+    public static readonly no_sound: 0;
     /**
      * Engine enum value for `snd_type.object_break`.
      */
-    public static object_break: 1024;
+    public static readonly object_break: 1024;
     /**
      * Engine enum value for `snd_type.object_collide`.
      */
-    public static object_collide: 512;
+    public static readonly object_collide: 512;
     /**
      * Engine enum value for `snd_type.object_explode`.
      */
-    public static object_explode: 256;
+    public static readonly object_explode: 256;
     /**
      * Engine enum value for `snd_type.pick_up`.
      */
-    public static pick_up: 67108864;
+    public static readonly pick_up: 67108864;
     /**
      * Engine enum value for `snd_type.reload`.
      */
-    public static reload: 262144;
+    public static readonly reload: 262144;
     /**
      * Engine enum value for `snd_type.shoot`.
      */
-    public static shoot: 2097152;
+    public static readonly shoot: 2097152;
     /**
      * Engine enum value for `snd_type.step`.
      */
-    public static step: 32768;
+    public static readonly step: 32768;
     /**
      * Engine enum value for `snd_type.take`.
      */
-    public static take: 8388608;
+    public static readonly take: 8388608;
     /**
      * Engine enum value for `snd_type.talk`.
      */
-    public static talk: 16384;
+    public static readonly talk: 16384;
     /**
      * Engine enum value for `snd_type.use`.
      */
-    public static use: 4194304;
+    public static readonly use: 4194304;
     /**
      * Engine enum value for `snd_type.weapon`.
      */
-    public static weapon: -2147483648;
+    public static readonly weapon: -2147483648;
     /**
      * Engine enum value for `snd_type.weapon_bullet_hit`.
      */
-    public static weapon_bullet_hit: -2146959360;
+    public static readonly weapon_bullet_hit: -2146959360;
     /**
      * Engine enum value for `snd_type.weapon_empty`.
      */
-    public static weapon_empty: -2146435072;
+    public static readonly weapon_empty: -2146435072;
     /**
      * Engine enum value for `snd_type.weapon_reload`.
      */
-    public static weapon_reload: -2147221504;
+    public static readonly weapon_reload: -2147221504;
     /**
      * Engine enum value for `snd_type.weapon_shoot`.
      */
-    public static weapon_shoot: -2145386496;
+    public static readonly weapon_shoot: -2145386496;
     /**
      * Engine enum value for `snd_type.world`.
      */
-    public static world: 134217728;
+    public static readonly world: 134217728;
     /**
      * Engine enum value for `snd_type.world_ambient`.
      */
-    public static world_ambient: 134217856;
+    public static readonly world_ambient: 134217856;
     /**
      * Engine enum value for `snd_type.world_object_break`.
      */
-    public static world_object_break: 134218752;
+    public static readonly world_object_break: 134218752;
     /**
      * Engine enum value for `snd_type.world_object_collide`.
      */
-    public static world_object_collide: 134218240;
+    public static readonly world_object_collide: 134218240;
     /**
      * Engine enum value for `snd_type.world_object_explode`.
      */
-    public static world_object_explode: 134217984;
+    public static readonly world_object_explode: 134217984;
 
     /**
      * Engine-owned sound category constants.
@@ -14542,7 +14631,14 @@ declare module "xray16" {
   }
 
   /**
+   * AI sound category bitmask used by sound memory, callbacks, and sound actions.
+   *
+   * @source `src/xrGame/script_sound_action_script.cpp`, `snd_type.sound_types` enum.
    * @group xr_sound
+   *
+   * @remarks
+   * Values combine a broad owner category such as `weapon`, `monster`, or `world` with a concrete event such as
+   * `shoot`, `die`, or `object_collide`. Use `snd_type.no_sound` when no AI sound category should be emitted.
    */
   export type TXR_snd_type = EnumeratedStaticsValues<typeof snd_type>;
 
@@ -14684,38 +14780,49 @@ declare module "xray16" {
   }
 
   /**
+   * Script-visible task state constant names from the `task.task_state` enum.
+   *
+   * @source `src/xrGame/GameTask_script.cpp`, `task.task_state` enum.
    * @group xr_task
    */
   export type TXR_TaskStateName = "fail" | "in_progress" | "completed" | "task_dummy";
 
   /**
-   * ETaskState.
+   * Runtime task state returned by task and objective state APIs.
    *
+   * @source C++ enum ETaskState
    * @group xr_task
+   *
+   * @remarks
+   * `task.task_dummy` is returned for missing tasks or objects that cannot expose task state.
    */
   export type TXR_TaskState =
-    | typeof task.fail
-    | typeof task.in_progress
-    | typeof task.completed
-    | typeof task.task_dummy;
+    typeof task.fail | typeof task.in_progress | typeof task.completed | typeof task.task_dummy;
 
   /**
-   * ETaskType constant names.
+   * Task type constant names, including the shared native dummy sentinel.
    *
+   * @source `src/xrGame/GameTask_script.cpp`, `task.task_type` enum and `task.task_state` dummy export.
    * @group xr_task
+   *
+   * @remarks
+   * `storyline`, `additional`, and `insignificant` are exported by the task type enum. `task_dummy` is exported
+   * by the same `task` class and has the native `ETaskTypeDummy` sentinel value.
    */
   export type TXR_TaskTypeName = "storyline" | "additional" | "insignificant" | "task_dummy";
 
   /**
-   * ETaskType.
+   * Task category used by `SGameTaskObjective.get_type()` and `set_type()`.
    *
+   * @source C++ enum ETaskType
    * @group xr_task
+   *
+   * @remarks
+   * `storyline`, `additional`, and `insignificant` are the script-exposed categories. `task.task_dummy` is kept
+   * in the type because native task APIs can use the dummy sentinel value.
    */
   export type TXR_TaskType =
-    | typeof task.storyline
-    | typeof task.additional
-    | typeof task.insignificant
-    | typeof task.task_dummy;
+    typeof task.storyline | typeof task.additional | typeof task.insignificant | typeof task.task_dummy;
 
   /**
    * One objective inside a game task.
@@ -15063,37 +15170,37 @@ declare module "xray16" {
     /**
      * Date formatting mode: day.
      */
-    public static DateToDay: 0;
+    public static readonly DateToDay: 0;
 
     /**
      * Date formatting mode: month.
      */
-    public static DateToMonth: 1;
+    public static readonly DateToMonth: 1;
 
     /**
      * Date formatting mode: year.
      */
-    public static DateToYear: 2;
+    public static readonly DateToYear: 2;
 
     /**
      * Time formatting mode: hours.
      */
-    public static TimeToHours: 0;
+    public static readonly TimeToHours: 0;
 
     /**
      * Time formatting mode: milliseconds.
      */
-    public static TimeToMilisecs: 3;
+    public static readonly TimeToMilisecs: 3;
 
     /**
      * Time formatting mode: minutes.
      */
-    public static TimeToMinutes: 1;
+    public static readonly TimeToMinutes: 1;
 
     /**
      * Time formatting mode: seconds.
      */
-    public static TimeToSeconds: 2;
+    public static readonly TimeToSeconds: 2;
 
     /**
      * Create an empty time value.
@@ -15300,7 +15407,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CMosquitoBald` anomaly objects.
    *
-   * @source C++ class CMosquitoBald : CGameObject
+   * @source `src/xrGame/MosquitoBald_script.cpp`, `CMosquitoBald` binding.
    * @customConstructor CMosquitoBald
    * @group xr_anomaly
    *
@@ -15312,7 +15419,7 @@ declare module "xray16" {
   /**
    * Client object binding for torch items.
    *
-   * @source C++ class CTorch : CGameObject
+   * @source `src/xrGame/torch_script.cpp`, `CTorch` binding.
    * @customConstructor CTorch
    * @group xr_anomaly
    *
@@ -15324,7 +15431,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CTorridZone` anomaly objects.
    *
-   * @source C++ class CTorridZone : CGameObject
+   * @source `src/xrGame/MosquitoBald_script.cpp`, `CTorridZone` binding.
    * @customConstructor CTorridZone
    * @group xr_anomaly
    */
@@ -15333,7 +15440,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CRadioactiveZone` anomaly objects.
    *
-   * @source C++ class CRadioactiveZone : CGameObject
+   * @source `src/xrGame/mincer_script.cpp`, `CRadioactiveZone` binding.
    * @customConstructor CRadioactiveZone
    * @group xr_anomaly
    */
@@ -15342,7 +15449,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CMincer` anomaly objects.
    *
-   * @source C++ class CMincer : CGameObject
+   * @source `src/xrGame/mincer_script.cpp`, `CMincer` binding.
    * @customConstructor CMincer
    * @group xr_anomaly
    */
@@ -15351,7 +15458,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CFracture` anomaly objects.
    *
-   * @source C++ class CFracture : CGameObject
+   * @source `src/xrGame/ai/monsters/fracture/fracture_script.cpp`, `CFracture` binding.
    * @customConstructor CFracture
    * @group xr_anomaly
    */
@@ -15360,23 +15467,49 @@ declare module "xray16" {
   /**
    * Client object binding for `CHairsZone` anomaly objects.
    *
-   * @source C++ class CHairsZone : CGameObject
+   * @source `src/xrGame/HairsZone_script.cpp`, `CHairsZone` binding.
    * @customConstructor CHairsZone
    * @group xr_anomaly
    */
   export class CHairsZone extends CGameObject {}
+
+  /**
+   * Client object binding for `CAmebaZone` anomaly objects.
+   *
+   * @source `src/xrGame/HairsZone_script.cpp`, `CAmebaZone` binding.
+   * @customConstructor CAmebaZone
+   * @group xr_anomaly
+   *
+   * @remarks
+   * Registered together with hair and no-gravity anomaly zones. Generic anomaly helpers are available through
+   * `CCustomZone`/`game_object` after checking the runtime class.
+   */
+  export class CAmebaZone extends CGameObject {}
+
+  /**
+   * Client object binding for `CNoGravityZone` anomaly objects.
+   *
+   * @source `src/xrGame/HairsZone_script.cpp`, `CNoGravityZone` binding.
+   * @customConstructor CNoGravityZone
+   * @group xr_anomaly
+   *
+   * @remarks
+   * Registered by the hair-zone script binding as a concrete anomaly wrapper.
+   */
+  export class CNoGravityZone extends CGameObject {}
 }
 
 declare module "xray16" {
   /**
    * Client-side artefact object.
    *
-   * @source C++ class CArtefact : CGameObject
+   * @source `src/xrGame/artefact_script.cpp`, `CArtefact` binding.
    * @customConstructor CArtefact
    * @group xr_artefact
    *
    * @remarks
-   * Scripts usually reach this wrapper through `game_object.cast_Artefact()` after checking `is_artefact()`.
+   * Scripts usually reach this wrapper through `game_object.cast_Artefact()` after checking `is_artefact()`. Path and
+   * visibility helpers only affect artefacts with detector support.
    */
   export class CArtefact extends CGameObject {
     /**
@@ -15385,14 +15518,15 @@ declare module "xray16" {
     public constructor();
 
     /**
-     * Move the artefact along a patrol path.
+     * Move the artefact detector helper along a patrol path.
      *
      * @remarks
-     * Requires a patrol path with the given name. The point index must refer to an existing path point.
+     * Native code delegates to detector support when it exists. Missing detector support makes this a no-op. The vector
+     * parameter is stored as movement force, not as an initial world position.
      *
      * @param path_name - Patrol path name.
      * @param point_index - Starting path point index.
-     * @param position - Initial position.
+     * @param position - Movement force used by detector support.
      */
     public FollowByPath(path_name: string, point_index: i32, position: vector): void;
 
@@ -15402,10 +15536,11 @@ declare module "xray16" {
     public GetAfRank(): u8;
 
     /**
-     * Show or hide the artefact.
+     * Show or hide the artefact detector helper.
      *
      * @remarks
-     * This changes the artefact's client visibility; it does not spawn or destroy the object.
+     * Native code delegates to detector support when it exists. Missing detector support makes this a no-op; it does
+     * not spawn or destroy the artefact object.
      *
      * @param is_visible - New visibility state.
      */
@@ -15415,7 +15550,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CZudaArtefact` artefacts.
    *
-   * @source C++ class CZudaArtefact : CArtefact
+   * @source `src/xrGame/artefact_script.cpp`, `CZudaArtefact` binding.
    * @customConstructor CZudaArtefact
    * @group xr_artefact
    */
@@ -15424,7 +15559,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CThornArtefact` artefacts.
    *
-   * @source C++ class CThornArtefact : CArtefact
+   * @source `src/xrGame/artefact_script.cpp`, `CThornArtefact` binding.
    * @customConstructor CThornArtefact
    * @group xr_artefact
    */
@@ -15433,7 +15568,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CBastArtefact` artefacts.
    *
-   * @source C++ class CBastArtefact : CArtefact
+   * @source `src/xrGame/artefact_script.cpp`, `CBastArtefact` binding.
    * @customConstructor CBastArtefact
    * @group xr_artefact
    */
@@ -15442,7 +15577,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CBlackDrops` artefacts.
    *
-   * @source C++ class CBlackDrops : CArtefact
+   * @source `src/xrGame/artefact_script.cpp`, `CBlackDrops` binding.
    * @customConstructor CBlackDrops
    * @group xr_artefact
    */
@@ -15451,7 +15586,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CBlackGraviArtefact` artefacts.
    *
-   * @source C++ class CBlackGraviArtefact : CArtefact
+   * @source `src/xrGame/artefact_script.cpp`, `CBlackGraviArtefact` binding.
    * @customConstructor CBlackGraviArtefact
    * @group xr_artefact
    */
@@ -15460,7 +15595,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CDummyArtefact` artefacts.
    *
-   * @source C++ class CDummyArtefact : CArtefact
+   * @source `src/xrGame/artefact_script.cpp`, `CDummyArtefact` binding.
    * @customConstructor CDummyArtefact
    * @group xr_artefact
    */
@@ -15469,7 +15604,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CElectricBall` artefacts.
    *
-   * @source C++ class CElectricBall : CArtefact
+   * @source `src/xrGame/artefact_script.cpp`, `CElectricBall` binding.
    * @customConstructor CElectricBall
    * @group xr_artefact
    */
@@ -15478,7 +15613,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CFadedBall` artefacts.
    *
-   * @source C++ class CFadedBall : CArtefact
+   * @source `src/xrGame/artefact_script.cpp`, `CFadedBall` binding.
    * @customConstructor CFadedBall
    * @group xr_artefact
    */
@@ -15487,7 +15622,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CGalantineArtefact` artefacts.
    *
-   * @source C++ class CGalantineArtefact : CArtefact
+   * @source `src/xrGame/artefact_script.cpp`, `CGalantineArtefact` binding.
    * @customConstructor CGalantineArtefact
    * @group xr_artefact
    */
@@ -15496,7 +15631,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CGraviArtefact` artefacts.
    *
-   * @source C++ class CGraviArtefact : CArtefact
+   * @source `src/xrGame/artefact_script.cpp`, `CGraviArtefact` binding.
    * @customConstructor CGraviArtefact
    * @group xr_artefact
    */
@@ -15505,7 +15640,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CMercuryBall` artefacts.
    *
-   * @source C++ class CMercuryBall : CArtefact
+   * @source `src/xrGame/artefact_script.cpp`, `CMercuryBall` binding.
    * @customConstructor CMercuryBall
    * @group xr_artefact
    */
@@ -15514,7 +15649,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CRustyHairArtefact` artefacts.
    *
-   * @source C++ class CRustyHairArtefact : CArtefact
+   * @source `src/xrGame/artefact_script.cpp`, `CRustyHairArtefact` binding.
    * @customConstructor CRustyHairArtefact
    * @group xr_artefact
    */
@@ -15525,12 +15660,13 @@ declare module "xray16" {
   /**
    * Base engine object exposed for compatibility with script binders.
    *
-   * @source C++ class DLL_Pure
+   * @source `src/xrGame/base_client_classes_script.cpp`, `DLL_Pure` binding.
    * @customConstructor DLL_Pure
    * @group xr_core
    *
    * @remarks
-   * Base for engine-owned client objects. Scripts normally receive derived objects from xray callbacks or casts.
+   * Backward-compatible script name for the native `IFactoryObject` base. It is exposed as `DLL_Pure` for existing mod
+   * scripts, while most gameplay code receives derived client objects from engine callbacks or casts.
    */
   export class DLL_Pure extends EngineBinding {
     /**
@@ -15542,34 +15678,35 @@ declare module "xray16" {
   /**
    * Render visual handle for client objects.
    *
-   * @source C++ class IRender_Visual
+   * @source `src/xrGame/base_client_classes_script.cpp`, `IRender_Visual` binding.
    * @group xr_client_object
    *
    * @remarks
-   * Visual handles are owned by the object. Treat returned cast interfaces as borrowed engine references.
+   * Visual handles are owned by the object. Cast helpers return borrowed engine interfaces and can return `null` when
+   * the underlying visual does not implement the requested interface.
    */
   export interface IXR_IRender_Visual {
     /**
      * Cast the visual to animated kinematics when supported.
      *
      * @remarks
-     * Runtime can return `null` when the visual is not animated even though older declarations expose a non-null type.
+     * Returns `null` when the visual is not animated. The native default implementation returns `nullptr`.
      *
      * @returns Animated kinematics interface.
      */
-    dcast_PKinematicsAnimated(): IKinematicsAnimated;
+    dcast_PKinematicsAnimated(): Nullable<IKinematicsAnimated>;
   }
 
   /**
    * Base client-side game object.
    *
-   * @source C++ class CGameObject : DLL_Pure, ISheduled, ICollidable, IRenderable
+   * @source `src/xrGame/base_client_classes_script.cpp`, `CGameObject` binding.
    * @customConstructor CGameObject
    * @group xr_client_object
    *
    * @remarks
-   * Client-side object state is engine-owned. Use this wrapper for low-level engine callbacks; gameplay scripts usually
-   * work with `game_object` instead.
+   * Client-side object state is engine-owned. The binding exposes low-level lifecycle hooks used by custom client
+   * subclasses; ordinary gameplay scripts usually work with the higher-level `game_object` wrapper instead.
    */
   export class CGameObject extends DLL_Pure {
     /**
@@ -15634,21 +15771,27 @@ declare module "xray16" {
   /**
    * Class to link client side object with script object entity.
    *
-   * @source C++ class object_binder
+   * @source `src/xrGame/script_binder_object_script.cpp`, `object_binder` binding.
    * @customConstructor object_binder
    * @group xr_client_object
    *
    * @remarks
-   * Script binders are callbacks attached to a `game_object`. The engine calls lifecycle methods; scripts usually
-   * override them in subclasses instead of invoking them directly.
+   * Script binders are callbacks attached to a `game_object`. The engine calls lifecycle methods through wrapper
+   * fallbacks, so script subclasses can override these methods and call `super` when they need base behavior.
    */
   export class object_binder<T = game_object> extends EngineBinding {
     /**
      * Script game object controlled by this binder.
+     *
+     * @remarks
+     * Bound through luabind `def_readwrite`, but consumers should normally treat the binder target as stable after
+     * construction.
      */
     public readonly object: T;
 
     /**
+     * Create a binder for a script game object.
+     *
      * @param object - Script game object controlled by this binder.
      */
     public constructor(object: T);
@@ -15731,22 +15874,27 @@ declare module "xray16" {
 
 declare module "xray16" {
   /**
-   * Client object binding for `CEntityAlive`.
+   * Runtime family wrapper for alive entities returned by `game_object.cast_EntityAlive()`.
    *
-   * @source C++ class CEntityAlive : public CEntity
+   * @source `src/xrGame/script_game_object_script3.cpp`, `cast_EntityAlive` binding.
    * @customConstructor CEntityAlive
    * @group xr_creature
    *
    * @remarks
-   * Base wrapper for alive objects. Use `game_object.is_entity_alive()` or a narrower predicate before calling
-   * alive-object methods from the shared `game_object` surface.
+   * This is a cast target, not a directly registered script constructor. Use `game_object.is_entity_alive()` or a
+   * narrower predicate before calling alive-object methods from the shared `game_object` surface.
    */
-  export class CEntityAlive extends CGameObject {}
+  export class CEntityAlive extends CGameObject {
+    /**
+     * Cast-only runtime wrapper.
+     */
+    protected constructor();
+  }
 
   /**
    * Client object binding for `CActor`.
    *
-   * @source C++ class CActor : CGameObject
+   * @source `src/xrGame/actor_script.cpp`, `CActor` binding.
    * @customConstructor CActor
    * @group xr_creature
    *
@@ -15756,22 +15904,27 @@ declare module "xray16" {
   export class CActor extends CGameObject {}
 
   /**
-   * Client object binding for `CCustomMonster`.
+   * Runtime family wrapper for custom monsters returned by `game_object.cast_Monster()`.
    *
-   * @source C++ class CCustomMonster : CGameObject
+   * @source `src/xrGame/script_game_object_script3.cpp`, `cast_Monster` binding.
    * @customConstructor CCustomMonster
    * @group xr_creature
    *
    * @remarks
-   * Base wrapper for custom monsters. Monster sound, range, memory, home, and enemy-transfer helpers require this
-   * family or one of its subclasses.
+   * This is a cast target for monster-specific helpers. Sound, range, memory, home, and enemy-transfer helpers require
+   * this family or one of its concrete runtime classes.
    */
-  export class CCustomMonster extends CGameObject {}
+  export class CCustomMonster extends CGameObject {
+    /**
+     * Cast-only runtime wrapper.
+     */
+    protected constructor();
+  }
 
   /**
-   * Client object binding for `CInventoryOwner`.
+   * Runtime family wrapper for inventory owners returned by `game_object.cast_InventoryOwner()`.
    *
-   * @source C++ class CInventoryOwner : CGameObject
+   * @source `src/xrGame/script_game_object_script3.cpp`, `cast_InventoryOwner` binding.
    * @customConstructor CInventoryOwner
    * @group xr_creature
    *
@@ -15779,12 +15932,17 @@ declare module "xray16" {
    * Inventory-owner APIs cover NPCs, traders, corpses, boxes, and the actor depending on runtime class. Check the
    * object kind before assuming dialog, trade, belt, or inventory-box behavior exists.
    */
-  export class CInventoryOwner extends CGameObject {}
+  export class CInventoryOwner extends CGameObject {
+    /**
+     * Cast-only runtime wrapper.
+     */
+    protected constructor();
+  }
 
   /**
-   * Client object binding for `CInventoryItem`.
+   * Runtime family wrapper for inventory items returned by `game_object.cast_InventoryItem()`.
    *
-   * @source C++ class CInventoryItem : CGameObject
+   * @source `src/xrGame/script_game_object_script3.cpp`, `cast_InventoryItem` binding.
    * @customConstructor CInventoryItem
    * @group xr_creature
    *
@@ -15792,12 +15950,17 @@ declare module "xray16" {
    * Base wrapper for inventory items. Item condition, cost, upgrades, and slot behavior depend on the concrete item
    * class.
    */
-  export class CInventoryItem extends CGameObject {}
+  export class CInventoryItem extends CGameObject {
+    /**
+     * Cast-only runtime wrapper.
+     */
+    protected constructor();
+  }
 
   /**
    * Client object binding for `CZombie`.
    *
-   * @source C++ class CZombie : CGameObject
+   * @source `src/xrGame/ai/monsters/zombie/zombie_script.cpp`, `CZombie` binding.
    * @customConstructor CZombie
    * @group xr_creature
    */
@@ -15806,7 +15969,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CController`.
    *
-   * @source C++ class CController : CGameObject
+   * @source `src/xrGame/ai/monsters/controller/controller_script.cpp`, `CController` binding.
    * @customConstructor CController
    * @group xr_creature
    */
@@ -15815,7 +15978,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CTushkano`.
    *
-   * @source C++ class CTushkano : CGameObject
+   * @source `src/xrGame/ai/monsters/tushkano/tushkano_script.cpp`, `CTushkano` binding.
    * @customConstructor CTushkano
    * @group xr_creature
    */
@@ -15824,7 +15987,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CBurer`.
    *
-   * @source C++ class CBurer : CGameObject
+   * @source `src/xrGame/ai/monsters/burer/burer_script.cpp`, `CBurer` binding.
    * @customConstructor CBurer
    * @group xr_creature
    */
@@ -15833,7 +15996,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CCat`.
    *
-   * @source C++ class CCat : CGameObject
+   * @source `src/xrGame/ai/monsters/cat/cat_script.cpp`, `CCat` binding.
    * @customConstructor CCat
    * @group xr_creature
    */
@@ -15842,7 +16005,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CChimera`.
    *
-   * @source C++ class CChimera : CGameObject
+   * @source `src/xrGame/ai/monsters/chimera/chimera_script.cpp`, `CChimera` binding.
    * @customConstructor CChimera
    * @group xr_creature
    */
@@ -15851,7 +16014,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CPoltergeist`.
    *
-   * @source C++ class CPoltergeist : CGameObject
+   * @source `src/xrGame/ai/monsters/poltergeist/poltergeist_script.cpp`, `CPoltergeist` binding.
    * @customConstructor CPoltergeist
    * @group xr_creature
    */
@@ -15860,7 +16023,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CPseudoGigant`.
    *
-   * @source C++ class CPseudoGigant : CGameObject
+   * @source `src/xrGame/ai/monsters/pseudogigant/pseudogigant_script.cpp`, `CPseudoGigant` binding.
    * @customConstructor CPseudoGigant
    * @group xr_creature
    */
@@ -15869,7 +16032,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CPsyDog`.
    *
-   * @source C++ class CPsyDog : CGameObject
+   * @source `src/xrGame/ai/monsters/pseudodog/pseudodog_script.cpp`, `CPsyDog` binding.
    * @customConstructor CPsyDog
    * @group xr_creature
    */
@@ -15878,7 +16041,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CPsyDogPhantom`.
    *
-   * @source C++ class CPsyDogPhantom : CGameObject
+   * @source `src/xrGame/ai/monsters/pseudodog/pseudodog_script.cpp`, `CPsyDogPhantom` binding.
    * @customConstructor CPsyDogPhantom
    * @group xr_creature
    */
@@ -15887,12 +16050,13 @@ declare module "xray16" {
   /**
    * Client object binding for `CAI_Bloodsucker`.
    *
-   * @source C++ class CAI_Bloodsucker : CGameObject
+   * @source `src/xrGame/ai/monsters/bloodsucker/bloodsucker_script.cpp`, `CAI_Bloodsucker` binding.
    * @customConstructor CAI_Bloodsucker
    * @group xr_creature
    *
    * @remarks
-   * Bloodsucker-specific visibility helpers are not valid for other custom monsters.
+   * Bloodsucker-specific visibility helpers are not valid for other custom monsters. The shared `game_object` wrapper
+   * also exposes this helper and logs a script error when the object is not this runtime class.
    */
   export class CAI_Bloodsucker extends CGameObject {
     /**
@@ -15906,7 +16070,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CAI_Boar`.
    *
-   * @source C++ class CAI_Boar : CGameObject
+   * @source `src/xrGame/ai/monsters/boar/boar_script.cpp`, `CAI_Boar` binding.
    * @customConstructor CAI_Boar
    * @group xr_creature
    */
@@ -15915,7 +16079,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CAI_Dog`.
    *
-   * @source C++ class CAI_Dog : CGameObject
+   * @source `src/xrGame/ai/monsters/dog/dog_script.cpp`, `CAI_Dog` binding.
    * @customConstructor CAI_Dog
    * @group xr_creature
    */
@@ -15924,7 +16088,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CAI_Flesh`.
    *
-   * @source C++ class CAI_Flesh : CGameObject
+   * @source `src/xrGame/ai/monsters/flesh/flesh_script.cpp`, `CAI_Flesh` binding.
    * @customConstructor CAI_Flesh
    * @group xr_creature
    */
@@ -15933,7 +16097,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CAI_PseudoDog`.
    *
-   * @source C++ class CAI_PseudoDog : CGameObject
+   * @source `src/xrGame/ai/monsters/pseudodog/pseudodog_script.cpp`, `CAI_PseudoDog` binding.
    * @customConstructor CAI_PseudoDog
    * @group xr_creature
    */
@@ -15942,7 +16106,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CAI_Stalker`.
    *
-   * @source C++ class CAI_Stalker : CGameObject
+   * @source `src/xrGame/ai/stalker/ai_stalker_script.cpp`, `CAI_Stalker` binding.
    * @customConstructor CAI_Stalker
    * @group xr_creature
    *
@@ -15954,7 +16118,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CAI_Trader`.
    *
-   * @source C++ class CAI_Trader : CGameObject
+   * @source `src/xrGame/ai/trader/ai_trader_script.cpp`, `CAI_Trader` binding.
    * @customConstructor CAI_Trader
    * @group xr_creature
    *
@@ -15966,7 +16130,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CSnork`.
    *
-   * @source C++ class CSnork : CGameObject
+   * @source `src/xrGame/ai/monsters/snork/snork_script.cpp`, `CSnork` binding.
    * @customConstructor CSnork
    * @group xr_creature
    */
@@ -15977,7 +16141,7 @@ declare module "xray16" {
   /**
    * Explosive component shared by grenade and explosive item classes.
    *
-   * @source C++ class explosive
+   * @source `src/xrGame/WeaponScript.cpp`, `explosive` binding.
    * @customConstructor explosive
    * @group xr_item
    *
@@ -16002,104 +16166,126 @@ declare module "xray16" {
   /**
    * Client object binding for `CAntirad` inventory items.
    *
-   * @source C++ class CAntirad : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CAntirad` binding.
    * @customConstructor CAntirad
    * @group xr_item
+   *
+   * @remarks
+   * Antirad objects are registered as plain `CGameObject` wrappers. Use shared inventory item/game object APIs for
+   * ownership, condition, and activation checks.
    */
   export class CAntirad extends CGameObject {}
 
   /**
    * Client object binding for `CStalkerOutfit` inventory items.
    *
-   * @source C++ class CStalkerOutfit : CGameObject
+   * @source `src/xrGame/StalkerOutfit.cpp`, `CStalkerOutfit` binding.
    * @customConstructor CStalkerOutfit
    * @group xr_item
+   *
+   * @remarks
+   * Stalker outfit objects are registered separately from generic custom outfits. Script-visible behavior is exposed
+   * through the shared game-object and inventory-item helpers.
    */
   export class CStalkerOutfit extends CGameObject {}
 
   /**
    * Client object binding for `CInventoryBox` inventory items.
    *
-   * @source C++ class CInventoryBox : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CInventoryBox` binding.
    * @customConstructor CInventoryBox
    * @group xr_item
    *
    * @remarks
-   * Inventory box helpers on `game_object` require this runtime class, not any inventory owner.
+   * Inventory box helpers on `game_object` require this runtime class, not any inventory owner. The object itself is
+   * still exposed as a client `CGameObject` wrapper.
    */
   export class CInventoryBox extends CGameObject {}
 
   /**
    * Client object binding for `CBottleItem` inventory items.
    *
-   * @source C++ class CBottleItem : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CBottleItem` binding.
    * @customConstructor CBottleItem
    * @group xr_item
+   *
+   * @remarks
+   * Bottle items are consumable inventory objects with no direct script-only methods in this binding.
    */
   export class CBottleItem extends CGameObject {}
 
   /**
    * Client object binding for `CFoodItem` inventory items.
    *
-   * @source C++ class CFoodItem : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CFoodItem` binding.
    * @customConstructor CFoodItem
    * @group xr_item
+   *
+   * @remarks
+   * Food items are consumable inventory objects with no direct script-only methods in this binding.
    */
   export class CFoodItem extends CGameObject {}
 
   /**
    * Client object binding for `CMedkit` inventory items.
    *
-   * @source C++ class CMedkit : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CMedkit` binding.
    * @customConstructor CMedkit
    * @group xr_item
+   *
+   * @remarks
+   * Medkit items are consumable inventory objects with no direct script-only methods in this binding.
    */
   export class CMedkit extends CGameObject {}
 
   /**
-   * Client object binding for `CExplosiveItem` inventory items.
+   * Client object binding for explosive inventory items.
    *
-   * @source C++ class CExplosiveItem : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CExplosiveItem` binding.
    * @customConstructor CExplosiveItem
    * @group xr_item
-   */
-  export class CExplosiveItem extends CGameObject {}
-
-  /**
-   * Client object binding for `CCWeaponAK74` inventory items.
    *
-   * @source C++ class CWeaponAK74 : CGameObject
-   * @customConstructor CWeaponAK74
-   * @group xr_item
+   * @remarks
+   * The script binding exposes both `CGameObject` and `explosive` bases for this class.
    */
-  export class CCWeaponAK74 extends CGameObject {}
+  export class CExplosiveItem extends CGameObject {
+    /**
+     * Trigger the item's explosive component immediately.
+     */
+    public explode(): void;
+  }
 
   /**
    * Client object binding for `CGrenadeLauncher` inventory items.
    *
-   * @source C++ class CGrenadeLauncher : CGameObject
+   * @source `src/xrGame/Scope.cpp`, `CGrenadeLauncher` binding.
    * @customConstructor CGrenadeLauncher
    * @group xr_item
+   *
+   * @remarks
+   * Weapon addon wrapper registered together with scopes and silencers. It is an inventory object, not a weapon
+   * subclass, so weapon-only methods are not available on this type.
    */
   export class CGrenadeLauncher extends CGameObject {}
 
   /**
    * Client object binding for `CWeaponAmmo` inventory items.
    *
-   * @source C++ class CWeaponAmmo : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponAmmo` binding.
    * @customConstructor CWeaponAmmo
    * @group xr_item
    *
    * @remarks
-   * Ammo-count helpers on `game_object` require this runtime class.
+   * Ammo-count helpers on `game_object` require this runtime class. The Lua class itself exposes only the common
+   * game-object surface.
    */
   export class CWeaponAmmo extends CGameObject {}
 
   /**
    * Client object binding for `CWeapon` inventory items.
    *
-   * @source C++ class CWeapon : public CHudItemObject, public CShootingObject
-   * @customConstructor CWeaponAmmo
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeapon` binding.
+   * @customConstructor CWeapon
    * @group xr_item
    *
    * @remarks
@@ -16111,7 +16297,8 @@ declare module "xray16" {
      * Check whether the weapon can currently fire a lethal shot.
      *
      * @remarks
-     * Takes current weapon state into account, including ammo and readiness.
+     * Returns true when the weapon has suitable ammo available or does not use ammo. This is the same predicate used by
+     * actor and stalker weapon selection before considering an item lethal.
      *
      * @returns Whether the weapon can kill.
      */
@@ -16119,18 +16306,40 @@ declare module "xray16" {
   }
 
   /**
-   * Client object binding for `CWeaponMagazined` inventory items.
+   * Client object binding for magazine-fed weapons.
    *
-   * @source C++ class CWeaponMagazined : public CWeapon
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponMagazined` binding.
    * @customConstructor CWeaponMagazined
    * @group xr_item
+   *
+   * @remarks
+   * Base class for most firearms exposed to scripts. The binding inherits `CWeapon`, so `can_kill()` is available on
+   * all subclasses declared under this family.
    */
   export class CWeaponMagazined extends CWeapon {}
 
+  /**
+   * Client object binding for magazine-fed weapons with grenade-launcher support.
+   *
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponMagazinedWGrenade` binding.
+   * @customConstructor CWeaponMagazinedWGrenade
+   * @group xr_item
+   */
+  export class CWeaponMagazinedWGrenade extends CWeaponMagazined {}
+
+  /**
+   * Client object binding for `CWeaponAK74` inventory items.
+   *
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponAK74` binding.
+   * @customConstructor CWeaponAK74
+   * @group xr_item
+   */
+  export class CWeaponAK74 extends CWeaponMagazinedWGrenade {}
+
   /**
    * Client object binding for `CWeaponAutomaticShotgun` inventory items.
    *
-   * @source C++ class CWeaponAutomaticShotgun : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponAutomaticShotgun` binding.
    * @customConstructor CWeaponAutomaticShotgun
    * @group xr_item
    */
@@ -16139,7 +16348,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CWeaponBM16` inventory items.
    *
-   * @source C++ class CWeaponBM16 : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponBM16` binding.
    * @customConstructor CWeaponBM16
    * @group xr_item
    */
@@ -16148,160 +16357,160 @@ declare module "xray16" {
   /**
    * Client object binding for `CWeaponBinoculars` inventory items.
    *
-   * @source C++ class CWeaponBinoculars : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponBinoculars` binding.
    * @customConstructor CWeaponBinoculars
    * @group xr_item
    */
-  export class CWeaponBinoculars extends CGameObject {}
+  export class CWeaponBinoculars extends CWeaponMagazined {}
 
   /**
    * Client object binding for `CWeaponFN2000` inventory items.
    *
-   * @source C++ class CWeaponFN2000 : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponFN2000` binding.
    * @customConstructor CWeaponFN2000
    * @group xr_item
    */
-  export class CWeaponFN2000 extends CGameObject {}
+  export class CWeaponFN2000 extends CWeaponMagazined {}
 
   /**
    * Client object binding for `CWeaponFORT` inventory items.
    *
-   * @source C++ class CWeaponFORT : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponFORT` binding.
    * @customConstructor CWeaponFORT
    * @group xr_item
    */
-  export class CWeaponFORT extends CGameObject {}
+  export class CWeaponFORT extends CWeaponMagazined {}
 
   /**
    * Client object binding for `CWeaponGroza` inventory items.
    *
-   * @source C++ class CWeaponGroza : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponGroza` binding.
    * @customConstructor CWeaponGroza
    * @group xr_item
    */
-  export class CWeaponGroza extends CGameObject {}
+  export class CWeaponGroza extends CWeaponMagazinedWGrenade {}
 
   /**
    * Client object binding for `CWeaponHPSA` inventory items.
    *
-   * @source C++ class CWeaponHPSA : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponHPSA` binding.
    * @customConstructor CWeaponHPSA
    * @group xr_item
    */
-  export class CWeaponHPSA extends CGameObject {}
+  export class CWeaponHPSA extends CWeaponMagazined {}
 
   /**
    * Client object binding for `CWeaponKnife` inventory items.
    *
-   * @source C++ class CWeaponKnife : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponKnife` binding.
    * @customConstructor CWeaponKnife
    * @group xr_item
    */
-  export class CWeaponKnife extends CGameObject {}
+  export class CWeaponKnife extends CWeapon {}
 
   /**
    * Client object binding for `CWeaponLR300` inventory items.
    *
-   * @source C++ class CWeaponLR300 : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponLR300` binding.
    * @customConstructor CWeaponLR300
    * @group xr_item
    */
-  export class CWeaponLR300 extends CGameObject {}
+  export class CWeaponLR300 extends CWeaponMagazined {}
 
   /**
    * Client object binding for `CWeaponPM` inventory items.
    *
-   * @source C++ class CWeaponPM : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponPM` binding.
    * @customConstructor CWeaponPM
    * @group xr_item
    */
-  export class CWeaponPM extends CGameObject {}
+  export class CWeaponPM extends CWeaponMagazined {}
 
   /**
    * Client object binding for `CWeaponRG6` inventory items.
    *
-   * @source C++ class CWeaponRG6 : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponRG6` binding.
    * @customConstructor CWeaponRG6
    * @group xr_item
    */
-  export class CWeaponRG6 extends CGameObject {}
+  export class CWeaponRG6 extends CWeaponShotgun {}
 
   /**
    * Client object binding for `CWeaponRPG7` inventory items.
    *
-   * @source C++ class CWeaponRPG7 : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponRPG7` binding.
    * @customConstructor CWeaponRPG7
    * @group xr_item
    */
-  export class CWeaponRPG7 extends CGameObject {}
+  export class CWeaponRPG7 extends CWeaponMagazined {}
 
   /**
    * Client object binding for `CWeaponSVD` inventory items.
    *
-   * @source C++ class CWeaponSVD : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponSVD` binding.
    * @customConstructor CWeaponSVD
    * @group xr_item
    */
-  export class CWeaponSVD extends CGameObject {}
+  export class CWeaponSVD extends CWeaponMagazined {}
 
   /**
    * Client object binding for `CWeaponSVU` inventory items.
    *
-   * @source C++ class CWeaponSVU : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponSVU` binding.
    * @customConstructor CWeaponSVU
    * @group xr_item
    */
-  export class CWeaponSVU extends CGameObject {}
+  export class CWeaponSVU extends CWeaponMagazined {}
 
   /**
    * Client object binding for `CWeaponShotgun` inventory items.
    *
-   * @source C++ class CWeaponShotgun : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponShotgun` binding.
    * @customConstructor CWeaponShotgun
    * @group xr_item
    */
-  export class CWeaponShotgun extends CGameObject {}
+  export class CWeaponShotgun extends CWeaponMagazined {}
 
   /**
    * Client object binding for `CWeaponUSP45` inventory items.
    *
-   * @source C++ class CWeaponUSP45 : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponUSP45` binding.
    * @customConstructor CWeaponUSP45
    * @group xr_item
    */
-  export class CWeaponUSP45 extends CGameObject {}
+  export class CWeaponUSP45 extends CWeaponMagazined {}
 
   /**
    * Client object binding for `CWeaponVal` inventory items.
    *
-   * @source C++ class CWeaponVal : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponVal` binding.
    * @customConstructor CWeaponVal
    * @group xr_item
    */
-  export class CWeaponVal extends CGameObject {}
+  export class CWeaponVal extends CWeaponMagazined {}
 
   /**
    * Client object binding for `CWeaponVintorez` inventory items.
    *
-   * @source C++ class CWeaponVintorez : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponVintorez` binding.
    * @customConstructor CWeaponVintorez
    * @group xr_item
    */
-  export class CWeaponVintorez extends CGameObject {}
+  export class CWeaponVintorez extends CWeaponMagazined {}
 
   /**
    * Client object binding for `CWeaponWalther` inventory items.
    *
-   * @source C++ class CWeaponWalther : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CWeaponWalther` binding.
    * @customConstructor CWeaponWalther
    * @group xr_item
    */
-  export class CWeaponWalther extends CGameObject {}
+  export class CWeaponWalther extends CWeaponMagazined {}
 
   /**
    * Client object binding for `CSilencer` inventory items.
    *
-   * @source C++ class CSilencer : CGameObject
+   * @source `src/xrGame/Scope.cpp`, `CSilencer` binding.
    * @customConstructor CSilencer
    * @group xr_item
    */
@@ -16310,50 +16519,122 @@ declare module "xray16" {
   /**
    * Client object binding for `CScope` inventory items.
    *
-   * @source C++ class CScope : CGameObject
+   * @source `src/xrGame/Scope.cpp`, `CScope` binding.
    * @customConstructor CScope
    * @group xr_item
    */
   export class CScope extends CGameObject {}
 
   /**
-   * Client object binding for `CRGD5` inventory items.
+   * Client object binding for `CRGD5` grenade items.
    *
-   * @source C++ class CRGD5 : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CRGD5` binding.
    * @customConstructor CRGD5
    * @group xr_item
+   *
+   * @remarks
+   * The script binding exposes both `CGameObject` and `explosive` bases for this class.
    */
-  export class CRGD5 extends CGameObject {}
+  export class CRGD5 extends CGameObject {
+    /**
+     * Trigger the grenade's explosive component immediately.
+     */
+    public explode(): void;
+  }
 
   /**
-   * Client object binding for `CF1` inventory items.
+   * Client object binding for `CF1` grenade items.
    *
-   * @source C++ class CF1 : CGameObject
+   * @source `src/xrGame/WeaponScript.cpp`, `CF1` binding.
    * @customConstructor CF1
    * @group xr_item
+   *
+   * @remarks
+   * The script binding exposes both `CGameObject` and `explosive` bases for this class.
    */
-  export class CF1 extends CGameObject {}
+  export class CF1 extends CGameObject {
+    /**
+     * Trigger the grenade's explosive component immediately.
+     */
+    public explode(): void;
+  }
 
   /**
    * Client object binding for `CPda` inventory items.
    *
-   * @source C++ class CPda : CGameObject
+   * @source `src/xrGame/torch_script.cpp`, `CPda` binding.
    * @customConstructor CPda
    * @group xr_item
+   *
+   * @remarks
+   * PDA objects are inventory items exposed through the torch binding file. Runtime PDA ownership and contact logic are
+   * handled by native inventory-owner code, not by script-visible PDA methods.
    */
   export class CPda extends CGameObject {}
+
+  /**
+   * Client object binding for simple artefact detectors.
+   *
+   * @source `src/xrGame/torch_script.cpp`, `CSimpleDetector` binding.
+   * @customConstructor CSimpleDetector
+   * @group xr_item
+   *
+   * @remarks
+   * The native detector rank is 1. The binding exposes the object as a `CGameObject`; detector UI and artefact search
+   * logic are handled internally by the engine.
+   */
+  export class CSimpleDetector extends CGameObject {}
+
+  /**
+   * Client object binding for advanced artefact detectors.
+   *
+   * @source `src/xrGame/torch_script.cpp`, `CAdvancedDetector` binding.
+   * @customConstructor CAdvancedDetector
+   * @group xr_item
+   *
+   * @remarks
+   * The native detector rank is 2. It is registered as a concrete `CGameObject` wrapper without extra script-visible
+   * methods.
+   */
+  export class CAdvancedDetector extends CGameObject {}
+
+  /**
+   * Client object binding for elite artefact detectors.
+   *
+   * @source `src/xrGame/torch_script.cpp`, `CEliteDetector` binding.
+   * @customConstructor CEliteDetector
+   * @group xr_item
+   *
+   * @remarks
+   * The native detector rank is 3. Use generic inventory-item and game-object APIs for script interaction.
+   */
+  export class CEliteDetector extends CGameObject {}
+
+  /**
+   * Client object binding for scientific artefact detectors.
+   *
+   * @source `src/xrGame/torch_script.cpp`, `CScientificDetector` binding.
+   * @customConstructor CScientificDetector
+   * @group xr_item
+   *
+   * @remarks
+   * Scientific detectors use the elite-detector rank and add native anomaly-zone scanning, but the Lua binding exposes
+   * no detector-specific methods beyond the game-object surface.
+   */
+  export class CScientificDetector extends CGameObject {}
 }
 
 declare module "xray16" {
   /**
    * Campfire anomaly object.
    *
-   * @source C++ class CZoneCampfire : CGameObject
+   * @source `src/xrGame/MosquitoBald_script.cpp`, `CZoneCampfire` binding.
    * @customConstructor CZoneCampfire
    * @group xr_level
    *
    * @remarks
-   * Campfire controls require this runtime object. They are not available on generic anomaly zones.
+   * Campfire controls require this runtime object. The binding is registered next to mosquito-bald anomalies and
+   * exposes only on/off state controls; generic anomaly zones do not have these methods.
    */
   export class CZoneCampfire extends CGameObject {
     /**
@@ -16367,12 +16648,12 @@ declare module "xray16" {
     public is_on(): boolean;
 
     /**
-     * Turn the campfire on.
+     * Switch the campfire into its enabled state and start native idle effects.
      */
     public turn_on(): void;
 
     /**
-     * Turn the campfire off.
+     * Switch the campfire into its disabled state and stop native idle effects.
      */
     public turn_off(): void;
   }
@@ -16380,13 +16661,13 @@ declare module "xray16" {
   /**
    * Animated client physics object.
    *
-   * @source C++ class CPhysicObject : CGameObject
+   * @source `src/xrGame/PhysicObject_script.cpp`, `CPhysicObject` binding.
    * @customConstructor CPhysicObject
    * @group xr_level
    *
    * @remarks
-   * Wrapper for animated physics props, especially door-like objects. Door and bone-sound helpers require this runtime
-   * class.
+   * Wrapper for animated physics props, especially door-like objects. The exposed methods control native object
+   * animation time, bone-attached sounds, and temporary dynamic-collision ignoring.
    */
   export class CPhysicObject extends CGameObject {
     /**
@@ -16439,15 +16720,29 @@ declare module "xray16" {
     public stop_bones_sound(): void;
   }
 
+  /**
+   * Destroyable animated physics object.
+   *
+   * @source `src/xrGame/PhysicObject_script.cpp`, `CDestroyablePhysicsObject` binding.
+   * @customConstructor CDestroyablePhysicsObject
+   * @group xr_level
+   *
+   * @remarks
+   * Registered as a `CPhysicObject` subclass. It inherits the animated physics helpers and participates in destroyable
+   * object callbacks through the engine object lifecycle.
+   */
+  export class CDestroyablePhysicsObject extends CPhysicObject {}
+
   /**
    * Hanging lamp object controlled from scripts.
    *
-   * @source C++ class hanging_lamp : CGameObject
+   * @source `src/xrGame/HangingLamp.cpp`, `hanging_lamp` binding.
    * @customConstructor hanging_lamp
    * @group xr_level
    *
    * @remarks
-   * Lamp controls require this runtime object. They do not apply to arbitrary lights or torches.
+   * Lamp controls require this runtime object. `turn_on()` activates render lights, glow/ambient light, visible light
+   * bones, and processing; `turn_off()` disables those native lamp effects.
    */
   export class hanging_lamp extends CGameObject {
     /**
@@ -16469,7 +16764,7 @@ declare module "xray16" {
   /**
    * Driveable car and mounted weapon holder.
    *
-   * @source C++ class CCar : CGameObject, holder
+   * @source `src/xrGame/CarScript.cpp`, `CCar` binding.
    * @customConstructor CCar
    * @group xr_level
    *
@@ -16481,27 +16776,27 @@ declare module "xray16" {
     /**
      * Engine enum value for `CCar.eWpnActivate`.
      */
-    public static eWpnActivate: 3;
+    public static readonly eWpnActivate: 3;
     /**
      * Engine enum value for `CCar.eWpnAutoFire`.
      */
-    public static eWpnAutoFire: 5;
+    public static readonly eWpnAutoFire: 5;
     /**
      * Engine enum value for `CCar.eWpnDesiredDir`.
      */
-    public static eWpnDesiredDir: 1;
+    public static readonly eWpnDesiredDir: 1;
     /**
      * Engine enum value for `CCar.eWpnDesiredPos`.
      */
-    public static eWpnDesiredPos: 2;
+    public static readonly eWpnDesiredPos: 2;
     /**
      * Engine enum value for `CCar.eWpnFire`.
      */
-    public static eWpnFire: 4;
+    public static readonly eWpnFire: 4;
     /**
      * Engine enum value for `CCar.eWpnToDefaultDir`.
      */
-    public static eWpnToDefaultDir: 6;
+    public static readonly eWpnToDefaultDir: 6;
 
     /**
      * Create a car object wrapper.
@@ -16533,14 +16828,22 @@ declare module "xray16" {
     public CarExplode(): void;
 
     /**
-     * Change fuel by a delta.
+     * Change current fuel by a delta and clamp it to the tank range.
+     *
+     * @remarks
+     * Negative deltas cannot reduce fuel below `0`; positive deltas cannot increase it above `GetfFuelTank()`.
+     * Use `SetfFuel()` or `set_fuel()` when the script needs to assign an absolute fuel value.
      *
      * @param fuel - Fuel delta.
      */
     public ChangefFuel(fuel: f32): void;
 
     /**
-     * Change vehicle health by a delta.
+     * Change vehicle health by a delta and clamp it to the normalized health range.
+     *
+     * @remarks
+     * The native implementation clamps the result to `0..1`. Use `SetfHealth()` when assigning an absolute health
+     * value.
      *
      * @param value - Health delta.
      */
@@ -16552,7 +16855,7 @@ declare module "xray16" {
     public CurrentVel(): vector;
 
     /**
-     * @returns Scheduled explosion time.
+     * @returns Scheduled delayed-fuse explosion time in milliseconds, or `0` when no fuse was initialized.
      */
     public ExplodeTime(): u32;
 
@@ -16615,21 +16918,30 @@ declare module "xray16" {
     public PlayDamageParticles(): void;
 
     /**
-     * Set scheduled explosion time.
+     * Set delayed-fuse explosion time.
      *
-     * @param time - Explosion time.
+     * @remarks
+     * The native method accepts milliseconds and converts them to the delayed action fuse timeout.
+     *
+     * @param time - Explosion time in milliseconds.
      */
     public SetExplodeTime(time: u32): void;
 
     /**
-     * Set current fuel amount.
+     * Set current fuel amount directly.
+     *
+     * @remarks
+     * This is an absolute setter and does not clamp against tank capacity.
      *
      * @param fuel - Fuel amount.
      */
     public SetfFuel(fuel: f32): void;
 
     /**
-     * Set current fuel amount.
+     * Set current fuel amount directly.
+     *
+     * @remarks
+     * Lowercase alias for `SetfFuel()`.
      *
      * @param fuel - Fuel amount.
      */
@@ -16664,11 +16976,16 @@ declare module "xray16" {
     public set_fuel_tank(fuel: f32): void;
 
     /**
-     * Set vehicle health.
+     * Set vehicle health directly.
+     *
+     * @remarks
+     * This forwards to the entity health setter and returns the applied value. `ChangefHealth()` is the clamped delta
+     * helper.
      *
      * @param health - New health value.
+     * @returns Applied health value.
      */
-    public SetfHealth(health: f32): void;
+    public SetfHealth(health: f32): f32;
 
     /**
      * @returns Whether vehicle engine is active at the moment.
@@ -16718,15 +17035,23 @@ declare module "xray16" {
     public engaged(): boolean;
 
     /**
-     * Send a holder or weapon action.
+     * Send a mounted-weapon action.
      *
-     * @param id - Action id.
+     * @remarks
+     * For `eWpnFire`, `eWpnActivate`, and `eWpnAutoFire`, native code treats `flags === 1` as enabled/start and any
+     * other value as disabled/stop. `eWpnToDefaultDir` resets the weapon direction to its bind orientation.
+     *
+     * @param id - Weapon action id.
      * @param flags - Action flags.
      */
     public Action(id: u16, flags: u32): void;
 
     /**
-     * Set a mounted weapon vector parameter.
+     * Set a mounted-weapon vector parameter.
+     *
+     * @remarks
+     * The script binding exposes the vector overload. Native code handles `eWpnDesiredPos` by aiming the weapon at the
+     * provided world position; other ids are ignored by this overload.
      *
      * @param id - Weapon parameter id.
      * @param vector - Parameter value.
@@ -16734,16 +17059,23 @@ declare module "xray16" {
     public SetParam(id: i32, vector: vector): void;
 
     /**
-     * Set a mounted weapon vector parameter.
+     * Set mounted weapon desired target position.
      *
-     * @param id - Weapon parameter id.
-     * @param vector - Parameter value.
+     * @param id - `CCar.eWpnDesiredPos`.
+     * @param vector - Target world position.
      */
-    public SetParam(id: TXR_CCar_weapon_param, vector: vector): void;
+    public SetParam(id: typeof CCar.eWpnDesiredPos, vector: vector): void;
   }
 
   /**
+   * Mounted-weapon action and parameter ids exported on `CCar`.
+   *
+   * @source `src/xrGame/CarScript.cpp`, `CCar.wpn_action` enum.
    * @group xr_level
+   *
+   * @remarks
+   * `eWpnFire`, `eWpnActivate`, `eWpnAutoFire`, and `eWpnToDefaultDir` are action ids for `CCar.Action()`.
+   * `eWpnDesiredPos` is handled by the script-visible `CCar.SetParam()` vector overload.
    */
   export type TXR_CCar_weapon_param = EnumeratedStaticsValues<typeof CCar>;
 
@@ -16784,14 +17116,12 @@ declare module "xray16" {
    * @group xr_level
    */
   export type TXR_helicopter_hunt_state =
-    | typeof CHelicopter.eEnemyNone
-    | typeof CHelicopter.eEnemyPoint
-    | typeof CHelicopter.eEnemyEntity;
+    typeof CHelicopter.eEnemyNone | typeof CHelicopter.eEnemyPoint | typeof CHelicopter.eEnemyEntity;
 
   /**
    * Script-controlled helicopter object.
    *
-   * @source C++ class CHelicopter : CGameObject
+   * @source `src/xrGame/helicopter_script.cpp`, `CHelicopter` binding.
    * @customConstructor CHelicopter
    * @group xr_level
    *
@@ -16944,8 +17274,12 @@ declare module "xray16" {
     /**
      * Get desired speed near the destination point.
      *
-     * @param value - Distance threshold.
-     * @returns Speed at that destination distance.
+     * @remarks
+     * The native binding requires one numeric argument, but the implementation ignores it and returns the configured
+     * destination speed.
+     *
+     * @param value - Ignored by native code.
+     * @returns Speed used near the destination point.
      */
     public GetSpeedInDestPoint(value: f32): f32;
 
@@ -16997,15 +17331,18 @@ declare module "xray16" {
     /**
      * Set desired speed near the destination point.
      *
+     * @remarks
+     * Used by the movement manager while approaching the current destination or patrol point.
+     *
      * @param value - Speed value.
      */
     public SetSpeedInDestPoint(value: f32): void;
 
     /**
-     * Set linear acceleration limits.
+     * Set forward and braking linear acceleration values.
      *
-     * @param min - Minimum acceleration.
-     * @param max - Maximum acceleration.
+     * @param min - Forward acceleration.
+     * @param max - Braking acceleration.
      */
     public SetLinearAcc(min: f32, max: f32): void;
 
@@ -17025,15 +17362,21 @@ declare module "xray16" {
     public SetMaxVelocity(value: f32): void;
 
     /**
-     * Track an enemy object.
+     * Track an enemy object by its engine id.
+     *
+     * @remarks
+     * Passing nullish values is not safe for the native object overload. Use `ClearEnemy()` to clear the current enemy.
      *
-     * @param game_object - Enemy object, or null to clear.
+     * @param game_object - Enemy object to track.
      */
-    public SetEnemy(game_object: Nillable<game_object>): void;
+    public SetEnemy(game_object: game_object): void;
 
     /**
      * Track an enemy point.
      *
+     * @remarks
+     * Sets the hunt state to `CHelicopter.eEnemyPoint` and stores the provided world position.
+     *
      * @param position - Enemy world position.
      */
     public SetEnemy(position: vector): void;
@@ -17053,7 +17396,7 @@ declare module "xray16" {
     public SetBarrelDirTolerance(value: f32): void;
 
     /**
-     * Set movement destination.
+     * Set movement destination and switch movement state to `CHelicopter.eMovToPoint`.
      *
      * @param position - Destination world position.
      */
@@ -17067,18 +17410,22 @@ declare module "xray16" {
     public SetOnPointRangeDist(distance: f32): void;
 
     /**
-     * Aim the helicopter body at a point.
+     * Aim the helicopter body at a point or return aiming to path direction.
      *
-     * @param position - Point to look at.
-     * @param is_smooth - Whether to rotate smoothly.
+     * @remarks
+     * Native code treats the boolean as an enable flag: `true` switches body state to `eBodyToPoint`, while `false`
+     * switches it back to `eBodyByPath`.
+     *
+     * @param position - Point to look at when enabled.
+     * @param is_smooth - Whether point aiming is enabled.
      */
     public LookAtPoint(position: vector, is_smooth: boolean): void;
 
     /**
-     * Move by a patrol path.
+     * Move by a named patrol path and switch movement state to `CHelicopter.eMovPatrolPath`.
      *
      * @param path_name - Patrol path name.
-     * @param start_point - Starting point index.
+     * @param start_point - Starting patrol vertex id.
      */
     public GoPatrolByPatrolPath(path_name: string, start_point: i32): void;
 
@@ -17100,14 +17447,17 @@ declare module "xray16" {
     public UseFireTrail(): boolean;
 
     /**
-     * Enable or disable fire trail rendering.
+     * Enable or disable fire trail rendering and update fire dispersion settings.
      *
      * @param is_enabled - New fire trail state.
      */
     public UseFireTrail(is_enabled: boolean): void;
 
     /**
-     * Move around a point by a round patrol path.
+     * Move around a point by a generated round patrol path and switch movement state to `CHelicopter.eMovRoundPath`.
+     *
+     * @remarks
+     * Native code refuses radii smaller than the current speed and angular-speed constraints allow.
      *
      * @param center - Round path center.
      * @param radius - Path radius.
@@ -17116,12 +17466,15 @@ declare module "xray16" {
     public GoPatrolByRoundPath(center: vector, radius: f32, clockwise: boolean): void;
 
     /**
-     * Kill the helicopter without running a full explosion command.
+     * Switch the helicopter to dead state and enable its falling physics.
+     *
+     * @remarks
+     * This stops the engine sound and starts the broken-loop sound, but it is separate from `Explode()`.
      */
     public Die(): void;
 
     /**
-     * Start flame effects.
+     * Start smoke/flame particle effects if they are not already active.
      */
     public StartFlame(): void;
 
@@ -17133,7 +17486,7 @@ declare module "xray16" {
     public TurnEngineSound(enabled: boolean): void;
 
     /**
-     * Clear current enemy target.
+     * Clear current enemy target and switch hunt state to `CHelicopter.eEnemyNone`.
      */
     public ClearEnemy(): void;
   }
@@ -17143,7 +17496,7 @@ declare module "xray16" {
   /**
    * One rigid body element inside a physics shell.
    *
-   * @source C++ class physics_element
+   * @source `src/xrPhysics/PhysicsShellScript.cpp`, `physics_element` binding.
    * @customConstructor physics_element
    * @group xr_physic
    *
@@ -17152,6 +17505,11 @@ declare module "xray16" {
    * them only while the owning shell and object are alive.
    */
   export class physics_element {
+    /**
+     * Engine-owned physics element.
+     */
+    private constructor();
+
     /**
      * Apply force to the element.
      *
@@ -17225,7 +17583,7 @@ declare module "xray16" {
   /**
    * Script-controlled particle system.
    *
-   * @source C++ class particles_object
+   * @source `src/xrGame/script_particles_script.cpp`, `particles_object` binding.
    * @customConstructor particles_object
    * @group xr_physic
    *
@@ -17355,7 +17713,7 @@ declare module "xray16" {
   /**
    * Joint connecting two physics elements.
    *
-   * @source C++ class physics_joint
+   * @source `src/xrPhysics/PhysicsShellScript.cpp`, `physics_joint` binding.
    * @customConstructor physics_joint
    * @group xr_physic
    *
@@ -17364,6 +17722,11 @@ declare module "xray16" {
    * `get_axes_number()` before using indexed axis methods. Keep them only while the owning shell and object are alive.
    */
   export class physics_joint {
+    /**
+     * Engine-owned physics joint.
+     */
+    private constructor();
+
     /**
      * Write the joint anchor into a vector.
      *
@@ -17528,7 +17891,7 @@ declare module "xray16" {
   /**
    * Physics shell made of elements and joints.
    *
-   * @source C++ class physics_shell
+   * @source `src/xrPhysics/PhysicsShellScript.cpp`, `physics_shell` binding.
    * @customConstructor physics_shell
    * @group xr_physic
    *
@@ -17672,7 +18035,7 @@ declare module "xray16" {
   /**
    * Opaque native physics condition handle.
    *
-   * @source C++ class CPHCondition
+   * @source `src/xrPhysics/PHCommander.h`, `CPHCondition` binding.
    * @customConstructor CPHCondition
    * @group xr_physic
    *
@@ -17681,13 +18044,13 @@ declare module "xray16" {
    * calls that already have a C++ condition object.
    */
   export class CPHCondition {
-    private constructor();
+    protected constructor();
   }
 
   /**
    * Opaque native physics action handle.
    *
-   * @source C++ class CPHAction
+   * @source `src/xrPhysics/PHCommander.h`, `CPHAction` binding.
    * @customConstructor CPHAction
    * @group xr_physic
    *
@@ -17696,13 +18059,113 @@ declare module "xray16" {
    * that already have a C++ action object.
    */
   export class CPHAction {
-    private constructor();
+    protected constructor();
+  }
+
+
+  /**
+   * Physics condition that becomes true on or after a selected physics step/time.
+   *
+   * @source `src/xrPhysics/PHSimpleCallsScript.cpp`, `phcondition_callonstep` binding.
+   * @customConstructor phcondition_callonstep
+   * @group xr_physic
+   *
+   * @remarks
+   * Use with `physics_world.add_call()` to schedule a physics action. Step and time interval setters compute the
+   * target step from the current physics world state.
+   */
+  export class phcondition_callonstep extends CPHCondition {
+    /**
+     * Create a physics step condition.
+     */
+    public constructor();
+
+    /**
+     * Set the absolute physics step that must be reached.
+     *
+     * @param step - Absolute physics step number.
+     */
+    public set_step(step: u64): void;
+
+    /**
+     * Set the condition to become true after a number of physics steps.
+     *
+     * @param steps - Step count from the current physics world step.
+     */
+    public set_steps_interval(steps: u64): void;
+
+    /**
+     * Set the absolute game time in milliseconds that must be reached.
+     *
+     * @param time - Absolute global time in milliseconds.
+     */
+    public set_global_time_ms(time: u32): void;
+
+    /**
+     * Set the absolute game time in seconds that must be reached.
+     *
+     * @param time - Absolute global time in seconds.
+     */
+    public set_global_time_s(time: f32): void;
+
+    /**
+     * Set the condition to become true after a millisecond interval.
+     *
+     * @param time - Interval in milliseconds.
+     */
+    public set_time_interval_ms(time: u32): void;
+
+    /**
+     * Set the condition to become true after a second interval.
+     *
+     * @param time - Interval in seconds.
+     */
+    public set_time_interval_s(time: f32): void;
+  }
+
+  /**
+   * Physics condition that expires on the selected step.
+   *
+   * @source `src/xrPhysics/PHSimpleCallsScript.cpp`, `phcondition_expireonstep` binding.
+   * @customConstructor phcondition_expireonstep
+   * @group xr_physic
+   *
+   * @remarks
+   * Subclass of `phcondition_callonstep` used by the physics commander for calls that should be considered true while
+   * expiring on the configured step.
+   */
+  export class phcondition_expireonstep extends phcondition_callonstep {
+    /**
+     * Create an expiring physics step condition.
+     */
+    public constructor();
+  }
+
+  /**
+   * Physics action that applies a constant force to a shell when run.
+   *
+   * @source `src/xrPhysics/PHSimpleCallsScript.cpp`, `phaction_constforce` binding.
+   * @customConstructor phaction_constforce
+   * @group xr_physic
+   *
+   * @remarks
+   * The action stores the target shell and force vector. The physics commander applies that force when the paired
+   * condition becomes true.
+   */
+  export class phaction_constforce extends CPHAction {
+    /**
+     * Create a constant-force physics action.
+     *
+     * @param shell - Target physics shell.
+     * @param force - Force vector to apply.
+     */
+    public constructor(shell: physics_shell, force: vector);
   }
 
   /**
    * Global physics world controls.
    *
-   * @source C++ class physics_world
+   * @source `src/xrPhysics/PHWorldScript.cpp`, `physics_world` binding.
    * @customConstructor physics_world
    * @group xr_physic
    *
@@ -17710,6 +18173,11 @@ declare module "xray16" {
    * Obtain the live world through `level.physics_world()`. Gravity changes affect the whole level.
    */
   export class physics_world {
+    /**
+     * Live level physics world returned by `level.physics_world()` in the engine.
+     */
+    private constructor();
+
     /**
      * Set world gravity.
      *
@@ -17738,11 +18206,16 @@ declare module "xray16" {
   /**
    * Animated model kinematics.
    *
-   * @source C++ class IKinematicsAnimated
+   * @source `src/xrGame/base_client_classes_script.cpp`, `IKinematicsAnimated` binding.
    * @customConstructor IKinematicsAnimated
    * @group xr_physic
    */
   export class IKinematicsAnimated {
+    /**
+     * Engine-owned animated kinematics interface.
+     */
+    private constructor();
+
     /**
      * Play an animation cycle by name.
      *
@@ -17754,8 +18227,7 @@ declare module "xray16" {
   /**
    * Client object that owns a physics shell.
    *
-   * @source C++ class CPhysicsShellHolder : public CGameObject, CParticlesPlayer,
-   *   IObjectPhysicsCollision, IPhysicsShellHolder
+   * @source `src/xrGame/script_game_object_script3.cpp`, `cast_PhysicsShellHolder` binding.
    * @customConstructor CPhysicsShellHolder
    * @group xr_physic
    *
@@ -17773,7 +18245,7 @@ declare module "xray16" {
   /**
    * Holder object that the actor can engage with.
    *
-   * @source C++ class holder
+   * @source `src/xrGame/holder_custom_script.cpp`, `holder` binding.
    * @customConstructor holder
    * @group xr_physic
    *
@@ -17781,6 +18253,11 @@ declare module "xray16" {
    * Returned only for objects that implement holder controls, such as mounted weapons or vehicles.
    */
   export class holder {
+    /**
+     * Engine-owned holder interface.
+     */
+    private constructor();
+
     /**
      * @returns Whether the actor is currently attached to the holder.
      */
@@ -17822,7 +18299,7 @@ declare module "xray16" {
   /**
    * Client object binding for `CSpaceRestrictor` zones.
    *
-   * @source C++ class CSpaceRestrictor : CGameObject
+   * @source `src/xrGame/space_restrictor_script.cpp`, `CSpaceRestrictor` binding.
    * @customConstructor CSpaceRestrictor
    * @group xr_zone
    *
@@ -17833,21 +18310,27 @@ declare module "xray16" {
   export class CSpaceRestrictor extends CGameObject {}
 
   /**
-   * Client object binding for `CCustomZone` zones.
+   * Runtime family wrapper for custom anomaly zones returned by `game_object.cast_CustomZone()`.
    *
-   * @source C++ class CCustomZone : public CSpaceRestrictor, public Feel::Touch
+   * @source `src/xrGame/script_game_object_script3.cpp`, `cast_CustomZone` binding.
    * @customConstructor CCustomZone
    * @group xr_zone
    *
    * @remarks
-   * Anomaly power and activation helpers on `game_object` require this family.
+   * No direct `CCustomZone` class constructor is registered in the script binding; concrete zone classes are exported
+   * separately. Anomaly power and activation helpers on `game_object` require this family.
    */
-  export class CCustomZone extends CSpaceRestrictor {}
+  export class CCustomZone extends CSpaceRestrictor {
+    /**
+     * Cast-only runtime wrapper.
+     */
+    protected constructor();
+  }
 
   /**
    * Client object binding for `CLevelChanger` zones.
    *
-   * @source C++ class CLevelChanger : CGameObject
+   * @source `src/xrGame/actor_script.cpp`, `CLevelChanger` binding.
    * @customConstructor CLevelChanger
    * @group xr_zone
    *
@@ -17859,7 +18342,7 @@ declare module "xray16" {
   /**
    * Client object binding for `smart_cover_object` zones.
    *
-   * @source C++ class smart_cover_object : CGameObject
+   * @source `src/xrGame/smart_cover_object_script.cpp`, `smart_cover_object` binding.
    * @customConstructor smart_cover_object
    * @group xr_zone
    *
@@ -17869,9 +18352,9 @@ declare module "xray16" {
   export class smart_cover_object extends CGameObject {}
 
   /**
-   * Client object binding for `ce_script_zone` zones.
+   * Server object binding for script zone spawn entities.
    *
-   * @source C++ class ce_script_zone : DLL_Pure
+   * @source `src/xrGame/script_zone_script.cpp`, `ce_script_zone` binding.
    * @customConstructor ce_script_zone
    * @group xr_zone
    *
@@ -17887,9 +18370,9 @@ declare module "xray16" {
   }
 
   /**
-   * Client object binding for `ce_smart_zone` zones.
+   * Server object binding for smart-zone spawn entities.
    *
-   * @source C++ class ce_smart_zone : DLL_Pure
+   * @source `src/xrGame/script_zone_script.cpp`, `ce_smart_zone` binding.
    * @customConstructor ce_smart_zone
    * @group xr_zone
    *
@@ -17983,8 +18466,14 @@ declare module "xray16" {
   export type TXR_bloodsucker_visibility_state = -1 | 0 | 1 | 2;
 
   /**
+   * Movement path type accepted by `game_object.set_path_type()` and returned by `game_object.path_type()`.
+   *
    * @source `src/xrGame/script_game_object_script2.cpp`, `game_object.EPathType` enum.
    * @group xr_script_interface
+   *
+   * @remarks
+   * The Lua binding exposes only the four named `MovementManager::EPathType` values. When mirroring these values in a
+   * TypeScript enum, use literal numeric initializers (`0`, `1`, `2`, `3`) instead of runtime `game_object` lookups.
    */
   export type TXR_game_object_path =
     | typeof game_object.game_path
@@ -18005,6 +18494,10 @@ declare module "xray16" {
    *
    * @source C++ enum ScriptEntity::EActionType
    * @group xr_script_interface
+   *
+   * @remarks
+   * `7` is native `ScriptEntity::eActionTypeRemoved`. It is used by the action-removed callback but is not exported as
+   * a named `game_object.action_types` enum member.
    */
   export type TXR_action_type =
     | typeof game_object.movement
@@ -18592,9 +19085,7 @@ declare module "xray16" {
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["action_movement"],
-            cb?: Nillable<
-        (this: void, object: game_object, action_type: TXR_action_type, target_point_index: -1) => void
-      >,
+      cb?: Nillable<(this: void, object: game_object, action_type: TXR_action_type, target_point_index: -1) => void>,
       object?: Nillable<T>
     ): void;
 
@@ -21409,7 +21900,12 @@ declare module "xray16" {
      * @param route_type - Patrol route type.
      * @param random - Whether path point selection is random.
      */
-    public set_patrol_path(path_name: string, start_type: TXR_patrol_start_type, route_type: TXR_patrol_route_type, random: boolean): void;
+    public set_patrol_path(
+      path_name: string,
+      start_type: TXR_patrol_start_type,
+      route_type: TXR_patrol_route_type,
+      random: boolean
+    ): void;
 
     /**
      * Make smart-cover target selection prefer idle positions.
@@ -21746,7 +22242,14 @@ declare module "xray16" {
      * @param internal_type - Internal monster sound id.
      * @returns Registered sound id, or `0` when this object is not a custom monster.
      */
-    public add_sound(prefix: string, max_count: u32, type: TXR_snd_type, priority: u32, mask: u32, internal_type: u32): u32;
+    public add_sound(
+      prefix: string,
+      max_count: u32,
+      type: TXR_snd_type,
+      priority: u32,
+      mask: u32,
+      internal_type: u32
+    ): u32;
 
     /**
      * Register an NPC sound with a bone name.
@@ -27323,9 +27826,13 @@ declare module "xray16" {
   }
 
   /**
-   * UI event id.
+   * UI event id passed to window message handlers such as `CUIScriptWnd.OnKeyboard()`.
    *
+   * @source C++ class ui_events
    * @group xr_ui_event
+   *
+   * @remarks
+   * Values identify UI notifications, not keyboard or mouse button codes. For input key codes use `TXR_DIK_key`.
    */
   export type TXR_ui_event = EnumeratedStaticsValues<typeof ui_events>;
 
@@ -28384,16 +28891,20 @@ declare module "xray16" {
   }
 
   /**
-   * Static key name from `DIK_keys`.
+   * Static key constant name from `DIK_keys`.
    *
    * @group xr_ui_event
    */
   export type TXR_DIK_key_name = EnumeratedStaticsKeys<typeof DIK_keys>;
 
   /**
-   * DIK, mouse, or gamepad key code.
+   * DIK, mouse, or gamepad key code passed to keyboard/input callbacks.
    *
+   * @source C++ class DIK_keys
    * @group xr_ui_event
+   *
+   * @remarks
+   * The binding keeps the legacy `DIK_*` names, but values come from SDL scancodes plus engine mouse/gamepad ranges.
    */
   export type TXR_DIK_key = EnumeratedStaticsValues<typeof DIK_keys>;