xray16 1.4.0 → 1.5.0

package/types/xr_lib/xr_map.d.ts

@@ -1,61 +1,192 @@
 declare module "xray16" {
   /**
+   * Manages active PDA/minimap locations.
+   *
    * @source C++ class CMapManager
    * @customConstructor CMapManager
    * @group xr_map
+   *
+   * @remarks
+   * Level scripts usually work with the level-owned map manager through map spot helpers instead of creating wrappers.
+   * Removed locations are queued for deferred destruction and should not be reused from script.
    */
   export class CMapManager {
+    /**
+     * Create a map manager wrapper.
+     */
     public constructor();
 
+    /**
+     * Remove all map locations attached to an object id.
+     *
+     * @remarks
+     * In single-player this also releases linked game-task map locations. Native location objects are destroyed on the
+     * manager's deferred destroy queue, so any old `CMapLocation` references become unsafe to use.
+     *
+     * @param id - Game object id.
+     */
     public RemoveMapLocationByObjectID(id: u16): void;
 
-    public RemoveMapLocation(spot_type: string, id: u16): void;
-
+    /**
+     * Remove a specific map location.
+     *
+     * @remarks
+     * In single-player this also releases linked game-task map locations. Native location objects are destroyed on the
+     * manager's deferred destroy queue, so do not call methods on `location` after removal.
+     *
+     * @param location - Location object to remove.
+     */
+    public RemoveMapLocation(location: CMapLocation): void;
+
+    /**
+     * Hide pointers for all map locations.
+     *
+     * @remarks
+     * Only pointer arrows are disabled. The map spots themselves remain enabled.
+     */
     public DisableAllPointers(): void;
   }
 
   /**
+   * A single PDA/minimap spot attached to an object or user position.
+   *
    * @source C++ class CMapLocation
    * @customConstructor CMapLocation
    * @group xr_map
+   *
+   * @remarks
+   * Map locations are created by the engine or map manager. The native binding does not expose a script constructor.
+   * A location can also expire or be removed by object lifetime, TTL, or task cleanup.
    */
   export class CMapLocation {
-    public constructor();
-
+    /**
+     * Engine-created map location.
+     */
+    protected constructor();
+
+    /**
+     * @returns Whether the map spot participates in UI collision.
+     */
     public Collidable(): boolean;
 
+    /**
+     * Hide the off-screen pointer arrow.
+     */
     public DisablePointer(): void;
 
+    /**
+     * Hide the map spot.
+     */
     public DisableSpot(): void;
 
+    /**
+     * Show the off-screen pointer arrow.
+     */
     public EnablePointer(): void;
 
+    /**
+     * Show the map spot.
+     */
     public EnableSpot(): void;
 
-    public GetHint(): string;
-
+    /**
+     * @remarks
+     * Returns `null` when hints are disabled for this spot.
+     *
+     * @returns Hint text shown for the spot.
+     */
+    public GetHint(): string | null;
+
+    /**
+     * @remarks
+     * This is a cached value updated by the map manager.
+     *
+     * @returns Last calculated spot position.
+     */
     public GetLastPosition(): vector2;
 
+    /**
+     * @remarks
+     * This is a cached value updated by the map manager.
+     *
+     * @returns Level name where the spot is located.
+     */
     public GetLevelName(): string;
 
+    /**
+     * @remarks
+     * This is a cached value updated by the map manager.
+     *
+     * @returns Current spot position on the map.
+     */
     public GetPosition(): vector2;
 
+    /**
+     * Highlight or clear the spot highlight.
+     *
+     * @remarks
+     * Requires a location type with a level-map spot. Types that only define minimap or complex-map visuals are not good
+     * candidates for this helper.
+     *
+     * @param state - Whether highlighting is enabled.
+     * @param color - Highlight color.
+     */
     public HighlightSpot(state: boolean, color: fcolor): void;
 
+    /**
+     * @returns Whether a hint can be shown for the spot.
+     */
     public HintEnabled(): boolean;
 
+    /**
+     * @returns Whether this is a user-created spot.
+     */
     public IsUserDefined(): boolean;
 
+    /**
+     * @returns Object id this spot tracks.
+     */
     public ObjectID(): u16;
 
+    /**
+     * @remarks
+     * Pointer state also depends on `SpotEnabled()`. A disabled spot reports its pointer as disabled.
+     *
+     * @returns Whether the off-screen pointer arrow is enabled.
+     */
     public PointerEnabled(): boolean;
 
+    /**
+     * Set hint text shown for the spot.
+     *
+     * @remarks
+     * Passing `disable_hint` disables hints and clears the stored hint.
+     *
+     * @param hint - Hint text or string table id.
+     */
     public SetHint(hint: string): void;
 
+    /**
+     * Mark the spot as user-created or engine-owned.
+     *
+     * @param state - User-defined flag.
+     */
     public SetUserDefinedFlag(state: boolean): void;
 
+    /**
+     * @remarks
+     * Disabling a spot also makes `PointerEnabled()` return `false`.
+     *
+     * @returns Whether the map spot is enabled.
+     */
     public SpotEnabled(): boolean;
 
+    /**
+     * @remarks
+     * Reads the level-map spot size. Use only for location types that define a level-map spot in `map_spots.xml`.
+     *
+     * @returns Spot size on the map.
+     */
     public SpotSize(): vector2;
   }
 }

package/types/xr_lib/xr_math.d.ts

