xray16 1.4.0 → 1.5.0

package/types/xr_lib/xr_dialog.d.ts

@@ -1,40 +1,132 @@
 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 {
-    public AddAction(value: string): void;
+    /**
+     * 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;
 
-    public AddDisableInfo(value: 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;
 
-    public AddDontHasInfo(value: 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;
 
-    public AddGiveInfo(value: 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;
 
-    public AddHasInfo(value: string): void;
+    /**
+     * Require an info portion before the phrase is available.
+     *
+     * @param info_portion - Info portion id.
+     */
+    public AddHasInfo(info_portion: string): void;
 
-    public AddPrecondition(value: 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;
 
-    public SetScriptText(value: 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;
   }
 }

package/types/xr_lib/xr_flags.d.ts

@@ -5,10 +5,13 @@ declare module "xray16" {
    * @source C++ class flags8
    * @customConstructor flags8
    * @group xr_flags
+   *
+   * @remarks
+   * Use `zero()`, `one()`, or `assign()` when you need an explicit initial state.
    */
   export class flags8 {
     /**
-     * Create an empty mask.
+     * Create a flag mask.
      */
     public constructor();
 
@@ -85,9 +88,9 @@ declare module "xray16" {
     public invert(value: flags8): flags8;
 
     /**
-     * Replace this mask with inverted raw value.
+     * Toggle selected bits in this mask.
      *
-     * @param value - Raw mask value.
+     * @param value - Bits to toggle.
      * @returns This mask.
      */
     public invert(value: u8): flags8;
@@ -95,6 +98,9 @@ declare module "xray16" {
     /**
      * Check whether all selected bits are set in a source mask.
      *
+     * @remarks
+     * This is stricter than `is_any()` and `test()`: every bit from `mask` must be present.
+     *
      * @param value - Source mask.
      * @param mask - Bits to test.
      * @returns Whether all bits are set.
@@ -104,6 +110,9 @@ declare module "xray16" {
     /**
      * Check whether all selected bits are set in this mask.
      *
+     * @remarks
+     * This is stricter than `is_any()` and `test()`: every bit from `mask` must be present.
+     *
      * @param mask - Bits to test.
      * @returns Whether all bits are set.
      */
@@ -112,6 +121,9 @@ declare module "xray16" {
     /**
      * Check whether any selected bit is set in a source mask.
      *
+     * @remarks
+     * Use this for overlap checks. For an all-bits check, use `is()`.
+     *
      * @param value - Source mask.
      * @param mask - Bits to test.
      * @returns Whether any bit is set.
@@ -121,6 +133,9 @@ declare module "xray16" {
     /**
      * Check whether any selected bit is set in this mask.
      *
+     * @remarks
+     * Use this for overlap checks. For an all-bits check, use `is()`.
+     *
      * @param mask - Bits to test.
      * @returns Whether any bit is set.
      */
@@ -129,6 +144,9 @@ declare module "xray16" {
     /**
      * Set all bits.
      *
+     * @remarks
+     * Sets all 8 bits to `1`.
+     *
      * @returns This mask.
      */
     public one(): flags8;
@@ -160,10 +178,13 @@ declare module "xray16" {
     public set(mask: u8, enabled: boolean): flags8;
 
     /**
-     * Test whether selected bits are set.
+     * Test whether any selected bit is set.
+     *
+     * @remarks
+     * Equivalent to `is_any(mask)`.
      *
      * @param mask - Bits to test.
-     * @returns Whether selected bits are set.
+     * @returns Whether any selected bit is set.
      */
     public test(mask: u8): boolean;
 
@@ -181,10 +202,13 @@ declare module "xray16" {
    * @source C++ class flags16
    * @customConstructor flags16
    * @group xr_flags
+   *
+   * @remarks
+   * Use `zero()`, `one()`, or `assign()` when you need an explicit initial state.
    */
   export class flags16 {
     /**
-     * Create an empty mask.
+     * Create a flag mask.
      */
     public constructor();
 
@@ -261,9 +285,9 @@ declare module "xray16" {
     public invert(value: flags16): flags16;
 
     /**
-     * Replace this mask with inverted raw value.
+     * Toggle selected bits in this mask.
      *
-     * @param value - Raw mask value.
+     * @param value - Bits to toggle.
      * @returns This mask.
      */
     public invert(value: u16): flags16;
@@ -271,6 +295,9 @@ declare module "xray16" {
     /**
      * Check whether all selected bits are set in a source mask.
      *
+     * @remarks
+     * This is stricter than `is_any()` and `test()`: every bit from `mask` must be present.
+     *
      * @param value - Source mask.
      * @param mask - Bits to test.
      * @returns Whether all bits are set.
@@ -280,6 +307,9 @@ declare module "xray16" {
     /**
      * Check whether all selected bits are set in this mask.
      *
+     * @remarks
+     * This is stricter than `is_any()` and `test()`: every bit from `mask` must be present.
+     *
      * @param mask - Bits to test.
      * @returns Whether all bits are set.
      */
@@ -288,6 +318,9 @@ declare module "xray16" {
     /**
      * Check whether any selected bit is set in a source mask.
      *
+     * @remarks
+     * Use this for overlap checks. For an all-bits check, use `is()`.
+     *
      * @param value - Source mask.
      * @param mask - Bits to test.
      * @returns Whether any bit is set.
@@ -297,6 +330,9 @@ declare module "xray16" {
     /**
      * Check whether any selected bit is set in this mask.
      *
+     * @remarks
+     * Use this for overlap checks. For an all-bits check, use `is()`.
+     *
      * @param mask - Bits to test.
      * @returns Whether any bit is set.
      */
@@ -305,6 +341,9 @@ declare module "xray16" {
     /**
      * Set all bits.
      *
+     * @remarks
+     * Sets all 16 bits to `1`.
+     *
      * @returns This mask.
      */
     public one(): flags16;
@@ -336,10 +375,13 @@ declare module "xray16" {
     public set(mask: u16, enabled: boolean): flags16;
 
     /**
-     * Test whether selected bits are set.
+     * Test whether any selected bit is set.
+     *
+     * @remarks
+     * Equivalent to `is_any(mask)`.
      *
      * @param mask - Bits to test.
-     * @returns Whether selected bits are set.
+     * @returns Whether any selected bit is set.
      */
     public test(mask: u16): boolean;
 
@@ -357,10 +399,13 @@ declare module "xray16" {
    * @source C++ class flags32
    * @customConstructor flags32
    * @group xr_flags
+   *
+   * @remarks
+   * Use `zero()`, `one()`, or `assign()` when you need an explicit initial state.
    */
   export class flags32 {
     /**
-     * Create an empty mask.
+     * Create a flag mask.
      */
     public constructor();
 
@@ -437,9 +482,9 @@ declare module "xray16" {
     public invert(value: flags32): flags32;
 
     /**
-     * Replace this mask with inverted raw value.
+     * Toggle selected bits in this mask.
      *
-     * @param value - Raw mask value.
+     * @param value - Bits to toggle.
      * @returns This mask.
      */
     public invert(value: u32): flags32;
@@ -447,6 +492,9 @@ declare module "xray16" {
     /**
      * Check whether all selected bits are set in a source mask.
      *
+     * @remarks
+     * This is stricter than `is_any()` and `test()`: every bit from `mask` must be present.
+     *
      * @param value - Source mask.
      * @param mask - Bits to test.
      * @returns Whether all bits are set.
@@ -456,6 +504,9 @@ declare module "xray16" {
     /**
      * Check whether all selected bits are set in this mask.
      *
+     * @remarks
+     * This is stricter than `is_any()` and `test()`: every bit from `mask` must be present.
+     *
      * @param mask - Bits to test.
      * @returns Whether all bits are set.
      */
@@ -464,6 +515,9 @@ declare module "xray16" {
     /**
      * Check whether any selected bit is set in a source mask.
      *
+     * @remarks
+     * Use this for overlap checks. For an all-bits check, use `is()`.
+     *
      * @param value - Source mask.
      * @param mask - Bits to test.
      * @returns Whether any bit is set.
@@ -473,6 +527,9 @@ declare module "xray16" {
     /**
      * Check whether any selected bit is set in this mask.
      *
+     * @remarks
+     * Use this for overlap checks. For an all-bits check, use `is()`.
+     *
      * @param mask - Bits to test.
      * @returns Whether any bit is set.
      */
@@ -481,6 +538,9 @@ declare module "xray16" {
     /**
      * Set all bits.
      *
+     * @remarks
+     * Sets all 32 bits to `1`.
+     *
      * @returns This mask.
      */
     public one(): flags32;
@@ -512,10 +572,13 @@ declare module "xray16" {
     public set(mask: u32, enabled: boolean): flags32;
 
     /**
-     * Test whether selected bits are set.
+     * Test whether any selected bit is set.
+     *
+     * @remarks
+     * Equivalent to `is_any(mask)`.
      *
      * @param mask - Bits to test.
-     * @returns Whether selected bits are set.
+     * @returns Whether any selected bit is set.
      */
     public test(mask: u32): boolean;