xray16 1.3.4 → 1.5.0

package/types/xr_lib/xr_debug.d.ts

@@ -1,77 +1,181 @@
-declare module "xray16" {
-  /**
-   * @source C++ class CConsole
-   * @customConstructor CConsole
-   * @group xr_debug
-   */
-  export class CConsole extends EngineBinding {
-    private constructor();
-
-    public execute(command: string): void;
-
-    public execute_deferred(command: string): void;
-
-    public execute_script(script: string): void;
-
-    public show(): void;
-
-    public hide(): void;
-
-    public get_bool(key: string): boolean;
-
-    public get_float(key: string): f32;
-
-    public get_integer(key: string): i32;
-
-    public get_string(key: string): string;
-
-    public get_token(key: string): string;
-  }
-
-  /**
-   * Log formatted message in game console and log file.
-   * Resulting message looks like "[LUA]  %s", where message is provided text parameter.
-   *
-   * Note: text length is limited and supplying too long value will crash the game. todo: check exact limit.
-   *
-   * @group xr_debug
-   * @param text - string to print
-   */
-  export function log(this: void, text: string): void;
-
-  /**
-   * @group xr_debug
-   */
-  export function error_log(this: void, text: string): void;
-
-  /**
-   * @group xr_debug
-   */
-  export function print_stack(this: void): void;
-
-  /**
-   * @group xr_debug
-   */
-  export function flush(this: void): void;
-
-  /**
-   * Get console object reference.
-   * Allows flushing logs / executing commands / getting global engine variables.
-   *
-   * @group xr_debug
-   * @returns console object reference
-   */
-  export function get_console(this: void): CConsole;
-
-  /**
-   * @group xr_debug
-   */
-  export function command_line(this: void): string;
-
-  /**
-   * Prefetch provided script before executing next lines.
-   *
-   * @group xr_global_declaration
-   */
-  export function prefetch(this: void, path: string): void;
-}
+declare module "xray16" {
+  /**
+   * Engine console interface.
+   *
+   * @source C++ class CConsole
+   * @customConstructor CConsole
+   * @group xr_debug
+   *
+   * @remarks
+   * Use `get_console()` to access the engine-owned console. Scripts do not create console instances.
+   */
+  export class CConsole extends EngineBinding {
+    /**
+     * Engine-owned console singleton.
+     */
+    private constructor();
+
+    /**
+     * Execute console command immediately.
+     *
+     * @remarks
+     * Executes without adding the command to console history.
+     *
+     * @param command - Console command.
+     */
+    public execute(command: string): void;
+
+    /**
+     * Queue console command for deferred execution.
+     *
+     * @remarks
+     * Schedules a `KERNEL:console` event, so the command runs later on the engine event queue.
+     *
+     * @param command - Console command.
+     */
+    public execute_deferred(command: string): void;
+
+    /**
+     * Execute a config file through the console.
+     *
+     * @remarks
+     * The binding prepends `cfg_load` to the provided path.
+     *
+     * @param script - Config file path.
+     */
+    public execute_script(script: string): void;
+
+    /**
+     * Show the console window.
+     */
+    public show(): void;
+
+    /**
+     * Hide the console window.
+     */
+    public hide(): void;
+
+    /**
+     * Read console variable as boolean.
+     *
+     * @remarks
+     * Returns `false` when the command is missing or is not a boolean-compatible mask/integer command.
+     *
+     * @param key - Console variable name.
+     * @returns Boolean value.
+     */
+    public get_bool(key: string): boolean;
+
+    /**
+     * Read console variable as float.
+     *
+     * @remarks
+     * Returns `0` when the command is missing or is not a float command.
+     *
+     * @param key - Console variable name.
+     * @returns Float value.
+     */
+    public get_float(key: string): f32;
+
+    /**
+     * Read console variable as integer.
+     *
+     * @remarks
+     * Mask commands are returned as `0` or `1`. Missing or incompatible commands return `0`.
+     *
+     * @param key - Console variable name.
+     * @returns Integer value.
+     */
+    public get_integer(key: string): i32;
+
+    /**
+     * Read console variable as string.
+     *
+     * @remarks
+     * Returns `null` when the command does not exist.
+     *
+     * @param key - Console variable name.
+     * @returns String value.
+     */
+    public get_string(key: string): string | null;
+
+    /**
+     * Read console variable token text.
+     *
+     * @remarks
+     * Uses the same engine path as `get_string`, so missing commands return `null`.
+     *
+     * @param key - Console variable name.
+     * @returns Token text.
+     */
+    public get_token(key: string): string | null;
+  }
+
+  /**
+   * Log a message through the script log channel.
+   *
+   * @group xr_debug
+   *
+   * @remarks
+   * In non-master builds the message is sent to `CScriptEngine::script_log`.
+   *
+   * @param text - Message to print.
+   */
+  export function log(this: void, text: string): void;
+
+  /**
+   * Log an error message and print the current script stack.
+   *
+   * @group xr_debug
+   *
+   * @remarks
+   * The C++ binding asserts after logging the message.
+   *
+   * @param text - Error message.
+   */
+  export function error_log(this: void, text: string): void;
+
+  /**
+   * Print the current script stack to the log.
+   *
+   * @group xr_debug
+   */
+  export function print_stack(this: void): void;
+
+  /**
+   * Flush pending script log output in debug builds.
+   *
+   * @group xr_debug
+   */
+  export function flush(this: void): void;
+
+  /**
+   * Get console object reference.
+   *
+   * @group xr_debug
+   *
+   * @remarks
+   * Returns the global engine console pointer.
+   *
+   * @returns Console object reference.
+   */
+  export function get_console(this: void): CConsole;
+
+  /**
+   * Get process command-line parameters.
+   *
+   * @group xr_debug
+   *
+   * @returns Engine command-line string.
+   */
+  export function command_line(this: void): string;
+
+  /**
+   * Load and compile a script before continuing execution.
+   *
+   * @group xr_global_declaration
+   *
+   * @param path - Script file path.
+   */
+  export function prefetch(this: void, path: string): void;
+}

