xray16 1.4.0 → 1.5.1

package/types/xr_ui/xr_ui_menu.d.ts

@@ -1,98 +1,317 @@
 declare module "xray16" {
   /**
+   * Main-menu options manager binding.
+   *
    * @source C++ class COptionsManager
    * @customConstructor COptionsManager
    * @group xr_ui_menu
+   *
+   * @remarks
+   * Operates on option item groups registered by the options UI.
    */
   export class COptionsManager {
+    /**
+     * Create an options manager script proxy.
+     */
     public constructor();
 
+    /**
+     * Send a UI options message to every option item in a group.
+     *
+     * @param group - Options group name.
+     * @param message - Message name.
+     */
     public SendMessage2Group(group: string, message: string): void;
 
+    /**
+     * Restore options in a group from their backup values.
+     *
+     * @param group - Options group name.
+     */
     public UndoGroup(group: string): void;
 
+    /**
+     * Save current option values as the backup for a group.
+     *
+     * @param group - Options group name.
+     */
     public SaveBackupValues(group: string): void;
 
-    public IsGroupChanged(group: string): boolean;
-
+    /**
+     * Persist current option values for a group.
+     *
+     * @param group - Options group name.
+     */
     public SaveValues(group: string): void;
 
+    /**
+     * Apply current engine option values to controls in a group.
+     *
+     * @param group - Options group name.
+     */
     public SetCurrentValues(group: string): void;
 
+    /**
+     * Check whether accepted options require a system restart.
+     *
+     * @returns Whether a system restart is needed.
+     */
     public NeedSystemRestart(): boolean;
 
+    /**
+     * Check whether accepted options require a video restart.
+     *
+     * @returns Whether a video restart is needed.
+     */
     public NeedVidRestart(): boolean;
 
+    /**
+     * Run post-accept handling after options are saved.
+     */
     public OptionsPostAccept(): void;
   }
 
   /**
+   * Main menu binding.
+   *
    * @source C++ class CMainMenu
    * @customConstructor CMainMenu
    * @group xr_ui_menu
+   *
+   * @remarks
+   * Engine-owned singleton returned by `main_menu.get_main_menu()`.
    */
   export class CMainMenu {
+    /**
+     * Get the CD key stored by the game.
+     *
+     * @returns CD key string.
+     */
     public GetCDKey(): string;
 
+    /**
+     * Get the multiplayer account manager.
+     *
+     * @returns Account manager.
+     */
     public GetAccountMngr(): account_manager;
 
+    /**
+     * Read metadata for a recorded demo file.
+     *
+     * @param fileName - Demo file name.
+     * @returns Demo info, or `null` when it cannot be read.
+     */
     public GetDemoInfo(fileName: string): demo_info | null;
 
+    /**
+     * Get patch download progress.
+     *
+     * @returns Patch progress object.
+     */
     public GetPatchProgress(): Patch_Dawnload_Progress;
 
+    /**
+     * Get the multiplayer profile store.
+     *
+     * @returns Profile store.
+     */
     public GetProfileStore(): profile_store;
 
+    /**
+     * Get GameSpy protocol version string.
+     *
+     * @returns GameSpy version.
+     */
     public GetGSVer(): string;
 
+    /**
+     * Get the multiplayer login manager.
+     *
+     * @returns Login manager.
+     */
     public GetLoginMngr(): login_manager;
 
+    /**
+     * Get the current player name.
+     *
+     * @returns Player name.
+     */
     public GetPlayerName(): string;
 
+    /**
+     * Cancel the active multiplayer map download.
+     */
     public CancelDownload(): void;
 
+    /**
+     * Validate the stored CD key.
+     *
+     * @returns Whether the CD key is valid.
+     */
     public ValidateCDKey(): boolean;
   }
 
   /**
+   * In-game UI root binding.
+   *
    * @source C++ class CUIGameCustom
    * @customConstructor CUIGameCustom
    * @group xr_ui_menu
+   *
+   * @remarks
+   * Current in-game HUD UI. Global helpers dereference the current game UI, so call them only while a level UI exists.
    */
   export class CUIGameCustom {
-    public AddCustomStatic(id: string, b: boolean): StaticDrawableWrapper;
+    /**
+     * Add a custom HUD static by XML id.
+     *
+     * @remarks
+     * If `singleInstance` is true and an active static with this id already exists, that wrapper is returned.
+     *
+     * @param id - Static descriptor id.
+     * @param singleInstance - Whether an existing static with the same id should be reused.
+     * @returns Drawable wrapper for the static.
+     */
+    public AddCustomStatic(id: string, singleInstance: boolean): StaticDrawableWrapper;
 
-    public AddCustomStatic(id: string, b: boolean, n: f32): StaticDrawableWrapper;
+    /**
+     * Add a custom HUD static by XML id and lifetime.
+     *
+     * @remarks
+     * The static is initialized from `ui_custom_msgs.xml`. Positive lifetime values remove it automatically after
+     * that many seconds unless the XML entry overrides `ttl`.
+     *
+     * @param id - Static descriptor id.
+     * @param singleInstance - Whether an existing static with the same id should be reused.
+     * @param lifetime - Time before the static is removed.
+     * @returns Drawable wrapper for the static.
+     */
+    public AddCustomStatic(id: string, singleInstance: boolean, lifetime: f32): StaticDrawableWrapper;
 
+    /**
+     * Add a dialog window to the HUD render list.
+     *
+     * @remarks
+     * Adds the window to the HUD dialog holder. It shows the window but does not take ownership of it.
+     *
+     * @param window - Dialog window.
+     */
     public AddDialogToRender(window: CUIWindow): void;
 
-    public CurrentItemAtCell(): game_object;
+    /**
+     * Get the inventory item currently under the actor menu cursor.
+     *
+     * @since OpenXRay 2015-07-07, 6e703b4c
+     *
+     * @remarks
+     * Requires the actor menu to have a current inventory cell.
+     *
+     * @returns Game object for the item, or `null` when the cell has no item.
+     */
+    public CurrentItemAtCell(): game_object | null;
 
-    public GetCustomStatic(value: string): StaticDrawableWrapper | null;
+    /**
+     * Get an active custom HUD static by id.
+     *
+     * @param id - Static descriptor id.
+     * @returns Drawable wrapper, or `null` when missing.
+     */
+    public GetCustomStatic(id: string): StaticDrawableWrapper | null;
 
+    /**
+     * Hide the actor inventory menu.
+     *
+     * @remarks
+     * No-op when the actor menu is already hidden.
+     */
     public HideActorMenu(): void;
 
+    /**
+     * Show the actor inventory menu.
+     *
+     * @remarks
+     * Toggles the actor menu. If it is already shown, the call hides it instead.
+     *
+     * @returns `true` after handling the toggle.
+     */
     public ShowActorMenu(): boolean;
 
+    /**
+     * Hide the PDA menu.
+     *
+     * @remarks
+     * No-op when the PDA menu is already hidden.
+     */
     public HidePdaMenu(): void;
 
+    /**
+     * Remove a custom HUD static.
+     *
+     * @remarks
+     * Destroys the matching HUD-owned wrapper when it exists.
+     *
+     * @param id - Static descriptor id.
+     */
     public RemoveCustomStatic(id: string): void;
 
+    /**
+     * Remove a dialog window from the HUD render list.
+     *
+     * @remarks
+     * Hides and disables the window in the HUD dialog holder. It does not destroy the window.
+     *
+     * @param window - Dialog window.
+     */
     public RemoveDialogToRender(window: CUIWindow): void;
 
+    /**
+     * Refresh actor menu state.
+     *
+     * @since OpenXRay 2015-07-07, 6e703b4c
+     *
+     * @remarks
+     * Updates the actor menu only when it is currently shown.
+     */
     public UpdateActorMenu(): void;
 
+    /**
+     * Enable or disable fake HUD indicators.
+     *
+     * @param enabled - New fake-indicator state.
+     */
     public enable_fake_indicators(enabled: boolean): void;
 
+    /**
+     * Hide HUD messages.
+     */
     public hide_messages(): void;
 
+    /**
+     * Show HUD messages.
+     */
     public show_messages(): void;
 
-    public update_fake_indicators(u8: number, enabled: boolean): void;
+    /**
+     * Update fake indicator visibility.
+     *
+     * @param indicator - Indicator id.
+     * @param enabled - New indicator state.
+     */
+    public update_fake_indicators(indicator: number, enabled: boolean): void;
 
-    public update_fake_indicators(u8: number, value: f32): void;
+    /**
+     * Update fake indicator value.
+     *
+     * @param indicator - Indicator id.
+     * @param value - New indicator value.
+     */
+    public update_fake_indicators(indicator: number, value: f32): void;
   }
 
   /**
+   * Main menu namespace exposed to scripts.
+   *
    * @source namespace main_menu
    * @group xr_ui_menu
    */
@@ -104,22 +323,39 @@ declare module "xray16" {
   }
 
   /**
+   * Actor/PDA menu namespace exposed to scripts.
+   *
    * @source namespace ActorMenu
    * @group xr_ui_menu
+   *
+   * @remarks
+   * These helpers dereference `CurrentGameUI()` directly. Use them only in-game after the HUD UI has been created.
    */
   export interface IXR_ActorMenu {
+    /**
+     * Get the current PDA menu window.
+     *
+     * @throws When called without an active current game UI.
+     *
+     * @returns PDA menu window.
+     */
     get_pda_menu(this: void): CUIPdaWnd;
+
+    /**
+     * Get the current actor menu window.
+     *
+     * @throws When called without an active current game UI.
+     *
+     * @returns Actor menu window.
+     */
     get_actor_menu(this: void): CUIActorMenu;
 
     /**
-     * Enum EMenuMode
-     * {
-     *     mmUndefined,
-     *     mmInventory,
-     *     mmTrade,
-     *     mmUpgrade,
-     *     mmDeadBodySearch,
-     * }.
+     * Get current actor menu mode.
+     *
+     * @throws When called without an active current game UI.
+     *
+     * @returns Numeric `EMenuMode` value.
      */
     get_menu_mode(this: void): number;
     // Get_maingame(this: void): unknown; // CUIMainIngameWnd - not registered, throws exception
@@ -136,7 +372,14 @@ declare module "xray16" {
   export const main_menu: IXR_main_menu;
 
   /**
+   * Get the current game HUD UI.
+   *
    * @group xr_ui_menu
+   *
+   * @remarks
+   * The binding returns `CurrentGameUI()`. Call it only while a level HUD exists.
+   *
+   * @returns Current HUD UI controller.
    */
   export function get_hud(this: void): CUIGameCustom;
 }

package/types/xrf_plugin.d.ts

@@ -1,58 +1,88 @@
 declare global {
   /**
-   * Utility to get current file name as inline value during transpiling, similar to __filename in node.
+   * Current source file name injected at transpile time.
    *
    * @group xrf_plugin
    */
   const $filename: string;
 
   /**
-   * Utility to get current directory name as inline value during transpiling, similar to __dirname in node.
+   * Current source directory name injected at transpile time.
    *
    * @group xrf_plugin
    */
   const $dirname: string;
 
   /**
-   * Utility to transform TS provided array to a lua one.
-   * Just wrapper that is stripped compile time, but simplifies unit testing with TS.
+   * Treat a TypeScript array as a Lua array.
+   *
+   * The transformer removes this call and emits its argument.
    *
    * @group xrf_plugin
    *
-   * @param array
+   * @param array - TypeScript array.
+   * @returns Same value typed as a Lua array.
    */
   function $fromArray<T>(array: Array<T>): LuaTable<number, T>;
 
   /**
-   * Utility to transform LUA array to JS array.
-   * Just wrapper that is stripped compile time, but simplifies unit testing with TS.
+   * Treat a Lua array as a TypeScript array.
+   *
+   * The transformer removes this call and emits its argument.
    *
    * @group xrf_plugin
    *
-   * @param array
+   * @param array - Lua array.
+   * @returns Same value typed as a TypeScript array.
    */
   function $fromLuaArray<T>(array: LuaTable<number, T>): Array<T>;
 
   /**
-   * Utility to transform TS provided object to a lua table.
-   * Just wrapper that is stripped compile time, but simplifies unit testing with TS.
+   * Treat a TypeScript object as a Lua table.
+   *
+   * The transformer removes this call and emits its argument.
    *
    * @group xrf_plugin
    *
-   * @param object
+   * @param object - TypeScript object.
+   * @returns Same value typed as a Lua table.
    */
   function $fromObject<K extends string | number, T>(object: Record<K, T>): LuaTable<K, T>;
+
+  /**
+   * Treat a TypeScript object as a Lua table.
+   *
+   * The transformer removes this call and emits its argument.
+   *
+   * @group xrf_plugin
+   *
+   * @param object - TypeScript object.
+   * @returns Same value typed as a Lua table.
+   */
   function $fromObject<D>(object: D): LuaTable<keyof D, D[keyof D]>;
 
   /**
-   * Utility to transform LUA provided table to a TS one.
-   * Just wrapper that is stripped compile time, but simplifies unit testing with TS.
+   * Treat a Lua table as a TypeScript object.
+   *
+   * The transformer removes this call and emits its argument.
    *
    * @group xrf_plugin
    *
-   * @param object
+   * @param object - Lua table.
+   * @returns Same value typed as a TypeScript object.
    */
   function $fromLuaTable<K extends string | number, T>(object: LuaTable<K, T>): Record<K, T>;
+
+  /**
+   * Treat a Lua table as a TypeScript object.
+   *
+   * The transformer removes this call and emits its argument.
+   *
+   * @group xrf_plugin
+   *
+   * @param object - Lua table.
+   * @returns Same value typed as a TypeScript object.
+   */
   function $fromLuaTable<D>(object: LuaTable<keyof D, D[keyof D]>): D;
 }