xray16 1.6.1 → 1.6.3

package/xray16.d.ts

@@ -371,6 +371,21 @@ declare module "xray16" {
    */
   export const object: typeof XR_object;
 
+  /**
+   * Opaque native patrol path handle used by low-level movement action bindings.
+   *
+   * @source C++ class CPatrolPath
+   * @customConstructor CPatrolPath
+   * @group xr_action
+   *
+   * @remarks
+   * The engine does not register this as a public Lua constructor. Scripts normally use the public `patrol` parameter
+   * object when constructing movement actions; this handle models native code paths that pass a raw patrol path pointer.
+   */
+  export class CPatrolPath {
+    private constructor();
+  }
+
   /**
    * Movement action for stalkers, monsters, and vehicles.
    *
@@ -383,7 +398,6 @@ declare module "xray16" {
    * actions. Use the constructor group that matches the object receiving the resulting `entity_action`.
    */
   export class move extends EngineBinding {
-    // Todo: All enums are in one static, probably should declare few parent interfaces / classes with enums
     /**
      * Engine enum value for `move.crouch`.
      */
@@ -545,7 +559,7 @@ declare module "xray16" {
      * @param pathType - Detail path type id.
      * @param game_object - Target object.
      */
-    public constructor(bodyState: number, movementType: TXR_move, pathType: number, 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.
@@ -557,9 +571,9 @@ declare module "xray16" {
      * @param value - Speed or distance value.
      */
     public constructor(
-      bodyState: number,
-      movementType: TXR_move,
-      pathType: number,
+      bodyState: TXR_body_state,
+      movementType: TXR_movement_type,
+      pathType: TXR_detail_path_type,
       game_object: game_object,
       value: f32
     );
@@ -572,7 +586,7 @@ declare module "xray16" {
      * @param pathType - Detail path type id.
      * @param patrol - Patrol path parameters.
      */
-    public constructor(bodyState: number, movementType: TXR_move, pathType: number, 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.
@@ -583,7 +597,7 @@ declare module "xray16" {
      * @param patrol - Patrol path parameters.
      * @param value - Speed or distance value.
      */
-    public constructor(bodyState: number, movementType: TXR_move, pathType: number, 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.
@@ -593,7 +607,7 @@ declare module "xray16" {
      * @param pathType - Detail path type id.
      * @param vector - Target position.
      */
-    public constructor(bodyState: number, movementType: TXR_move, pathType: number, 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.
@@ -604,7 +618,7 @@ declare module "xray16" {
      * @param vector - Target position.
      * @param value - Speed or distance value.
      */
-    public constructor(bodyState: number, movementType: TXR_move, pathType: number, 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.
@@ -757,14 +771,14 @@ declare module "xray16" {
      *
      * @param pathType - Detail path type id.
      */
-    public path(pathType: number): void;
+    public path(pathType: TXR_detail_path_type): void;
 
     /**
      * Set movement type.
      *
      * @param movementType - Movement type id.
      */
-    public move(movementType: number): void;
+    public move(movementType: TXR_movement_type): void;
 
     /**
      * Set target position.
@@ -781,12 +795,18 @@ declare module "xray16" {
     public input(inputKey: number): void;
 
     /**
-     * Set patrol path.
+     * Set patrol path from a native patrol path pointer.
      *
-     * @param patrolPath - Patrol path object.
-     * @param path_name - Patrol path name.
+     * @source `src/xrGame/script_movement_action_script.cpp`, `move.patrol` binding.
+     *
+     * @remarks
+     * This low-level binding expects an internal `CPatrolPath*`, not the public `patrol` parameter object. Prefer the
+     * movement action constructors that accept `patrol` unless native code passes a raw patrol path pointer.
+     *
+     * @param patrolPath - Internal native patrol path handle.
+     * @param path_name - Patrol path name copied into the movement action.
      */
-    public patrol(patrolPath: unknown, path_name: string): void;
+    public patrol(patrolPath: CPatrolPath, path_name: string): void;
 
     /**
      * Set target object.
@@ -800,20 +820,69 @@ declare module "xray16" {
      *
      * @param bodyState - Body state id.
      */
-    public body(bodyState: number): void;
+    public body(bodyState: TXR_body_state): void;
   }
 
   /**
+   * Movement action constants exposed by the `move` class.
+   *
    * @group xr_action
    */
   export type TXR_move = EnumeratedStaticsValues<typeof move>;
 
+  /**
+   * Body-state constants accepted by stalker movement actions.
+   *
+   * @source `src/xrGame/script_movement_action_script.cpp`, `move.body` enum.
+   * @group xr_action
+   */
+  export type TXR_body_state = typeof move.crouch | typeof move.standing;
+
+  /**
+   * Movement-type constants accepted by stalker movement actions.
+   *
+   * @source `src/xrGame/script_movement_action_script.cpp`, `move.move` enum.
+   * @group xr_action
+   */
+  export type TXR_movement_type = typeof move.walk | typeof move.run | typeof move.stand;
+
+  /**
+   * Detail-path constants accepted by stalker movement actions.
+   *
+   * @source `src/xrGame/script_movement_action_script.cpp`, `move.path` enum.
+   * @group xr_action
+   */
+  export type TXR_detail_path_type = typeof move.line | typeof move.dodge | typeof move.criteria;
+
+  /**
+   * Patrol start mode accepted by native patrol path managers.
+   *
+   * @source C++ enum EPatrolStartType
+   * @group xr_action
+   *
+   * @remarks
+   * `1` is the native `ePatrolStartTypeLast` value. The Lua `patrol` constants do not expose a dedicated name for it.
+   */
+  export type TXR_patrol_start_type = -1 | 0 | 1 | 2 | 3 | 4;
+
+  /**
+   * Patrol route behavior accepted by native patrol path managers.
+   *
+   * @source C++ enum EPatrolRouteType
+   * @group xr_action
+   */
+  export type TXR_patrol_route_type = typeof patrol.stop | typeof patrol.continue | typeof patrol.dummy;
+
   /**
    * Patrol path parameters used by movement actions.
    *
-   * @source C++ class patrol
+   * @source `src/xrAICore/Navigation/PatrolPath/patrol_path_params_script.cpp`, `CPatrolPathParams` binding.
    * @customConstructor patrol
    * @group xr_action
+   *
+   * @remarks
+   * The Lua-visible `patrol` class stores a patrol path name, start mode, route mode, randomization flag, and optional
+   * custom point index. Movement action constructors copy those values into the native movement action.
    */
   export class patrol extends EngineBinding {
     /**
@@ -851,18 +920,22 @@ declare module "xray16" {
     /**
      * Create patrol path parameters.
      *
+     * @remarks
+     * The native constructor resolves `name` through patrol path storage. Missing patrol paths can assert in debug
+     * builds. Use `patrol.custom` with `customPointIndex` to start from an explicit patrol point.
+     *
      * @param name - Patrol path name.
-     * @param startType - Patrol start type.
-     * @param routeType - Patrol route type.
-     * @param bool - Whether random point selection is enabled.
-     * @param int - Custom start point index.
+     * @param startType - Patrol start mode.
+     * @param routeType - Patrol route mode.
+     * @param random - Whether random point selection is enabled.
+     * @param customPointIndex - Custom start point index.
      */
     public constructor(
       name?: string,
-      startType?: TXR_patrol_type,
-      routeType?: TXR_patrol_type,
-      bool?: boolean,
-      int?: u32
+      startType?: TXR_patrol_start_type,
+      routeType?: TXR_patrol_route_type,
+      random?: boolean,
+      customPointIndex?: u32
     );
 
     /**
@@ -954,7 +1027,13 @@ declare module "xray16" {
   }
 
   /**
+   * Patrol start or route enum value.
+   *
    * @group xr_action
+   *
+   * @remarks
+   * The xray binding exports patrol start and route enums on the same Lua class, so this type is a flattened union of
+   * both enum groups.
    */
   export type TXR_patrol_type = EnumeratedStaticsValues<typeof patrol>;
 
@@ -1273,7 +1352,7 @@ declare module "xray16" {
      *
      * @param state - Mental state id.
      */
-    public constructor(state: number); /* Enum MonsterSpace::EMentalState */
+    public constructor(state: TXR_mental_state);
 
     /**
      * Set monster animation action and extra value.
@@ -1284,7 +1363,7 @@ declare module "xray16" {
      * @param state - Monster animation action id.
      * @param value - Extra action value.
      */
-    public constructor(state: number /* Enum MonsterSpace::EScriptMonsterAnimAction */, value: i32);
+    public constructor(state: TXR_monster_animation_action, value: i32);
 
     /**
      * @returns Whether the animation action is complete.
@@ -1296,7 +1375,7 @@ declare module "xray16" {
      *
      * @param state - Mental state id.
      */
-    public type(state: number /* Enum MonsterSpace::EMentalState */): void;
+    public type(state: TXR_mental_state): void;
 
     /**
      * Set animation name.
@@ -1312,10 +1391,51 @@ declare module "xray16" {
   export type TXR_animation_key = EnumeratedStaticsKeys<typeof anim>;
 
   /**
+   * Animation action constants exposed by the `anim` class.
+   *
    * @group xr_action
    */
   export type TXR_animation = EnumeratedStaticsValues<typeof anim>;
 
+  /**
+   * Mental-state constants accepted by stalker animation and movement APIs.
+   *
+   * @source `src/xrGame/script_animation_action_script.cpp`, `anim.type` enum.
+   * @group xr_action
+   */
+  export type TXR_mental_state = typeof anim.danger | typeof anim.free | typeof anim.panic;
+
+  /**
+   * Monster animation action constants accepted by the two-argument `anim` constructor.
+   *
+   * @source `src/xrGame/script_animation_action_script.cpp`, `anim.monster` enum.
+   * @group xr_action
+   */
+  export type TXR_monster_animation_action =
+    | typeof anim.stand_idle
+    | typeof anim.capture_prepare
+    | typeof anim.sit_idle
+    | typeof anim.lie_idle
+    | typeof anim.eat
+    | typeof anim.sleep
+    | typeof anim.rest
+    | typeof anim.attack
+    | typeof anim.look_around
+    | typeof anim.turn;
+
+  /**
+   * Monster head-animation constants accepted by trader sound actions.
+   *
+   * @source `src/xrGame/script_sound_action_script.cpp`, trader-specific sound constructor.
+   * @group xr_action
+   */
+  export type TXR_monster_head_animation =
+    | typeof MonsterSpace.head_anim_normal
+    | typeof MonsterSpace.head_anim_angry
+    | typeof MonsterSpace.head_anim_glad
+    | typeof MonsterSpace.head_anim_kind
+    | -1;
+
   /**
    * Sound action for scripted AI behavior.
    *
@@ -1500,7 +1620,7 @@ declare module "xray16" {
      *
      * @param type - Monster sound type id.
      */
-    public constructor(type: TXR_sound_type); /* MonsterSound::EType */
+    public constructor(type: TXR_sound_type);
 
     /**
      * Play a monster sound by type with extra value.
@@ -1511,19 +1631,22 @@ declare module "xray16" {
      * @param type - Monster sound type id.
      * @param value - Extra sound value.
      */
-    public constructor(type: TXR_sound_type /* Enum MonsterSound::EType*/, value: number);
+    public constructor(type: TXR_sound_type, value: number);
 
     /**
      * Play a trader sound with a head animation.
      *
+     * @source `src/xrGame/script_sound_action_script.cpp`, trader-specific sound constructor.
+     *
      * @remarks
-     * Trader-specific overload. The head animation is one of `MonsterSpace.head_anim_*`.
+     * Trader-specific overload. The head animation is one of the `MonsterSpace.head_anim_*` constants. The native enum
+     * also has `-1` for no head animation, but that value is not exported as a named Lua constant.
      *
      * @param value1 - Sound prefix or collection.
      * @param value2 - Sound name.
      * @param type - Monster head animation type.
      */
-    public constructor(value1: string, value2: string, type: unknown); /* Enum MonsterSpace::EMonsterHeadAnimType */
+    public constructor(value1: string, value2: string, type: TXR_monster_head_animation);
 
     /**
      * Set sound by name.
@@ -1565,7 +1688,7 @@ declare module "xray16" {
      *
      * @param type - Sound type id.
      */
-    public set_sound_type(type: number /* ESoundTypes */): void;
+    public set_sound_type(type: TXR_snd_type): void;
 
     /**
      * @returns Whether sound playback is complete.
@@ -1810,6 +1933,27 @@ type Nillable<T> = T | null | undefined;
 type Nullable<T> = T | null;
 
 declare module "xray16" {
+  /**
+   * Restriction-space category stored on space restrictors and used by ALife restriction events.
+   *
+   * @group xr_alife
+   *
+   * @remarks
+   * Values mirror `RestrictionSpace::ERestrictorTypes`: default none/out/in are `0`, `1`, `2`; runtime none/in/out
+   * are `3`, `4`, `5`.
+   */
+  export type TXR_restrictor_type = 0 | 1 | 2 | 3 | 4 | 5;
+
+  /**
+   * Dynamic restriction-list type accepted by APIs that clear ALife in/out restriction arrays.
+   *
+   * @group xr_alife
+   *
+   * @remarks
+   * The engine switch handles only runtime `eRestrictorTypeIn` (`4`) and `eRestrictorTypeOut` (`5`) here.
+   */
+  export type TXR_dynamic_restrictor_type = 4 | 5;
+
   /**
    * Access point for ALife simulation objects and registries.
    *
@@ -1945,7 +2089,7 @@ declare module "xray16" {
      * @param objectId - Restricted object id.
      * @param type - Restriction type.
      */
-    public remove_all_restrictions(objectId: u16, type: i32 /* Enum RestrictionSpace::ERestrictorTypes */): void;
+    public remove_all_restrictions(objectId: u16, type: TXR_dynamic_restrictor_type): void;
 
     /**
      * Remove an inside-space restriction from an offline monster.
@@ -2517,7 +2661,7 @@ declare module "xray16" {
      *
      * @returns Movement path type.
      */
-    public path_type(): number; /* EPathType */
+    public path_type(): TXR_game_object_path;
 
     /**
      * Get the detail path manager.
@@ -2586,14 +2730,14 @@ declare module "xray16" {
      *
      * @param type - Patrol route type.
      */
-    public route_type(type: u32 /* Const enum PatrolPathManager::EPatrolRouteType */): void;
+    public route_type(type: TXR_patrol_route_type): void;
 
     /**
      * Get patrol route behavior.
      *
      * @returns Patrol route type.
      */
-    public route_type(): u32;
+    public route_type(): TXR_patrol_route_type;
 
     /**
      * Enable or disable random patrol point selection.
@@ -2614,14 +2758,14 @@ declare module "xray16" {
      *
      * @param type - Patrol start type.
      */
-    public start_type(type: u32 /* Const enum PatrolPathManager::EPatrolStartType */): void;
+    public start_type(type: TXR_patrol_start_type): void;
 
     /**
      * Get how the patrol path starts.
      *
      * @returns Patrol start type.
      */
-    public start_type(): u32;
+    public start_type(): TXR_patrol_start_type;
 
     /**
      * Set the starting patrol point.
@@ -3622,12 +3766,12 @@ declare module "xray16" {
   /**
    * @group xr_alife
    */
-  type TXR_class_key = EnumeratedStaticsKeys<typeof clsid>;
+  export type TXR_class_key = EnumeratedStaticsKeys<typeof clsid>;
 
   /**
    * @group xr_alife
    */
-  type TXR_class_id = EnumeratedStaticsValues<typeof clsid>;
+  export type TXR_class_id = EnumeratedStaticsValues<typeof clsid>;
 
   /**
    * Factory for ALife server object bindings.
@@ -5427,7 +5571,7 @@ declare module "xray16" {
     /**
      * @returns How the danger was perceived.
      */
-    public perceive_type(): number; /* CDangerObject::EDangerPerceiveType */
+    public perceive_type(): TXR_danger_perceive_type;
 
     /**
      * Get the object attached to this danger event.
@@ -5440,6 +5584,13 @@ declare module "xray16" {
     public dependent_object(): Nullable<game_object>;
   }
 
+  /**
+   * How a danger event was perceived by AI memory.
+   *
+   * @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;
   /**
    * @group xr_memory
    */
@@ -7433,7 +7584,7 @@ declare module "xray16" {
    * @source C++ enum EGameIDs
    * @group xr_game
    */
-  export type TXR_EGameID = 0 | 1 | 2 | 8 | 16 | 32 | 64;
+  export type TXR_EGameID = 0 | 1 | 2 | 4 | 8 | 16 | 32 | 64;
 
   /**
    * Game type constants used by menu and multiplayer scripts.
@@ -7500,18 +7651,18 @@ declare module "xray16" {
     /**
      * Engine enum value for `GAME_TYPE.GAME_DUMMY`.
      */
-    public static readonly GAME_DUMMY: 255; // Temporary g
+    public static readonly GAME_DUMMY: 255;
   }
 
   /**
    * @group xr_game
    */
-  type TXR_GAME_TYPE = EnumeratedStaticsValues<typeof GAME_TYPE>;
+  export type TXR_GAME_TYPE = EnumeratedStaticsValues<typeof GAME_TYPE>;
 
   /**
    * Single-player difficulty constants.
    *
-   * @source C++ class game_difficulty
+   * @source `src/xrGame/game_cl_single.h`, `ESingleGameDifficulty`; `src/xrGame/level_script.cpp`, `game_difficulty` binding
    * @customConstructor game_difficulty
    * @group xr_game
    */
@@ -7794,51 +7945,51 @@ declare module "xray16" {
     /**
      * Engine enum value for `hit.burn`.
      */
-    public static readonly burn = 0;
+    public static readonly burn: 0;
     /**
      * Engine enum value for `hit.chemical_burn`.
      */
-    public static readonly chemical_burn = 2;
+    public static readonly chemical_burn: 2;
     /**
      * Engine enum value for `hit.dummy`.
      */
-    public static readonly dummy = 12;
+    public static readonly dummy: 12;
     /**
      * Engine enum value for `hit.explosion`.
      */
-    public static readonly explosion = 7;
+    public static readonly explosion: 7;
     /**
      * Engine enum value for `hit.fire_wound`.
      */
-    public static readonly fire_wound = 8;
+    public static readonly fire_wound: 8;
     /**
      * Engine enum value for `hit.light_burn`.
      */
-    public static readonly light_burn = 11;
+    public static readonly light_burn: 11;
     /**
      * Engine enum value for `hit.physic_strike`.
      */
-    public static readonly physic_strike = 10;
+    public static readonly physic_strike: 10;
     /**
      * Engine enum value for `hit.radiation`.
      */
-    public static readonly radiation = 3;
+    public static readonly radiation: 3;
     /**
      * Engine enum value for `hit.shock`.
      */
-    public static readonly shock = 1;
+    public static readonly shock: 1;
     /**
      * Engine enum value for `hit.strike`.
      */
-    public static readonly strike = 5;
+    public static readonly strike: 5;
     /**
      * Engine enum value for `hit.telepatic`.
      */
-    public static readonly telepatic = 4;
+    public static readonly telepatic: 4;
     /**
      * Engine enum value for `hit.wound`.
      */
-    public static readonly wound = 6;
+    public static readonly wound: 6;
 
     /**
      * Hit direction.
@@ -8380,6 +8531,231 @@ declare module "xray16" {
 }
 
 declare module "xray16" {
+  /**
+   * Ray query target bitmask accepted by `level.ray_pick` and `ray_pick`.
+   *
+   * @source `src/xrGame/level_script.cpp`, `rq_target` binding.
+   * @customConstructor rq_target
+   * @group xr_level
+   */
+  export class rq_target {
+    /**
+     * No ray query target.
+     */
+    public static readonly rqtNone: 0;
+
+    /**
+     * Dynamic game objects.
+     */
+    public static readonly rqtObject: 1;
+
+    /**
+     * Static level geometry.
+     */
+    public static readonly rqtStatic: 2;
+
+    /**
+     * Dynamic collision shapes.
+     */
+    public static readonly rqtShape: 4;
+
+    /**
+     * Dynamic obstacles.
+     */
+    public static readonly rqtObstacle: 8;
+
+    /**
+     * Dynamic game objects and static level geometry.
+     */
+    public static readonly rqtBoth: 3;
+
+    /**
+     * Dynamic game objects, collision shapes, and obstacles.
+     */
+    public static readonly rqtDyn: 13;
+  }
+
+  /**
+   * Ray query target bitmask value.
+   *
+   * @group xr_level
+   */
+  export type TXR_rq_target = EnumeratedStaticsValues<typeof rq_target>;
+
+  /**
+   * Result object filled by level ray queries.
+   *
+   * @source `src/xrGame/raypick.h`, `script_rq_result`.
+   * @customConstructor rq_result
+   * @group xr_level
+   *
+   * @remarks
+   * A new result starts with `object = null`, `range = 0`, and `element = 0`. `level.ray_pick` updates it only when the
+   * query returns `true`.
+   */
+  export class rq_result extends EngineBinding {
+    /**
+     * Create an empty ray query result.
+     */
+    public constructor();
+
+    /**
+     * Hit object, or `null` when the hit is not a game object.
+     */
+    public readonly object: Nullable<game_object>;
+
+    /**
+     * Distance from ray origin to the hit.
+     */
+    public readonly range: f32;
+
+    /**
+     * Hit model element id, or `0` when the hit has no element.
+     */
+    public readonly element: i32;
+  }
+
+  /**
+   * Active weather descriptor exposed through `CEnvironment.current()`.
+   *
+   * @source C++ class CEnvDescriptor
+   * @customConstructor CEnvDescriptor
+   * @group xr_level
+   *
+   * @remarks
+   * Lua receives the engine-owned current descriptor; scripts should treat it as read-only.
+   */
+  export class CEnvDescriptor {
+    /**
+     * Current fog density.
+     */
+    public readonly fog_density: f32;
+
+    /**
+     * Current far clipping plane distance.
+     */
+    public readonly far_plane: f32;
+  }
+
+  /**
+   * Active weather environment controller.
+   *
+   * @source C++ class CEnvironment
+   * @customConstructor CEnvironment
+   * @group xr_level
+   *
+   * @remarks
+   * Returned by `level.environment()`. The Lua binding exposes only access to the current descriptor.
+   */
+  export class CEnvironment {
+    /**
+     * Get the current interpolated environment descriptor.
+     *
+     * @returns Engine-owned current environment descriptor.
+     */
+    public current(): CEnvDescriptor;
+  }
+
+  /**
+   * Reusable ray query object.
+   *
+   * @source `src/xrGame/level_script.cpp`, `ray_pick` binding.
+   * @customConstructor ray_pick
+   * @group xr_level
+   */
+  export class ray_pick extends EngineBinding {
+    /**
+     * Create an empty ray query with no target flags and zero range.
+     */
+    public constructor();
+
+    /**
+     * Create a configured ray query.
+     *
+     * @param position - Ray origin.
+     * @param direction - Ray direction.
+     * @param range - Ray range.
+     * @param target - Ray query target flags.
+     * @param ignore_object - Object ignored by the query, or `null` / `undefined`.
+     */
+    public constructor(
+      position: vector,
+      direction: vector,
+      range: f32,
+      target: TXR_rq_target,
+      ignore_object: Nillable<game_object>
+    );
+
+    /**
+     * Set ray origin.
+     *
+     * @param position - Ray origin.
+     */
+    public set_position(position: vector): void;
+
+    /**
+     * Set ray direction.
+     *
+     * @param direction - Ray direction.
+     */
+    public set_direction(direction: vector): void;
+
+    /**
+     * Set ray range.
+     *
+     * @param range - Ray range.
+     */
+    public set_range(range: f32): void;
+
+    /**
+     * Set ray target flags.
+     *
+     * @param target - Ray query target flags.
+     */
+    public set_flags(target: TXR_rq_target): void;
+
+    /**
+     * Set object ignored by the query.
+     *
+     * @param ignore_object - Object ignored by the query, or `null` / `undefined`.
+     */
+    public set_ignore_object(ignore_object: Nillable<game_object>): void;
+
+    /**
+     * Execute the ray query and update this query's result on hit.
+     *
+     * @returns Whether the ray hit anything.
+     */
+    public query(): boolean;
+
+    /**
+     * Get last ray query result.
+     *
+     * @returns Last ray query result.
+     */
+    public get_result(): rq_result;
+
+    /**
+     * Get hit object from the last ray query.
+     *
+     * @returns Hit object, or `null`.
+     */
+    public get_object(): Nullable<game_object>;
+
+    /**
+     * Get hit distance from the last ray query.
+     *
+     * @returns Hit distance.
+     */
+    public get_distance(): f32;
+
+    /**
+     * Get hit model element id from the last ray query.
+     *
+     * @returns Hit model element id, or `0`.
+     */
+    public get_element(): i32;
+  }
   /**
    * Global helpers for the currently loaded level.
    *
@@ -8516,25 +8892,31 @@ declare module "xray16" {
     client_spawn_manager(this: void): client_spawn_manager;
 
     /**
-     * Get actor object used by debug helpers.
+     * Get the current actor object used by debug helpers.
+     *
+     * @source `src/xrGame/level_script.cpp`, `debug_actor` binding.
      *
      * @remarks
-     * Exported only in debug builds.
+     * Exported only in debug builds. The native helper logs a warning on first use and returns `null` when the current
+     * level entity is not an actor.
      *
-     * @returns Actor game object.
+     * @returns Actor game object, or `null` when no actor is current.
      */
-    debug_actor(this: void): game_object;
+    debug_actor(this: void): Nullable<game_object>;
 
     /**
-     * Find an object by debug name.
+     * Find an online object by debug name.
+     *
+     * @source `src/xrGame/level_script.cpp`, `debug_object` binding.
      *
      * @remarks
-     * Exported only in debug builds.
+     * Exported only in debug builds. The native helper logs a warning on first use and searches loaded level objects by
+     * runtime name.
      *
-     * @param name - Object name.
-     * @returns Matching game object.
+     * @param name - Runtime object name.
+     * @returns Matching online object, or `null` when no object with this name is loaded.
      */
-    debug_object(this: void, name: string): game_object;
+    debug_object(this: void, name: string): Nullable<game_object>;
 
     /**
      * Disable player input.
@@ -8550,11 +8932,11 @@ declare module "xray16" {
     enable_input(this: void): void;
 
     /**
-     * Get the active environment object.
+     * Get the active weather environment controller.
      *
-     * @returns Engine environment object.
+     * @returns Engine-owned environment controller.
      */
-    environment(this: void): unknown /* XR_CEnvironment */;
+    environment(this: void): CEnvironment;
 
     /**
      * Get current game state id.
@@ -8585,7 +8967,9 @@ declare module "xray16" {
     /**
      * Get active single-player difficulty.
      *
-     * @returns Difficulty id.
+     * @source `src/xrGame/level_script.cpp`, `get_game_difficulty`.
+     *
+     * @returns Current `game_difficulty` enum value.
      */
     get_game_difficulty(this: void): TXR_game_difficulty;
 
@@ -8621,6 +9005,11 @@ declare module "xray16" {
      * Get the object under the crosshair.
      *
      * @since OpenXRay 2014-12-27, c82669625
+     * @source `src/xrGame/level_script.cpp`, `g_get_target_obj`.
+     *
+     * @remarks
+     * Reads the current HUD ray query. Returns `null` when the ray hit has no object or the hit object is not a
+     * `CGameObject`.
      *
      * @returns Target object, or `null` when nothing is targeted.
      */
@@ -8813,10 +9202,15 @@ declare module "xray16" {
     name<T extends string = string>(this: void): T;
 
     /**
-     * Find an online object by id.
+     * Find an online object by runtime id.
+     *
+     * @source `src/xrGame/level_script.cpp`, `object_by_id` binding.
+     *
+     * @remarks
+     * Looks up the object in `Level().Objects` by network id. This does not search offline ALife objects.
      *
-     * @param object_id - Game object id.
-     * @returns Matching object, or `null` when it is not online.
+     * @param object_id - Runtime network object id.
+     * @returns Matching online object, or `null` when it is not loaded on the level.
      */
     object_by_id(this: void, object_id: u16): Nullable<game_object>;
 
@@ -8970,14 +9364,17 @@ declare module "xray16" {
     /**
      * Set active single-player difficulty.
      *
+     * @source `src/xrGame/level_script.cpp`, `set_game_difficulty`.
+     *
      * @remarks
-     * Updates the global difficulty and notifies the active single-player game state.
+     * Updates the global difficulty and notifies the active single-player game state. The native binding verifies that
+     * the current game state is `game_cl_Single`.
      *
      * @throws If the active game state is not single-player.
      *
-     * @param difficulty - Difficulty id.
+     * @param difficulty - `game_difficulty` enum value.
      */
-    set_game_difficulty(this: void, difficulty: unknown /* Enum ESingleGameDifficulty */): void;
+    set_game_difficulty(this: void, difficulty: TXR_game_difficulty): void;
 
     /**
      * Set a post-process effector factor.
@@ -9146,7 +9543,7 @@ declare module "xray16" {
      * Cast a ray through the level collision world.
      *
      * @remarks
-     * `result` is updated only when this returns `true`.
+     * `result` is updated only when this returns `true`. Use `rq_target` flags to choose static, object, or dynamic collision targets.
      *
      * @param position - Ray origin.
      * @param direction - Ray direction.
@@ -9161,8 +9558,8 @@ declare module "xray16" {
       position: vector,
       direction: vector,
       range: f32,
-      target: unknown,
-      result: unknown,
+      target: TXR_rq_target,
+      result: rq_result,
       ignore_object: Nillable<game_object>
     ): boolean;
   }
@@ -9216,6 +9613,20 @@ declare module "xray16" {
    */
   export function LuabindClass(): ClassDecorator;
 
+  /**
+   * Opaque native Lua state pointer.
+   *
+   * @source C++ type lua_State
+   * @customConstructor lua_State
+   * @group xr_luabind
+   */
+  export class lua_State {
+    /**
+     * Native engine pointer; scripts do not construct Lua states.
+     */
+    private constructor();
+  }
+
   /**
    * Runtime metadata for a LuaBind class.
    *
@@ -9253,7 +9664,7 @@ declare module "xray16" {
    * @param lua_state - Lua state to inspect.
    * @returns Registered class names.
    */
-  export function class_names(this: void, lua_state: unknown /* Lua_State*/): LuaTable<number, string>;
+  export function class_names(this: void, lua_state: lua_State): LuaTable<number, string>;
 
   /**
    * Get LuaBind metadata for an object or class.
@@ -9263,7 +9674,7 @@ declare module "xray16" {
    * @param target - Object or class to inspect.
    * @returns LuaBind class metadata.
    */
-  export function class_info(this: void, target: unknown): class_info_data;
+  export function class_info(this: void, target: object): class_info_data;
 }
 
 declare module "xray16" {
@@ -10141,6 +10552,21 @@ declare module "xray16" {
     public constructor();
   }
 
+  /**
+   * Opaque native quaternion used by matrix transform helpers.
+   *
+   * @source C++ struct Fquaternion
+   * @customConstructor Fquaternion
+   * @group xr_math
+   *
+   * @remarks
+   * The engine binds matrix transforms against this native quaternion type, but does not expose a public constructor or
+   * script-side quaternion operations in these Lua bindings.
+   */
+  export class Fquaternion {
+    private constructor();
+  }
+
   /**
    * Mutable 4x4 transform matrix.
    *
@@ -10207,7 +10633,7 @@ declare module "xray16" {
      * @param position - Translation vector.
      * @returns This matrix.
      */
-    public mk_xform(rotation: unknown /* _quaternion<float> */, position: vector): matrix;
+    public mk_xform(rotation: Fquaternion, position: vector): matrix;
 
     /**
      * Copy another matrix.
@@ -10550,7 +10976,7 @@ declare module "xray16" {
      * @param password - Account password.
      * @param cb - Completion callback.
      */
-    public get_account_profiles(email: string, password: string, cb: account_profiles_cb): unknown;
+    public get_account_profiles(email: string, password: string, cb: account_profiles_cb): void;
 
     /**
      * Get profiles found by the last email search.
@@ -11335,7 +11761,7 @@ declare module "xray16" {
    * @group xr_multiplayer
    *
    * @remarks
-   * Multiplayer match state, not single-player task or story state. `type` uses raw engine `EGameIDs` values.
+   * Multiplayer match state, not single-player task or story state. `type` uses engine `EGameIDs` values.
    */
   export class game_GameState extends DLL_Pure {
     /**
@@ -11351,7 +11777,7 @@ declare module "xray16" {
     /**
      * Multiplayer game type id.
      */
-    public type: number; /* EGameIDs */
+    public type: TXR_EGameID;
 
     /**
      * Create an empty multiplayer game state.
@@ -11376,39 +11802,165 @@ declare module "xray16" {
     /**
      * @returns Multiplayer game type id.
      */
-    public Type(): number; /* EGameIDs */
+    public Type(): TXR_EGameID;
   }
 
   /**
-   * Todo:
-   *
-   *    class_<game_PlayerState, no_bases, default_holder, WrapType>("game_PlayerState")
-   *         .def(constructor<>())
-   *         .def_readwrite("team", &BaseType::team)
-   *         .def_readwrite("kills", &BaseType::m_iRivalKills)
-   *         .def_readwrite("deaths", &BaseType::m_iDeaths)
-   *         .def_readwrite("money_for_round", &BaseType::money_for_round)
-   *         .def_readwrite("flags", &BaseType::flags__)
-   *         .def_readwrite("ping", &BaseType::ping)
-   *         .def_readwrite("GameID", &BaseType::GameID)
-   *         //.def_readwrite("Skip", &BaseType::Skip)
-   *         .def_readwrite("lasthitter", &BaseType::lasthitter)
-   *         .def_readwrite("lasthitweapon", &BaseType::lasthitweapon)
-   *         .def_readwrite("skin", &BaseType::skin)
-   *         .def_readwrite("RespawnTime", &BaseType::RespawnTime)
-   *         .def_readwrite("money_delta", &BaseType::money_delta).
-   *
-   *         .def_readwrite("pItemList", &BaseType::pItemList)
-   *         .def_readwrite("LastBuyAcount", &BaseType::LastBuyAcount)
-   *         .def("testFlag", &BaseType::testFlag)
-   *         .def("setFlag", &BaseType::setFlag)
-   *         .def("resetFlag", &BaseType::resetFlag)
-   *         .def("getName", &BaseType::getName)
-   *         .def("setName", &BaseType::setName)
-   *         .def("clear", &BaseType::clear, &WrapType::clear_static)
-   *         .def("net_Export", &BaseType::net_Export, &WrapType::net_Export_static)
-   *         .def("net_Import", &BaseType::net_Import, &WrapType::net_Import_static).
+   * Opaque native list of multiplayer buy/spawn item ids.
+   *
+   * @source C++ type game_PlayerState::PLAYER_ITEMS_LIST (`xr_vector<u16>`)
+   * @customConstructor game_player_item_list
+   * @group xr_multiplayer
+   *
+   * @remarks
+   * The field is exposed as a native vector object. No public vector mutation or iteration helpers are declared here
+   * because the binding only exposes the field, not a script API for `xr_vector<u16>` itself.
    */
+  export class game_player_item_list {
+    private constructor();
+  }
+
+  /**
+   * Multiplayer player state replicated by multiplayer game modes.
+   *
+   * @source C++ class game_PlayerState
+   * @customConstructor game_PlayerState
+   * @group xr_multiplayer
+   *
+   * @remarks
+   * This is the networked player state used by multiplayer server/client code. The public fields are the exact names
+   * exported by the Lua binding, which do not always match the underlying C++ member names.
+   */
+  export class game_PlayerState {
+    /**
+     * Player team id.
+     */
+    public team: u8;
+
+    /**
+     * Rival kill count.
+     */
+    public kills: i16;
+
+    /**
+     * Death count.
+     */
+    public deaths: i16;
+
+    /**
+     * Current multiplayer money amount.
+     */
+    public money_for_round: i32;
+
+    /**
+     * Packed `GAME_PLAYER_FLAG_*` bitmask.
+     */
+    public flags: u16;
+
+    /**
+     * Player network ping.
+     */
+    public ping: u16;
+
+    /**
+     * Current player game id.
+     */
+    public GameID: u16;
+
+    /**
+     * Object id of the last hitter.
+     */
+    public lasthitter: u16;
+
+    /**
+     * Weapon id used by the last hitter.
+     */
+    public lasthitweapon: u16;
+
+    /**
+     * Multiplayer skin id.
+     */
+    public skin: i8;
+
+    /**
+     * Scheduled respawn time.
+     */
+    public RespawnTime: u32;
+
+    /**
+     * Last money delta shown to the player.
+     */
+    public money_delta: i16;
+
+    /**
+     * Native item id vector containing selected buy/spawn item ids.
+     */
+    public pItemList: game_player_item_list;
+
+    /**
+     * Money difference from the last buy transaction.
+     */
+    public LastBuyAcount: i32;
+
+    /**
+     * Create an empty player state.
+     */
+    public constructor();
+
+    /**
+     * Check whether a player flag bit is set.
+     *
+     * @param flag - `GAME_PLAYER_FLAG_*` bit to test.
+     * @returns Whether the bit is set.
+     */
+    public testFlag(flag: u16): boolean;
+
+    /**
+     * Set a player flag bit.
+     *
+     * @param flag - `GAME_PLAYER_FLAG_*` bit to set.
+     */
+    public setFlag(flag: u16): void;
+
+    /**
+     * Clear a player flag bit.
+     *
+     * @param flag - `GAME_PLAYER_FLAG_*` bit to clear.
+     */
+    public resetFlag(flag: u16): void;
+
+    /**
+     * @returns Current multiplayer player name.
+     */
+    public getName(): string;
+
+    /**
+     * Set multiplayer player name.
+     *
+     * @param name - New player name.
+     */
+    public setName(name: string): void;
+
+    /**
+     * Reset this state to default values.
+     */
+    public clear(): void;
+
+    /**
+     * Write this state to a network packet.
+     *
+     * @param packet - Target network packet.
+     * @param full - Whether to include account data in the packet.
+     */
+    public net_Export(packet: net_packet, full?: boolean): void;
+
+    /**
+     * Read this state from a network packet.
+     *
+     * @param packet - Source network packet.
+     */
+    public net_Import(packet: net_packet): void;
+  }
 }
 
 declare module "xray16" {
@@ -11829,339 +12381,318 @@ declare module "xray16" {
   }
 
   /**
-   * Helper for building editor property rows for spawned objects.
+   * Native editor property item collection.
    *
-   * @source C++ class properties_list_helper
-   * @customConstructor properties_list_helper
+   * @source C++ class PropItemVec
+   * @customConstructor prop_item_vec
    * @group xr_properties
-   *
-   * @remarks
-   * This is an editor bridge. Most methods require a real editor property item list and a server object that owns
-   * the wrapped field; they are not useful in ordinary gameplay scripts.
    */
-  export class properties_list_helper extends EngineBinding {
-    /**
-     * Create a 3-axis angle property.
-     *
-     * @remarks
-     * Bound object field must be an `Fvector`.
-     *
-     * @returns Engine property value handle.
-     */
-    public create_vangle(): unknown;
-
-    /**
-     * Create an angle property.
-     *
-     * @remarks
-     * Bound object field must be a float.
-     *
-     * @returns Engine property value handle.
-     */
-    public create_angle(): unknown;
-
-    /**
-     * Create a time property.
-     *
-     * @remarks
-     * Bound object field must be a float.
-     *
-     * @returns Engine property value handle.
-     */
-    public create_time(): unknown;
-
-    /**
-     * Create a color property.
-     *
-     * @remarks
-     * Bound object field must be a 32-bit color value.
-     *
-     * @returns Engine property value handle.
-     */
-    public create_color(): unknown;
-
-    /**
-     * Create a vector color property.
-     *
-     * @remarks
-     * Bound object field must be an `Fvector`.
-     *
-     * @returns Engine property value handle.
-     */
-    public create_vcolor(): unknown;
-
-    /**
-     * Create a float color property.
-     *
-     * @remarks
-     * Bound object field must be an `Fcolor`.
-     *
-     * @returns Engine property value handle.
-     */
-    public create_fcolor(): unknown;
-
-    /**
-     * Create a runtime token list property.
-     *
-     * @remarks
-     * Requires an `rtoken_list`; keep it alive while the editor property uses it.
-     *
-     * @returns Engine property value handle.
-     */
-    public create_list(): unknown;
-
-    /**
-     * Create an 8-bit token property.
-     *
-     * @remarks
-     * Requires a `token_list`; ids must fit into an unsigned 8-bit value.
-     *
-     * @returns Engine property value handle.
-     */
-    public create_token8(): unknown;
-
-    /**
-     * Create a 16-bit token property.
-     *
-     * @remarks
-     * Requires a `token_list`; ids must fit into an unsigned 16-bit value.
-     *
-     * @returns Engine property value handle.
-     */
-    public create_token16(): unknown;
-
-    /**
-     * Create a 32-bit token property.
-     *
-     * @remarks
-     * Requires a `token_list`; ids are stored as unsigned 32-bit values.
-     *
-     * @returns Engine property value handle.
-     */
-    public create_token32(): unknown;
-
-    /**
-     * Create an 8-bit flag property.
-     *
-     * @remarks
-     * Binds individual bit toggles to an unsigned 8-bit integer field.
-     *
-     * @returns Engine property value handle.
-     */
-    public create_flag8(): unknown;
-
-    /**
-     * Create a 16-bit flag property.
-     *
-     * @remarks
-     * Binds individual bit toggles to an unsigned 16-bit integer field.
-     *
-     * @returns Engine property value handle.
-     */
-    public create_flag16(): unknown;
-
+  export class prop_item_vec {
     /**
-     * Create a 32-bit flag property.
-     *
-     * @remarks
-     * Binds individual bit toggles to an unsigned 32-bit integer field.
-     *
-     * @returns Engine property value handle.
-     */
-    public create_flag32(): unknown;
-
-    /**
-     * Create a vector property.
-     *
-     * @remarks
-     * Bound object field must be an `Fvector`.
-     *
-     * @returns Engine property value handle.
+     * Engine-created property item vector.
      */
-    public create_vector(): unknown;
-
-    /**
-     * Create a boolean property bound to an object field.
-     *
-     * @remarks
-     * The native helper wraps `value[id]` and attaches the wrapper to `object`, so `object` must be a server object.
-     *
-     * @param items - Property item list to append to.
-     * @param path - Property path or caption.
-     * @param object - Spawn object owning the property.
-     * @param value - Property storage descriptor.
-     * @param id - Field identifier used by the editor bridge.
-     * @returns Whether the property was created.
-     */
-    public create_bool(
-      items: LuaTable<number>,
-      path: string,
-      object: cse_abstract,
-      value: unknown,
-      id: number | string
-    ): boolean;
-
-    /**
-     * Create a float property.
-     *
-     * @remarks
-     * Bound object field must be a float. Native overloads may also carry min/max/default editor values.
-     *
-     * @returns Engine property value handle.
+    private constructor();
+  }
+
+  /**
+   * Editor asset chooser mode constants.
+   *
+   * @source `src/xrServerEntities/script_properties_list_helper_script.cpp`, `choose_type` binding.
+   * @customConstructor choose_type
+   * @group xr_properties
+   */
+  export class choose_type {
+    public static readonly custom: u32;
+    public static readonly sound_source: u32;
+    public static readonly sound_environment: u32;
+    public static readonly library_object: u32;
+    public static readonly engine_shader: u32;
+    public static readonly compiler_shader: u32;
+    public static readonly particle_effect: u32;
+    public static readonly particle_system: u32;
+    public static readonly texture: u32;
+    public static readonly entity: u32;
+    public static readonly spawn_item: u32;
+    public static readonly light_animation: u32;
+    public static readonly visual: u32;
+    public static readonly skeleton_animations: u32;
+    public static readonly skeleton_bones: u32;
+    public static readonly material: u32;
+    public static readonly game_animation: u32;
+    public static readonly game_motion: u32;
+
+    /**
+     * Engine-owned chooser constants.
      */
-    public create_float(): unknown;
+    private constructor();
+  }
 
+  /**
+   * Editor asset chooser mode value.
+   *
+   * @group xr_properties
+   */
+  export type TXR_choose_type = EnumeratedStaticsValues<typeof choose_type>;
+
+  /** @group xr_properties */
+  export class caption_value extends prop_value {}
+  /** @group xr_properties */
+  export class canvas_value extends prop_value {}
+  /** @group xr_properties */
+  export class button_value extends prop_value {}
+  /** @group xr_properties */
+  export class text_value extends prop_value {}
+  /** @group xr_properties */
+  export class choose_value extends text_value {}
+  /** @group xr_properties */
+  export class bool_value extends prop_value {}
+  /** @group xr_properties */
+  export class vector_value extends prop_value {}
+  /** @group xr_properties */
+  export class color_value extends prop_value {}
+  /** @group xr_properties */
+  export class float_value extends prop_value {}
+  /** @group xr_properties */
+  export class s8_value extends prop_value {}
+  /** @group xr_properties */
+  export class s16_value extends prop_value {}
+  /** @group xr_properties */
+  export class s32_value extends prop_value {}
+  /** @group xr_properties */
+  export class u8_value extends prop_value {}
+  /** @group xr_properties */
+  export class u16_value extends prop_value {}
+  /** @group xr_properties */
+  export class u32_value extends prop_value {}
+  /** @group xr_properties */
+  export class flag8_value extends prop_value {}
+  /** @group xr_properties */
+  export class flag16_value extends prop_value {}
+  /** @group xr_properties */
+  export class flag32_value extends prop_value {}
+  /** @group xr_properties */
+  export class token8_value extends prop_value {}
+  /** @group xr_properties */
+  export class token16_value extends prop_value {}
+  /** @group xr_properties */
+  export class token32_value extends prop_value {}
+  /** @group xr_properties */
+  export class list_value extends text_value {}
+  /**
+   * Helper for building editor property rows for spawned objects.
+   *
+   * @source C++ class properties_list_helper
+   * @customConstructor properties_list_helper
+   * @group xr_properties
+   *
+   * @remarks
+   * This is an editor bridge. Most methods require a real editor property item list and a server object that owns
+   * the wrapped field; they are not useful in ordinary gameplay scripts.
+   */
+  export class properties_list_helper extends EngineBinding {
     /**
-     * Create an unsigned 8-bit integer property.
-     *
-     * @remarks
-     * Bound object field must fit into an unsigned 8-bit value.
-     *
-     * @returns Engine property value handle.
+     * Create a 3-axis angle property bound to an `Fvector` field.
      */
-    public create_u8(): unknown;
+    public create_vangle(
+      items: prop_item_vec,
+      key: string,
+      object: object,
+      name: string,
+      min?: f32,
+      max?: f32,
+      increment?: f32,
+      decimals?: i32
+    ): vector_value;
 
     /**
-     * Create an unsigned 16-bit integer property.
-     *
-     * @remarks
-     * Bound object field must fit into an unsigned 16-bit value.
-     *
-     * @returns Engine property value handle.
+     * Create an angle property bound to a float field.
      */
-    public create_u16(): unknown;
+    public create_angle(
+      items: prop_item_vec,
+      key: string,
+      object: object,
+      name: string,
+      min?: f32,
+      max?: f32,
+      increment?: f32,
+      decimals?: i32
+    ): float_value;
 
     /**
-     * Create an unsigned 32-bit integer property.
-     *
-     * @remarks
-     * Bound object field must fit into an unsigned 32-bit value.
-     *
-     * @returns Engine property value handle.
+     * Create a time property bound to a float field.
      */
-    public create_u32(): unknown;
+    public create_time(
+      items: prop_item_vec,
+      key: string,
+      object: object,
+      name: string,
+      min?: f32,
+      max?: f32
+    ): float_value;
 
     /**
-     * Create a signed 32-bit integer property.
-     *
-     * @remarks
-     * Bound object field must fit into a signed 32-bit value.
-     *
-     * @returns Engine property value handle.
+     * Create a 32-bit packed color property bound to an unsigned integer field.
      */
-    public create_s32(): unknown;
+    public create_color(items: prop_item_vec, key: string, object: object, name: string): u32_value;
 
     /**
-     * Create a signed 16-bit integer property.
-     *
-     * @remarks
-     * Bound object field must fit into a signed 16-bit value.
-     *
-     * @returns Engine property value handle.
+     * Create a vector color property bound to an `Fvector` field.
      */
-    public create_s16(): unknown;
+    public create_vcolor(items: prop_item_vec, key: string, object: object, name: string): vector_value;
 
     /**
-     * Create an asset/object chooser property.
-     *
-     * @remarks
-     * Requires a chooser mode and a string-like field that receives the selected section, asset, or path.
-     *
-     * @returns Engine property value handle.
+     * Create a float color property bound to an `Fcolor` field.
      */
-    public create_choose(): unknown;
+    public create_fcolor(items: prop_item_vec, key: string, object: object, name: string): color_value;
 
     /**
-     * Create a button property.
-     *
-     * @remarks
-     * Editor-only command row. Use it to expose an action callback, not persistent object data.
-     *
-     * @returns Engine property value handle.
+     * Create a runtime token list property bound to a string field.
      */
-    public create_button(): unknown;
+    public create_list(items: prop_item_vec, key: string, object: object, name: string, tokens: rtoken_list): list_value;
 
     /**
-     * Create a custom canvas property.
-     *
-     * @remarks
-     * Editor-only drawing surface for custom property UI.
-     *
-     * @returns Engine property value handle.
+     * Create token properties bound to integer fields.
      */
-    public create_canvas(): unknown;
+    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 a read-only caption row.
-     *
-     * @remarks
-     * Editor-only label row used to group or explain nearby properties.
-     *
-     * @returns Engine property value handle.
+     * Create flag properties bound to integer flag fields.
      */
-    public create_caption(): unknown;
+    public create_flag8(
+      items: prop_item_vec,
+      key: string,
+      object: object,
+      name: string,
+      mask: u8,
+      offCaption?: string,
+      onCaption?: string,
+      flags?: u32
+    ): flag8_value;
+    public create_flag16(
+      items: prop_item_vec,
+      key: string,
+      object: object,
+      name: string,
+      mask: u16,
+      offCaption?: string,
+      onCaption?: string,
+      flags?: u32
+    ): flag16_value;
+    public create_flag32(
+      items: prop_item_vec,
+      key: string,
+      object: object,
+      name: string,
+      mask: u32,
+      offCaption?: string,
+      onCaption?: string,
+      flags?: u32
+    ): flag32_value;
 
     /**
-     * Callback used after editing a float property.
-     *
-     * @remarks
-     * Editor bridge callback. Native code passes the edited value through an output argument.
-     *
-     * @returns Engine callback result.
+     * Create a vector property bound to an `Fvector` field.
      */
-    public float_on_after_edit(): unknown;
+    public create_vector(
+      items: prop_item_vec,
+      key: string,
+      object: object,
+      name: string,
+      min?: f32,
+      max?: f32,
+      increment?: f32,
+      decimals?: i32
+    ): vector_value;
 
     /**
-     * Callback used before editing a float property.
-     *
-     * @remarks
-     * Editor bridge callback. Native code passes the current value through an output argument.
-     *
-     * @returns Engine callback result.
+     * Create a boolean property bound to `table[name]` and owned by `object`.
      */
-    public float_on_before_edit(): unknown;
+    public create_bool(items: prop_item_vec, key: string, object: object, table: object, name: string): bool_value;
 
     /**
-     * Callback used after editing an object name.
-     *
-     * @remarks
-     * Editor bridge callback. Native code passes the edited name through an output argument.
-     *
-     * @returns Engine callback result.
+     * Create numeric properties bound to object fields.
      */
-    public name_after_edit(): unknown;
+    public create_float(
+      items: prop_item_vec,
+      key: string,
+      object: object,
+      name: string,
+      min?: f32,
+      max?: f32,
+      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_u16(
+      items: prop_item_vec,
+      key: string,
+      object: object,
+      name: string,
+      min?: u16,
+      max?: u16,
+      increment?: u16
+    ): u16_value;
+    public create_u32(
+      items: prop_item_vec,
+      key: string,
+      object: object,
+      name: string,
+      min?: u32,
+      max?: u32,
+      increment?: u32
+    ): u32_value;
+    public create_s32(
+      items: prop_item_vec,
+      key: string,
+      object: object,
+      name: string,
+      min?: i32,
+      max?: i32,
+      increment?: i32
+    ): s32_value;
+    public create_s16(
+      items: prop_item_vec,
+      key: string,
+      object: object,
+      name: string,
+      min?: i16,
+      max?: i16,
+      increment?: i16
+    ): s16_value;
 
     /**
-     * Callback used before editing an object name.
-     *
-     * @remarks
-     * Editor bridge callback. Native code passes the current name through an output argument.
-     *
-     * @returns Engine callback result.
+     * Create an asset/object chooser property bound to a string field.
      */
-    public name_before_edit(): unknown;
+    public create_choose(
+      items: prop_item_vec,
+      key: string,
+      object: object,
+      name: string,
+      mode: TXR_choose_type,
+      path?: string,
+      fillParam?: string,
+      subItemCount?: u32
+    ): choose_value;
 
     /**
-     * Callback used before editing a vector property.
-     *
-     * @remarks
-     * Editor bridge callback for vector rows, usually used to prepare a value before the editor opens.
-     *
-     * @returns Engine callback result.
+     * Create editor-only utility rows.
      */
-    public vector_on_before_edit(): unknown;
+    public create_button(items: prop_item_vec, key: string, value: string, flags: u32): button_value;
+    public create_canvas(items: prop_item_vec, key: string, value: string, height: i32): canvas_value;
+    public create_caption(items: prop_item_vec, key: string, value: string): caption_value;
+    public create_text(items: prop_item_vec, key: string, object: object, name: string): text_value;
 
     /**
-     * Callback used after editing a vector property.
-     *
-     * @remarks
-     * Editor bridge callback for vector rows, usually used to accept or normalize the edited value.
-     *
-     * @returns Engine callback result.
+     * Standard editor callbacks used by property rows with luabind out-parameters.
      */
-    public vector_on_after_edit(): unknown;
+    public float_on_after_edit(sender: prop_value, value: f32): LuaMultiReturn<[boolean, f32]>;
+    public float_on_before_edit(sender: prop_value, value: f32): f32;
+    public name_after_edit(sender: prop_value, value: string): LuaMultiReturn<[boolean, string]>;
+    public name_before_edit(sender: prop_value, value: string): string;
+    public vector_on_before_edit(sender: prop_value, value: vector): vector;
+    public vector_on_after_edit(sender: prop_value, value: vector): boolean;
   }
-
   /**
    * Global editor properties helper.
    *
@@ -12195,7 +12726,7 @@ declare module "xray16" {
      *
      * @returns Engine property value handle.
      */
-    public token16_value(): unknown;
+    public token16_value(): token16_value;
 
     /**
      * Treat this property value as a 32-bit flag value.
@@ -12205,7 +12736,7 @@ declare module "xray16" {
      *
      * @returns Engine property value handle.
      */
-    public flag32_value(): unknown;
+    public flag32_value(): flag32_value;
 
     /**
      * Treat this property value as text.
@@ -12215,7 +12746,7 @@ declare module "xray16" {
      *
      * @returns Engine property value handle.
      */
-    public text_value(): unknown;
+    public text_value(): text_value;
 
     /**
      * Treat this property value as a boolean.
@@ -12225,7 +12756,7 @@ declare module "xray16" {
      *
      * @returns Engine property value handle.
      */
-    public bool_value(): unknown;
+    public bool_value(): bool_value;
 
     /**
      * Treat this property value as an unsigned 16-bit integer.
@@ -12235,7 +12766,7 @@ declare module "xray16" {
      *
      * @returns Engine property value handle.
      */
-    public u16_value(): unknown;
+    public u16_value(): u16_value;
 
     /**
      * Treat this property value as a signed 16-bit integer.
@@ -12245,7 +12776,7 @@ declare module "xray16" {
      *
      * @returns Engine property value handle.
      */
-    public s16_value(): unknown;
+    public s16_value(): s16_value;
 
     /**
      * Treat this property value as a button.
@@ -12255,7 +12786,7 @@ declare module "xray16" {
      *
      * @returns Engine property value handle.
      */
-    public button_value(): unknown;
+    public button_value(): button_value;
 
     /**
      * Treat this property value as a caption.
@@ -12265,7 +12796,7 @@ declare module "xray16" {
      *
      * @returns Engine property value handle.
      */
-    public caption_value(): unknown;
+    public caption_value(): caption_value;
   }
 
   /**
@@ -12513,19 +13044,29 @@ declare module "xray16" {
   export const relation_registry: IXR_relation_registry;
 
   /**
-   * Enumeration of relations.
+   * Relation type names exposed through the `game_object.relation` Lua enum.
    *
-   * ERelationTypeFriend - 0
-   * eRelationTypeNeutral - 1
-   * eRelationTypeEnemy - 2
-   * eRelationTypeWorstEnemy - 3
-   * eRelationTypeLast - 4
-   * eRelationTypeDummy - -1.
+   * @source `src/xrGame/script_game_object_script2.cpp`, `game_object.relation` enum.
+   * @group xr_relation
+   */
+  export type TXR_relation_name = "friend" | "neutral" | "enemy" | "dummy";
+
+  /**
+   * Relation type returned by `game_object.relation()` and accepted by `game_object.set_relation()`.
    *
+   * @source C++ enum ALife::ERelationType
    * @group xr_relation
+   *
+   * @remarks
+   * `game_object.relation()` returns `game_object.dummy` when either object cannot be treated as a living entity.
+   * `3` is the native `eRelationTypeWorstEnemy` value; it is not exported as a named Lua enum member.
    */
-  export type TXR_relation = 0 | 1 | 2 | 3;
-}
+  export type TXR_relation =
+    | typeof game_object.dummy
+    | typeof game_object.friend
+    | typeof game_object.neutral
+    | typeof game_object.enemy
+    | 3;}
 
 declare module "xray16" {
   /**
@@ -14145,14 +14686,36 @@ declare module "xray16" {
   /**
    * @group xr_task
    */
-  export type TXR_TaskStateName = EnumeratedStaticsKeys<typeof task>;
+  export type TXR_TaskStateName = "fail" | "in_progress" | "completed" | "task_dummy";
 
   /**
    * ETaskState.
    *
    * @group xr_task
    */
-  export type TXR_TaskState = EnumeratedStaticsValues<typeof task>;
+  export type TXR_TaskState =
+    | typeof task.fail
+    | typeof task.in_progress
+    | typeof task.completed
+    | typeof task.task_dummy;
+
+  /**
+   * ETaskType constant names.
+   *
+   * @group xr_task
+   */
+  export type TXR_TaskTypeName = "storyline" | "additional" | "insignificant" | "task_dummy";
+
+  /**
+   * ETaskType.
+   *
+   * @group xr_task
+   */
+  export type TXR_TaskType =
+    | typeof task.storyline
+    | typeof task.additional
+    | typeof task.insignificant
+    | typeof task.task_dummy;
 
   /**
    * One objective inside a game task.
@@ -14326,14 +14889,14 @@ declare module "xray16" {
     /**
      * @returns Task type, such as `task.storyline` or `task.additional`.
      */
-    public get_type(): number; /* ETaskType */
+    public get_type(): TXR_TaskType;
 
     /**
      * Set task type.
      *
      * @param type - Task type, such as `task.storyline` or `task.additional`.
      */
-    public set_type(type: i32 /* ETaskType */): void;
+    public set_type(type: TXR_TaskType): void;
 
     /**
      * Set hint text for the linked map location.
@@ -16184,6 +16747,47 @@ declare module "xray16" {
    */
   export type TXR_CCar_weapon_param = EnumeratedStaticsValues<typeof CCar>;
 
+  /**
+   * Helicopter life-state values returned by `CHelicopter.GetState()`.
+   *
+   * @source `src/xrGame/helicopter_script.cpp`, `CHelicopter.state` enum.
+   * @group xr_level
+   */
+  export type TXR_helicopter_state = typeof CHelicopter.eAlive | typeof CHelicopter.eDead | -1;
+
+  /**
+   * Helicopter movement-state values returned by `CHelicopter.GetMovementState()`.
+   *
+   * @source `src/xrGame/helicopter_script.cpp`, `CHelicopter.movement_state` enum.
+   * @group xr_level
+   */
+  export type TXR_helicopter_movement_state =
+    | typeof CHelicopter.eMovNone
+    | typeof CHelicopter.eMovToPoint
+    | typeof CHelicopter.eMovPatrolPath
+    | typeof CHelicopter.eMovRoundPath
+    | typeof CHelicopter.eMovLanding
+    | typeof CHelicopter.eMovTakeOff;
+
+  /**
+   * Helicopter body-state values returned by `CHelicopter.GetBodyState()`.
+   *
+   * @source `src/xrGame/helicopter_script.cpp`, `CHelicopter.body_state` enum.
+   * @group xr_level
+   */
+  export type TXR_helicopter_body_state = typeof CHelicopter.eBodyByPath | typeof CHelicopter.eBodyToPoint;
+
+  /**
+   * Helicopter enemy-tracking values returned by `CHelicopter.GetHuntState()`.
+   *
+   * @source `src/xrGame/helicopter_script.cpp`, `CHelicopter.hunt_state` enum.
+   * @group xr_level
+   */
+  export type TXR_helicopter_hunt_state =
+    | typeof CHelicopter.eEnemyNone
+    | typeof CHelicopter.eEnemyPoint
+    | typeof CHelicopter.eEnemyEntity;
+
   /**
    * Script-controlled helicopter object.
    *
@@ -16363,12 +16967,12 @@ declare module "xray16" {
     /**
      * @returns Current movement state.
      */
-    public GetMovementState(): i32; /* Enum ? */
+    public GetMovementState(): TXR_helicopter_movement_state;
 
     /**
      * @returns Current body aiming state.
      */
-    public GetBodyState(): i32; /* Enum ? */
+    public GetBodyState(): TXR_helicopter_body_state;
 
     /**
      * @returns Current velocity vector.
@@ -16378,7 +16982,7 @@ declare module "xray16" {
     /**
      * @returns Alive/dead state.
      */
-    public GetState(): i32;
+    public GetState(): TXR_helicopter_state;
 
     /**
      * @returns Distance to destination position.
@@ -16388,14 +16992,14 @@ declare module "xray16" {
     /**
      * @returns Current enemy tracking state.
      */
-    public GetHuntState(): i32; /* Enum ? */
+    public GetHuntState(): TXR_helicopter_hunt_state;
 
     /**
      * Set desired speed near the destination point.
      *
      * @param value - Speed value.
      */
-    public SetSpeedInDestPoint(value: f32): unknown;
+    public SetSpeedInDestPoint(value: f32): void;
 
     /**
      * Set linear acceleration limits.
@@ -17065,6 +17669,36 @@ declare module "xray16" {
     public unblock_breaking(): void;
   }
 
+  /**
+   * Opaque native physics condition handle.
+   *
+   * @source C++ class CPHCondition
+   * @customConstructor CPHCondition
+   * @group xr_physic
+   *
+   * @remarks
+   * Script-friendly condition callbacks are exposed through `level.add_call`; this handle models native physics world
+   * calls that already have a C++ condition object.
+   */
+  export class CPHCondition {
+    private constructor();
+  }
+
+  /**
+   * Opaque native physics action handle.
+   *
+   * @source C++ class CPHAction
+   * @customConstructor CPHAction
+   * @group xr_physic
+   *
+   * @remarks
+   * Script-friendly action callbacks are exposed through `level.add_call`; this handle models native physics world calls
+   * that already have a C++ action object.
+   */
+  export class CPHAction {
+    private constructor();
+  }
+
   /**
    * Global physics world controls.
    *
@@ -17092,9 +17726,13 @@ declare module "xray16" {
      * Add a physics condition/action callback pair.
      *
      * @remarks
-     * This binding expects native `CPHCondition` and `CPHAction` objects; ordinary scripts rarely call it directly.
+     * This binding expects native `CPHCondition` and `CPHAction` objects; ordinary scripts usually use
+     * `level.add_call` instead.
+     *
+     * @param condition - Native physics condition object.
+     * @param action - Native physics action object.
      */
-    public add_call(/* Class CPHCondition*, class CPHAction */): void;
+    public add_call(condition: CPHCondition, action: CPHAction): void;
   }
 
   /**
@@ -17345,10 +17983,37 @@ declare module "xray16" {
   export type TXR_bloodsucker_visibility_state = -1 | 0 | 1 | 2;
 
   /**
-   * @source C++ enum visibility_t
+   * @source `src/xrGame/script_game_object_script2.cpp`, `game_object.EPathType` enum.
+   * @group xr_script_interface
+   */
+  export type TXR_game_object_path =
+    | typeof game_object.game_path
+    | typeof game_object.level_path
+    | typeof game_object.patrol_path
+    | typeof game_object.no_path;
+
+  /**
+   * Game-graph destination selection mode for stalker movement.
+   *
+   * @source `src/xrGame/script_game_object_script2.cpp`, `game_object.ESelectionType` enum.
    * @group xr_script_interface
    */
-  export type TXR_game_object_path = 0 | 1 | 2 | 3 | number;
+  export type TXR_movement_selection_type = 0 | 1;
+
+  /**
+   * Script entity action type id passed to action callbacks.
+   *
+   * @source C++ enum ScriptEntity::EActionType
+   * @group xr_script_interface
+   */
+  export type TXR_action_type =
+    | typeof game_object.movement
+    | typeof game_object.watch
+    | typeof game_object.animation
+    | typeof game_object.sound
+    | typeof game_object.particle
+    | typeof game_object.object
+    | 7;
 
   /**
    * Engine callback id registry.
@@ -17922,11 +18587,14 @@ declare module "xray16" {
      * @source `src/xrGame/script_entity.cpp`, `CScriptEntity::ProcessScripts`.
      *
      * @remarks
-     * The engine passes `-1` as the third argument for this callback path.
+     * The engine passes `ScriptEntity::eActionTypeMovement` as the action type and `-1` as the target point index for
+     * this callback path.
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["action_movement"],
-      cb?: Nillable<(this: void, object: game_object, movement_type: u32 /* EMovementType */, unknown: -1) => void>,
+            cb?: Nillable<
+        (this: void, object: game_object, action_type: TXR_action_type, target_point_index: -1) => void
+      >,
       object?: Nillable<T>
     ): void;
 
@@ -17937,7 +18605,7 @@ declare module "xray16" {
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["action_watch"],
-      cb?: Nillable<(this: void, object: game_object, action_type: u32) => void>,
+      cb?: Nillable<(this: void, object: game_object, action_type: TXR_action_type) => void>,
       object?: Nillable<T>
     ): void;
 
@@ -17948,7 +18616,7 @@ declare module "xray16" {
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["action_removed"],
-      cb?: Nillable<(this: void, object: game_object, action_type: u32) => void>,
+      cb?: Nillable<(this: void, object: game_object, action_type: TXR_action_type) => void>,
       object?: Nillable<T>
     ): void;
 
@@ -17959,7 +18627,7 @@ declare module "xray16" {
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["action_animation"],
-      cb?: Nillable<(this: void, object: game_object, action_type: u32) => void>,
+      cb?: Nillable<(this: void, object: game_object, action_type: TXR_action_type) => void>,
       object?: Nillable<T>
     ): void;
 
@@ -17970,7 +18638,7 @@ declare module "xray16" {
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["action_sound"],
-      cb?: Nillable<(this: void, object: game_object, action_type: u32) => void>,
+      cb?: Nillable<(this: void, object: game_object, action_type: TXR_action_type) => void>,
       object?: Nillable<T>
     ): void;
 
@@ -17981,7 +18649,7 @@ declare module "xray16" {
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["action_particle"],
-      cb?: Nillable<(this: void, object: game_object, action_type: u32) => void>,
+      cb?: Nillable<(this: void, object: game_object, action_type: TXR_action_type) => void>,
       object?: Nillable<T>
     ): void;
 
@@ -17992,7 +18660,7 @@ declare module "xray16" {
      */
     public set_callback<T extends AnyObject>(
       type: TXR_callbacks["action_object"],
-      cb?: Nillable<(this: void, object: game_object, action_type: u32) => void>,
+      cb?: Nillable<(this: void, object: game_object, action_type: TXR_action_type) => void>,
       object?: Nillable<T>
     ): void;
 
@@ -18622,8 +19290,15 @@ declare module "xray16" {
     /**
      * Get inventory object by index or name.
      *
+     * @source `src/xrGame/script_game_object_script2.cpp`, `object` bindings.
+     *
+     * @remarks
+     * Requires this object to be a `CInventoryOwner`. Numeric lookup uses the engine inventory index, not a runtime
+     * object id. String lookup searches inventory item names. Both overloads return `null` when the item is missing or
+     * the inventory entry cannot be cast back to a game object.
+     *
      * @param value - Inventory index or item name.
-     * @returns Matching item, or `null` when it does not exist.
+     * @returns Matching inventory item, or `null`.
      */
     public object(value: i32 | string): Nullable<game_object>;
 
@@ -18693,22 +19368,25 @@ declare module "xray16" {
     /**
      * Get active detector item.
      *
+     * @source `src/xrGame/script_game_object_inventory_owner.cpp`, `CScriptGameObject::active_detector`.
+     *
      * @remarks
-     * Requires this object to be a `CInventoryOwner`. Other object types log a script error and return
-     * a default value or do nothing.
+     * Requires this object to be a `CInventoryOwner`. The binding reads the detector slot and returns the detector only
+     * while it is working. Missing inventory owner, empty detector slot, or inactive detector returns `null`.
      *
-     * @returns Active detector, or `null`.
+     * @returns Working detector item, or `null`.
      */
     public active_detector(): Nullable<game_object>;
 
     /**
      * Get active inventory item.
      *
+     * @source `src/xrGame/script_game_object3.cpp`, `CScriptGameObject::GetActiveItem`.
+     *
      * @remarks
-     * Requires this object to be a `CInventoryOwner`. Other object types log a script error and return
-     * a default value or do nothing.
+     * Requires this object to be a `CInventoryOwner`. Other object types log a script error and return `null`.
      *
-     * @returns Active item, or `null`.
+     * @returns Active inventory item, or `null` when no item is active.
      */
     public active_item(): Nullable<game_object>;
 
@@ -18762,24 +19440,29 @@ declare module "xray16" {
     public base_out_restrictions(): string;
 
     /**
-     * Get best known item for this object.
+     * Get best remembered item for this object.
+     *
+     * @source `src/xrGame/script_game_object2.cpp`, `CScriptGameObject::GetBestItem`.
      *
      * @remarks
-     * Requires this object to be a `CInventoryOwner`. Other object types log a script error and return
-     * a default value or do nothing.
+     * Requires this object to be a `CCustomMonster`. This is the selected item from monster memory, not the best item in
+     * the object's inventory. Non-monster objects or monsters without a selected item return `null`.
      *
-     * @returns Best item, or `null`.
+     * @returns Best remembered item, or `null`.
      */
     public best_item(): Nullable<game_object>;
 
     /**
      * Get best available weapon for this object.
      *
+     * @source `src/xrGame/script_game_object2.cpp`, `CScriptGameObject::best_weapon`.
+     *
      * @remarks
-     * Requires this object to be a `CInventoryOwner`. Other object types log a script error and return
-     * a default value or do nothing.
+     * Requires this object to be a `CAI_Stalker`. The binding reads the stalker object handler's best weapon candidate
+     * and returns it only when the item still belongs to this object. Non-stalker objects, missing candidates, and
+     * candidates owned by another object return `null`.
      *
-     * @returns Best weapon, or `null`.
+     * @returns Best weapon candidate, or `null`.
      */
     public best_weapon(): Nullable<game_object>;
 
@@ -19215,15 +19898,17 @@ declare module "xray16" {
     public max_ignore_monster_distance(value: f32): void;
 
     /**
-     * Get objects that recently hit this object.
+     * Iterate native hit-memory records for this monster.
+     *
+     * @source `src/xrGame/script_game_object_script3.cpp`, `memory_hit_objects` binding with `return_stl_iterator()`.
      *
      * @remarks
-     * Requires this object to be a `CCustomMonster` or one of its subclasses. Items, actors, and other
-     * objects log a script error and return a default value or do nothing.
+     * Requires this object to be a `CCustomMonster` or one of its subclasses. The binding returns a Lua iterator over
+     * the native `xr_vector<MemorySpace::CHitObject>` collection.
      *
-     * @returns Engine hit-memory collection.
+     * @returns Iterable hit-memory records.
      */
-    public memory_hit_objects(): unknown; // :vector<MemorySpace::CHitObject, xalloc<struct MemorySpace::CHitObject>
+    public memory_hit_objects(): LuaIterable<hit_memory_object>;
 
     /**
      * Get time since this object remembered another object.
@@ -19251,20 +19936,29 @@ declare module "xray16" {
     /**
      * Get current stalker mental state.
      *
-     * @returns Mental state id.
+     * @source `src/xrGame/script_game_object3.cpp`, `CScriptGameObject::mental_state`.
+     *
+     * @remarks
+     * Requires this object to be a `CAI_Stalker`. Non-stalker objects log an engine script error and return
+     * `anim.danger`.
+     *
+     * @returns Current mental state.
      */
-    public mental_state<T extends number>(): T; // Todo: unknown enum
+    public mental_state(): TXR_mental_state;
 
     /**
-     * Get objects that are being detected but are not visible yet.
+     * Iterate visual-memory candidates that are being detected but are not visible yet.
+     *
+     * @source `src/xrGame/script_game_object_script3.cpp`, `not_yet_visible_objects` binding with
+     * `return_stl_iterator()`.
      *
      * @remarks
-     * Requires this object to be a `CCustomMonster` or one of its subclasses. Items, actors, and other
-     * objects log a script error and return a default value or do nothing.
+     * Requires this object to be a `CCustomMonster` or one of its subclasses. The binding returns a Lua iterator over
+     * the native visual memory manager collection. Use `memory_visible_objects()` for fully visible remembered objects.
      *
-     * @returns Engine not-yet-visible collection.
+     * @returns Iterable pending-visibility records.
      */
-    public not_yet_visible_objects(): unknown;
+    public not_yet_visible_objects(): LuaIterable<not_yet_visible_object>;
 
     /**
      * Get inventory object count.
@@ -19431,7 +20125,7 @@ declare module "xray16" {
      *
      * @param state - Target mental state.
      */
-    public set_mental_state(state: TXR_animation): void;
+    public set_mental_state(state: TXR_mental_state): void;
 
     /**
      * Force an override animation.
@@ -19757,7 +20451,7 @@ declare module "xray16" {
      *
      * @returns Current stalker body state.
      */
-    public body_state(): TXR_MonsterBodyState;
+    public body_state(): TXR_body_state;
 
     /**
      * Get model bone world position.
@@ -20058,9 +20752,12 @@ declare module "xray16" {
     public get_campfire(): CZoneCampfire;
 
     /**
+     * Get currently equipped outfit.
+     *
+     * @source `src/xrGame/script_game_object3.cpp`, `CScriptGameObject::GetCurrentOutfit`.
+     *
      * @remarks
-     * Requires this object to be a `CInventoryOwner`. Other object types log a script error and return
-     * a default value or do nothing.
+     * Requires this object to be a `CInventoryOwner`. Other object types log a script error and return `null`.
      *
      * @returns Currently equipped outfit, or `null` when none is equipped.
      */
@@ -20320,15 +21017,17 @@ declare module "xray16" {
     public marked_dropped(object: game_object): boolean;
 
     /**
-     * Get sound memory records.
+     * Iterate sound-memory records for this monster.
+     *
+     * @source `src/xrGame/script_game_object_script3.cpp`, `memory_sound_objects` binding with `return_stl_iterator()`.
      *
      * @remarks
-     * Requires this object to be a `CCustomMonster` or one of its subclasses. Items, actors, and other
-     * objects log a script error and return a default value or do nothing.
+     * Requires this object to be a `CCustomMonster` or one of its subclasses. The binding returns a Lua iterator over
+     * the native `xr_vector<MemorySpace::CSoundObject>` collection.
      *
-     * @returns Engine sound-memory collection.
+     * @returns Iterable sound-memory records.
      */
-    public memory_sound_objects(): unknown;
+    public memory_sound_objects(): LuaIterable<sound_memory_object>;
 
     /**
      * @remarks
@@ -20349,13 +21048,17 @@ declare module "xray16" {
     public motivation_action_manager(): action_planner;
 
     /**
+     * Get current stalker movement type.
+     *
+     * @source `src/xrGame/script_game_object3.cpp`, `CScriptGameObject::movement_type`.
+     *
      * @remarks
-     * Requires this object to be a `CAI_Stalker`. Other object types log a script error and return a
-     * default value or do nothing.
+     * Requires this object to be a `CAI_Stalker`. Non-stalker objects log an engine script error and return
+     * `move.stand`.
      *
-     * @returns Current movement type id.
+     * @returns Current movement type.
      */
-    public movement_type(): number; // Todo: unknown enum
+    public movement_type(): TXR_movement_type;
 
     /**
      * @remarks
@@ -20568,7 +21271,7 @@ declare module "xray16" {
      *
      * @param state - Body state.
      */
-    public set_body_state(state: TXR_MonsterBodyState): void;
+    public set_body_state(state: TXR_body_state): void;
 
     /**
      * Configure bloodsucker capture animation jump.
@@ -20666,9 +21369,9 @@ declare module "xray16" {
      * Requires this object to be a `CAI_Stalker`. Other object types log a script error and return a
      * default value or do nothing.
      *
-     * @param EDetailPathType - Detail path type id.
+     * @param type - Detail path type id.
      */
-    public set_detail_path_type(EDetailPathType: unknown /* Enum DetailPathManager::EDetailPathType */): void;
+    public set_detail_path_type(type: TXR_detail_path_type): void;
 
     /**
      * Force bloodsucker invisibility state.
@@ -20684,13 +21387,15 @@ declare module "xray16" {
     /**
      * Set movement target selection type.
      *
+     * @source `src/xrGame/script_game_object3.cpp`, `CScriptGameObject::set_movement_selection_type`.
+     *
      * @remarks
-     * Requires an AI object using movement path selection. Invalid enum values can trip native assertions or leave the
-     * path builder in an unusable state.
+     * Requires this object to be a `CAI_Stalker`. The native wrapper logs an error for non-stalker objects but then
+     * still dereferences the missing stalker pointer, so this should only be called after the runtime type is known.
      *
      * @param type - Selection type id.
      */
-    public set_movement_selection_type(type: unknown /* Enum ESelectionType */): void;
+    public set_movement_selection_type(type: TXR_movement_selection_type): void;
 
     /**
      * Set movement patrol path.
@@ -20704,7 +21409,7 @@ 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: number, route_type: number, 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.
@@ -20982,7 +21687,7 @@ declare module "xray16" {
      * @param ini_file - Trade config.
      * @param section - Condition section.
      */
-    public show_condition(ini_file: unknown, section: string): void;
+    public show_condition(ini_file: ini_file, section: string): void;
 
     /**
      * @remarks
@@ -21027,43 +21732,47 @@ declare module "xray16" {
     /**
      * Register an NPC sound.
      *
+     * @source `src/xrGame/script_game_object4.cpp`, `CScriptGameObject::add_sound`.
+     *
      * @remarks
      * Requires this object to be a `CCustomMonster` or one of its subclasses. Items, actors, and other
      * objects log a script error and return a default value or do nothing.
      *
      * @param prefix - Sound prefix.
+     * @param max_count - Maximum samples in the sound collection.
+     * @param type - AI sound category.
      * @param priority - Sound priority.
-     * @param type - Sound type.
-     * @param mask - Sound mask.
-     * @param internal_type - Internal sound type.
-     * @param max_count - Maximum active sounds.
-     * @returns Registered sound id.
+     * @param mask - Sound synchronization mask.
+     * @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, priority: u32, type: unknown, mask: u32, internal_type: u32, max_count: 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.
      *
+     * @source `src/xrGame/script_game_object4.cpp`, `CScriptGameObject::add_sound`.
+     *
      * @remarks
      * Requires this object to be a `CCustomMonster` or one of its subclasses. Items, actors, and other
      * objects log a script error and return a default value or do nothing.
      *
      * @param prefix - Sound prefix.
+     * @param max_count - Maximum samples in the sound collection.
+     * @param type - AI sound category.
      * @param priority - Sound priority.
-     * @param type - Sound type.
-     * @param mask - Sound mask.
-     * @param internal_type - Internal sound type.
-     * @param max_count - Maximum active sounds.
-     * @param bone - Bone name.
-     * @returns Registered sound id.
+     * @param mask - Sound synchronization mask.
+     * @param internal_type - Internal monster sound id.
+     * @param bone - Bone name used for playback placement.
+     * @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,
-      type: unknown,
       mask: u32,
       internal_type: u32,
-      max_count: u32,
       bone: string
     ): u32;
 
@@ -21248,9 +21957,18 @@ declare module "xray16" {
     public deadbody_can_take_status(): boolean;
 
     /**
-     * @returns Current detail path type used by the object's movement manager.
+     * Get current detail path type used by the object's movement manager.
+     *
+     * @source `src/xrGame/script_game_object3.cpp`, `CScriptGameObject::detail_path_type`.
+     *
+     * @remarks
+     * Requires this object to be a `CAI_Stalker`. Non-stalker objects log an engine script error and return
+     * `move.line`. In the verified xray source, the wrapper also returns `move.line` for stalkers instead of reading
+     * the current movement manager value.
+     *
+     * @returns Detail path type id.
      */
-    public detail_path_type(): unknown;
+    public detail_path_type(): TXR_detail_path_type;
 
     /**
      * Enable or disable weapon show, hide and reload sounds for this inventory owner.
@@ -21383,9 +22101,13 @@ declare module "xray16" {
     public get_car(): CCar;
 
     /**
+     * Get current corpse selected by this monster.
+     *
+     * @source `src/xrGame/script_game_object3.cpp`, `CScriptGameObject::GetCorpse`.
+     *
      * @remarks
-     * Requires this object to be a monster with corpse-search logic. Other object types log a script
-     * error and return `null`.
+     * Requires this object to be a `CCustomMonster`. The binding ignores destroyed corpse objects and returns `null`
+     * when no usable corpse is selected.
      *
      * @returns Corpse selected by this monster, or `null`.
      */
@@ -21397,9 +22119,13 @@ declare module "xray16" {
     public get_current_holder(): Nullable<holder>;
 
     /**
+     * Get current enemy selected by this monster.
+     *
+     * @source `src/xrGame/script_game_object3.cpp`, `CScriptGameObject::GetEnemy`.
+     *
      * @remarks
-     * Requires this object to be a `CCustomMonster` or one of its subclasses. Items, actors, and other
-     * objects log a script error and return a default value or do nothing.
+     * Requires this object to be an alive `CCustomMonster`. The binding ignores destroyed enemy objects and returns
+     * `null` when the monster is dead, has no current enemy, or is not a monster.
      *
      * @returns Current enemy object, or `null`.
      */
@@ -21453,9 +22179,9 @@ declare module "xray16" {
      * a default value or do nothing.
      *
      * @param task_id - Task id.
-     * @returns Task state id.
+     * @returns Task state id, or `task.task_dummy` when this object is not an inventory owner or the task is missing.
      */
-    public get_task_state(task_id: string): unknown;
+    public get_task_state(task_id: string): TXR_TaskState;
 
     /**
      * Add an info portion to this object.
@@ -21681,25 +22407,28 @@ declare module "xray16" {
     /**
      * Get item in inventory slot.
      *
+     * @source `src/xrGame/script_game_object_inventory_owner.cpp`, `CScriptGameObject::item_in_slot`.
+     *
      * @remarks
-     * Requires this object to be a `CInventoryOwner`. Other object types log a script error and return
-     * a default value or do nothing.
+     * Requires this object to be a `CInventoryOwner`. Compatibility mode can shift slot ids by one for legacy
+     * minus-one slot ordering. Empty slots and non-inventory owners return `null`.
      *
-     * @param slot - Slot id.
+     * @param slot - Inventory slot id.
      * @returns Item in slot, or `null`.
      */
     public item_in_slot(slot: u32): Nullable<game_object>;
 
     /**
-     * Get item on belt by slot.
+     * Get item on belt by belt container index.
      *
      * @since OpenXRay 2015-10-07, 658f68a2
+     * @source `src/xrGame/script_game_object_inventory_owner.cpp`, `CScriptGameObject::ItemOnBelt`.
      *
      * @remarks
-     * Requires this object to be a `CInventoryOwner`. Other object types log a script error and return
-     * a default value or do nothing.
+     * Requires this object to be a `CInventoryOwner`. Empty belt cells, non-inventory owners, and invalid belt indices
+     * return `null` after logging a script error where applicable.
      *
-     * @param slot - Belt slot id.
+     * @param slot - Belt container index.
      * @returns Item on belt, or `null`.
      */
     public item_on_belt(slot: u32): Nullable<game_object>;
@@ -21777,9 +22506,17 @@ declare module "xray16" {
     public out_restrictions(): string;
 
     /**
+     * Get current movement path type.
+     *
+     * @source `src/xrGame/script_game_object3.cpp`, `CScriptGameObject::path_type`.
+     *
+     * @remarks
+     * Requires this object to be a `CAI_Stalker`. Non-stalker objects log an engine script error and return
+     * `game_object.no_path`.
+     *
      * @returns Current movement path type.
      */
-    public path_type(): unknown;
+    public path_type(): TXR_game_object_path;
 
     /**
      * @remarks
@@ -22002,7 +22739,7 @@ declare module "xray16" {
      * @param relation - Relation id.
      * @param object - Target object.
      */
-    public set_relation(relation: number, object: game_object): void;
+    public set_relation(relation: TXR_relation, object: game_object): void;
 
     /**
      * Make the smart-cover target mode fire without lookout.
@@ -22203,7 +22940,7 @@ declare module "xray16" {
      *
      * @returns Target body state requested by the movement manager.
      */
-    public target_body_state(): TXR_move;
+    public target_body_state(): TXR_body_state;
 
     /**
      * @remarks
@@ -22212,7 +22949,7 @@ declare module "xray16" {
      *
      * @returns Target movement type requested by the movement manager.
      */
-    public target_movement_type(): number; /* EMovementType */
+    public target_movement_type(): TXR_movement_type;
 
     /**
      * Transfer an item to another inventory owner.
@@ -22398,13 +23135,15 @@ declare module "xray16" {
     ): cover_point;
 
     /**
-     * Get best known enemy.
+     * Get best enemy selected by monster memory.
+     *
+     * @source `src/xrGame/script_game_object2.cpp`, `CScriptGameObject::GetBestEnemy`.
      *
      * @remarks
-     * Requires this object to be a `CCustomMonster` or one of its subclasses. Items, actors, and other
-     * objects log a script error and return a default value or do nothing.
+     * Requires this object to be a `CCustomMonster`. The binding reads the selected enemy from monster memory and
+     * returns `null` when the object is not a monster or no enemy is selected.
      *
-     * @returns Enemy object, or `null`.
+     * @returns Selected enemy object, or `null`.
      */
     public best_enemy(): Nullable<game_object>;
 
@@ -22549,26 +23288,27 @@ declare module "xray16" {
     /**
      * Register a combat sound.
      *
+     * @source `src/xrGame/script_game_object4.cpp`, `CScriptGameObject::add_combat_sound`.
+     *
      * @remarks
-     * Requires this object to be a `CCustomMonster` or one of its subclasses. Items, actors, and other
-     * objects log a script error and return a default value or do nothing.
+     * Requires this object to be a `CAI_Stalker`. Other object types log a script error and return `0`.
      *
      * @param prefix - Sound prefix.
+     * @param max_count - Maximum samples in the sound collection.
+     * @param type - AI sound category.
      * @param priority - Sound priority.
-     * @param type - Sound type.
-     * @param mask - Sound mask.
-     * @param internal_type - Internal sound type.
-     * @param max_count - Maximum active sounds.
-     * @param bone - Bone name.
-     * @returns Registered sound id.
+     * @param mask - Sound synchronization mask.
+     * @param internal_type - Internal stalker sound id.
+     * @param bone - Bone name used for playback placement.
+     * @returns Registered sound id, or `0` when this object is not a stalker.
      */
     public add_combat_sound(
       prefix: string,
-      priority: number,
-      type: i32 /* Enum ESoundTypes */,
+      max_count: u32,
+      type: TXR_snd_type,
+      priority: u32,
       mask: u32,
       internal_type: u32,
-      max_count: u32,
       bone: string
     ): u32;
 
@@ -22810,9 +23550,14 @@ declare module "xray16" {
     /**
      * Get parent object.
      *
-     * @returns Parent object.
+     * @source `src/xrGame/script_game_object_use.cpp`, `CScriptGameObject::Parent`.
+     *
+     * @remarks
+     * Returns `null` when the object has no parent game object.
+     *
+     * @returns Parent object, or `null` when no parent exists.
      */
-    public parent(): game_object;
+    public parent(): Nullable<game_object>;
 
     /**
      * Get current world position.
@@ -22896,7 +23641,7 @@ declare module "xray16" {
      *
      * @param movement_type - Movement type.
      */
-    public set_movement_type(movement_type: number /* MonsterSpace::EMovementType */): void;
+    public set_movement_type(movement_type: TXR_movement_type): void;
 
     /**
      * Move an NPC to a position.
@@ -22949,7 +23694,7 @@ declare module "xray16" {
      *
      * @returns Target mental state requested by the movement manager.
      */
-    public target_mental_state(): TXR_animation;
+    public target_mental_state(): TXR_mental_state;
 
     /**
      * Unregister this door from NPC door management.
@@ -23259,24 +24004,22 @@ declare module "xray16" {
     public get_remaining_uses(): u8;
 
     /**
-     * Set custom zone restrictor type.
+     * Set space-restrictor category.
      *
      * @remarks
-     * Requires this object to be a custom zone. Other object types log a script error and return a
-     * default value or do nothing.
+     * Requires this object to be a space restrictor. Other object types silently do nothing.
      *
      * @param type - Restrictor type.
      */
-    public set_restrictor_type(type: u8): void;
+    public set_restrictor_type(type: TXR_restrictor_type): void;
 
     /**
      * @remarks
-     * Requires this object to be a custom zone. Other object types log a script error and return a
-     * default value or do nothing.
+     * Requires this object to be a space restrictor. Other object types return `255`.
      *
-     * @returns Custom zone restrictor type.
+     * @returns Space-restrictor category, or `255` when this object is not a space restrictor.
      */
-    public get_restrictor_type(): u8;
+    public get_restrictor_type(): TXR_restrictor_type | 255;
 
     /**
      * Set spatial registration type for this object.
@@ -24457,7 +25200,7 @@ declare module "xray16" {
      * @param pref - Property prefix.
      * @param items - Property collection to populate.
      */
-    public FillProps(pref: string, items: LuaTable<number, unknown>): void;
+    public FillProps(pref: string, items: prop_item_vec): void;
   }
 
   /**
@@ -25513,16 +26256,20 @@ declare module "xray16" {
     /**
      * Replace the table of available loopholes.
      *
-     * @param object - Lua table with loophole ids.
+     * @remarks
+     * Keys are smart-cover loophole ids from the description table. A `false` value hides the matching loophole from
+     * parsed draw/usage data; missing keys leave loopholes available.
+     *
+     * @param loopholes - Lua table mapping loophole id to availability flag.
      */
-    public set_available_loopholes(object: unknown): void;
+    public set_available_loopholes(loopholes: LuaTable<string, boolean>): void;
 
     /**
      * Enable or disable editor validation for the loopholes table.
      *
      * @param value - Whether loopholes should be checked.
      */
-    public set_loopholes_table_checker(value: boolean): void;
+    public set_loopholes_table_checker(value: bool_value): void;
   }
 
   /**
@@ -26580,7 +27327,7 @@ declare module "xray16" {
    *
    * @group xr_ui_event
    */
-  type TXR_ui_event = EnumeratedStaticsValues<typeof ui_events>;
+  export type TXR_ui_event = EnumeratedStaticsValues<typeof ui_events>;
 
   /**
    * Keyboard scan-code constants.
@@ -27641,14 +28388,14 @@ declare module "xray16" {
    *
    * @group xr_ui_event
    */
-  type TXR_DIK_key_name = EnumeratedStaticsKeys<typeof DIK_keys>;
+  export type TXR_DIK_key_name = EnumeratedStaticsKeys<typeof DIK_keys>;
 
   /**
    * DIK, mouse, or gamepad key code.
    *
    * @group xr_ui_event
    */
-  type TXR_DIK_key = EnumeratedStaticsValues<typeof DIK_keys>;
+  export type TXR_DIK_key = EnumeratedStaticsValues<typeof DIK_keys>;
 
   /**
    * Game action binding constants.