package/types/xr_lib/xr_dialog.d.ts

@@ -1,40 +1,132 @@
-declare module "xray16" {
-  /**
-   * @source C++ class CPhraseScript
-   * @customConstructor CPhraseScript
-   * @group xr_dialog
-   */
-  export class CPhraseScript {
-    public AddAction(value: string): void;
-
-    public AddDisableInfo(value: string): void;
-
-    public AddDontHasInfo(value: string): void;
-
-    public AddGiveInfo(value: string): void;
-
-    public AddHasInfo(value: string): void;
-
-    public AddPrecondition(value: string): void;
-
-    public SetScriptText(value: string): void;
-  }
-
-  /**
-   * @source C++ class CPhrase
-   * @customConstructor CPhrase
-   * @group xr_dialog
-   */
-  export class CPhrase {
-    public GetPhraseScript(): CPhraseScript;
-  }
-
-  /**
-   * @source C++ class CPhraseDialog
-   * @customConstructor CPhraseDialog
-   * @group xr_dialog
-   */
-  export class CPhraseDialog {
-    public AddPhrase(text: string, phrase_id: string, prev_phrase_id: string, goodwill_level: i32): CPhrase;
-  }
-}
+declare module "xray16" {
+  /**
+   * Script rules attached to a dialog phrase.
+   *
+   * @source C++ class CPhraseScript
+   * @customConstructor CPhraseScript
+   * @group xr_dialog
+   *
+   * @remarks
+   * Phrase scripts are evaluated by the dialog engine against the current actor/NPC speakers. Info portion checks use
+   * the actor info registry.
+   */
+  export class CPhraseScript {
+    /**
+     * Run a script action after the phrase is spoken.
+     *
+     * @remarks
+     * In active two-speaker dialogs the function receives `(speaker, listener, dialog_id, phrase_id)`. In simpler
+     * dialog checks it receives `(speaker, dialog_id)`.
+     *
+     * @throws If the function name cannot be resolved.
+     *
+     * @param function_name - Script function name.
+     */
+    public AddAction(function_name: string): void;
+
+    /**
+     * Disable an info portion when phrase actions run.
+     *
+     * @remarks
+     * Applied after the phrase is accepted and its actions run.
+     *
+     * @param info_portion - Info portion id.
+     */
+    public AddDisableInfo(info_portion: string): void;
+
+    /**
+     * Require an info portion to be absent before the phrase is available.
+     *
+     * @param info_portion - Info portion id.
+     */
+    public AddDontHasInfo(info_portion: string): void;
+
+    /**
+     * Give an info portion when phrase actions run.
+     *
+     * @remarks
+     * Applied after the phrase is accepted and its actions run.
+     *
+     * @param info_portion - Info portion id.
+     */
+    public AddGiveInfo(info_portion: string): void;
+
+    /**
+     * Require an info portion before the phrase is available.
+     *
+     * @param info_portion - Info portion id.
+     */
+    public AddHasInfo(info_portion: string): void;
+
+    /**
+     * Add a script predicate checked before the phrase is available.
+     *
+     * @remarks
+     * In active two-speaker dialogs the function receives `(speaker, listener, dialog_id, phrase_id, next_phrase_id)`.
+     * It should return `true` when the phrase may be shown.
+     *
+     * @throws If the function name cannot be resolved.
+     *
+     * @param function_name - Script function name.
+     */
+    public AddPrecondition(function_name: string): void;
+
+    /**
+     * Use a script function to provide phrase text.
+     *
+     * @remarks
+     * The function is called when the dialog asks for phrase text. Use it for text that depends on the current speaker
+     * or dialog state.
+     *
+     * @throws If the function name cannot be resolved.
+     *
+     * @param function_name - Script function name.
+     */
+    public SetScriptText(function_name: string): void;
+  }
+
+  /**
+   * Runtime phrase in a phrase dialog.
+   *
+   * @source C++ class CPhrase
+   * @customConstructor CPhrase
+   * @group xr_dialog
+   *
+   * @remarks
+   * Phrase instances are owned by the dialog graph. Script code usually configures them immediately after
+   * `CPhraseDialog.AddPhrase`.
+   */
+  export class CPhrase {
+    /**
+     * @returns Script helper used to configure phrase conditions and actions.
+     */
+    public GetPhraseScript(): CPhraseScript;
+  }
+
+  /**
+   * Phrase dialog built or extended from scripts.
+   *
+   * @source C++ class CPhraseDialog
+   * @customConstructor CPhraseDialog
+   * @group xr_dialog
+   *
+   * @remarks
+   * A phrase dialog is a directed phrase graph. Phrase id `"0"` is the start phrase used by loaded XML dialogs.
+   */
+  export class CPhraseDialog {
+    /**
+     * Add a phrase to the dialog tree.
+     *
+     * @remarks
+     * `prev_phrase_id` creates the edge from the previous phrase to the new one. Pass an empty string for a root phrase.
+     * Reusing an existing `phrase_id` returns the existing phrase and still links it from `prev_phrase_id`.
+     *
+     * @param text - Text or string table id.
+     * @param phrase_id - New phrase id.
+     * @param prev_phrase_id - Parent phrase id, or an empty string.
+     * @param goodwill_level - Goodwill value used when the engine orders available replies.
+     * @returns Created phrase.
+     */
+    public AddPhrase(text: string, phrase_id: string, prev_phrase_id: string, goodwill_level: i32): CPhrase;
+  }
+}