xray16 1.3.4 → 1.5.0

package/types/xr_lib/xr_luabind.d.ts

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

package/types/xr_lib/xr_map.d.ts

@@ -1,61 +1,192 @@
-declare module "xray16" {
-  /**
-   * @source C++ class CMapManager
-   * @customConstructor CMapManager
-   * @group xr_map
-   */
-  export class CMapManager {
-    public constructor();
-
-    public RemoveMapLocationByObjectID(id: u16): void;
-
-    public RemoveMapLocation(spot_type: string, id: u16): void;
-
-    public DisableAllPointers(): void;
-  }
-
-  /**
-   * @source C++ class CMapLocation
-   * @customConstructor CMapLocation
-   * @group xr_map
-   */
-  export class CMapLocation {
-    public constructor();
-
-    public Collidable(): boolean;
-
-    public DisablePointer(): void;
-
-    public DisableSpot(): void;
-
-    public EnablePointer(): void;
-
-    public EnableSpot(): void;
-
-    public GetHint(): string;
-
-    public GetLastPosition(): vector2;
-
-    public GetLevelName(): string;
-
-    public GetPosition(): vector2;
-
-    public HighlightSpot(state: boolean, color: fcolor): void;
-
-    public HintEnabled(): boolean;
-
-    public IsUserDefined(): boolean;
-
-    public ObjectID(): u16;
-
-    public PointerEnabled(): boolean;
-
-    public SetHint(hint: string): void;
-
-    public SetUserDefinedFlag(state: boolean): void;
-
-    public SpotEnabled(): boolean;
-
-    public SpotSize(): vector2;
-  }
-}
+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;
+
+    /**
+     * 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 {
+    /**
+     * 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;
+
+    /**
+     * @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;
+  }
+}