@@ -5,6 +5,9 @@ declare module "xray16" {
    * @source C++ class Frect
    * @customConstructor Frect
    * @group xr_math
+   *
+   * @remarks
+   * Used by UI bindings for window and texture rectangles. `set()` mutates this rectangle.
    */
   export class Frect extends EngineBinding {
     /**
@@ -60,6 +63,9 @@ declare module "xray16" {
    * @source C++ class Fbox
    * @customConstructor Fbox
    * @group xr_math
+   *
+   * @remarks
+   * Bounds are stored as mutable `min` and `max` vectors.
    */
   export class Fbox {
     /**
@@ -103,6 +109,9 @@ declare module "xray16" {
    * @source C++ class vector2
    * @customConstructor vector2
    * @group xr_math
+   *
+   * @remarks
+   * `set()` mutates the receiver and returns it for chaining.
    */
   export class vector2 {
     /**
@@ -146,6 +155,9 @@ declare module "xray16" {
    * @source C++ class XR_vector
    * @customConstructor vector
    * @group xr_math
+   *
+   * @remarks
+   * Use `set()` first when you need a known value; script-created native vectors expose their fields directly.
    */
   export class vector {
     /**
@@ -287,6 +299,9 @@ declare module "xray16" {
     /**
      * Divide every component by a scalar.
      *
+     * @remarks
+     * The binding performs raw division. Pass a non-zero divisor.
+     *
      * @param value - Scalar divisor.
      * @returns This vector.
      */
@@ -295,6 +310,9 @@ declare module "xray16" {
     /**
      * Set this vector to component-wise `left / right`.
      *
+     * @remarks
+     * The binding performs raw component division. Divisor components must be non-zero.
+     *
      * @param left - Left vector.
      * @param right - Right vector.
      * @returns This vector.
@@ -304,6 +322,9 @@ declare module "xray16" {
     /**
      * Divide this vector component-wise by another vector.
      *
+     * @remarks
+     * The binding performs raw component division. Divisor components must be non-zero.
+     *
      * @param vector - Divisor vector.
      * @returns This vector.
      */
@@ -312,6 +333,9 @@ declare module "xray16" {
     /**
      * Set this vector to `vector / value`.
      *
+     * @remarks
+     * The binding performs raw division. Pass a non-zero divisor.
+     *
      * @param vector - Source vector.
      * @param value - Scalar divisor.
      * @returns This vector.
@@ -329,6 +353,9 @@ declare module "xray16" {
     /**
      * Get heading angle for this direction vector.
      *
+     * @remarks
+     * Intended for direction vectors. For arbitrary points, the result is just the angle of that vector from origin.
+     *
      * @returns Heading angle in radians.
      */
     public getH(): f32;
@@ -336,6 +363,9 @@ declare module "xray16" {
     /**
      * Get pitch angle for this direction vector.
      *
+     * @remarks
+     * Intended for direction vectors. For arbitrary points, the result is just the angle of that vector from origin.
+     *
      * @returns Pitch angle in radians.
      */
     public getP(): f32;
@@ -490,6 +520,9 @@ declare module "xray16" {
     /**
      * Normalize this vector safely.
      *
+     * @remarks
+     * The script binding routes `normalize()` through the same safe native path as `normalize_safe()`.
+     *
      * @returns This vector.
      */
     public normalize(): vector;
@@ -497,6 +530,9 @@ declare module "xray16" {
     /**
      * Set this vector to normalized source vector safely.
      *
+     * @remarks
+     * The script binding routes `normalize(vector)` through the same safe native path as `normalize_safe(vector)`.
+     *
      * @param vector - Source vector.
      * @returns This vector.
      */
@@ -556,6 +592,9 @@ declare module "xray16" {
     /**
      * Change vector length while keeping direction.
      *
+     * @remarks
+     * Use on a vector that already has a meaningful direction.
+     *
      * @param value - New length.
      * @returns This vector.
      */
@@ -620,6 +659,9 @@ declare module "xray16" {
    * @source C++ class RPoint
    * @customConstructor RPoint
    * @group xr_math
+   *
+   * @remarks
+   * `P` stores position, `A` stores orientation data used by patrol graph points.
    */
   export class RPoint {
     /**
@@ -646,6 +688,10 @@ declare module "xray16" {
    * @source C++ class matrix
    * @customConstructor matrix
    * @group xr_math
+   *
+   * @remarks
+   * Script-exposed mutators return this matrix for chaining. Call `identity()` or `set()` before composing transforms
+   * when you need a known starting value.
    */
   export class matrix {
     /**
@@ -724,6 +770,9 @@ declare module "xray16" {
     /**
      * Set this matrix to `value / divisor`.
      *
+     * @remarks
+     * The binding performs raw scalar division. Pass a non-zero divisor.
+     *
      * @param value - Source matrix.
      * @param divisor - Scalar divisor.
      * @returns This matrix.
@@ -733,6 +782,9 @@ declare module "xray16" {
     /**
      * Divide this matrix by a scalar.
      *
+     * @remarks
+     * The binding performs raw scalar division. Pass a non-zero divisor.
+     *
      * @param divisor - Scalar divisor.
      * @returns This matrix.
      */
@@ -768,6 +820,10 @@ declare module "xray16" {
     /**
      * Get heading, pitch, and bank from this matrix.
      *
+     * @remarks
+     * Native Lua uses pointer-style output parameters for `heading`, `pitch`, and `bank`; the declaration keeps the
+     * legacy shape for compatibility.
+     *
      * @param value - Placeholder kept for existing declaration compatibility.
      * @param heading - Heading output placeholder.
      * @param pitch - Pitch output placeholder.