xray16 1.4.0 → 1.5.0

package/types/xr_lib/xr_profile.d.ts

@@ -2,6 +2,8 @@ declare module "xray16" {
   /**
    * No Lua profiler is active.
    *
+   * @since OpenXRay 2025-03-19, ac4ba75d, PR #1771
+   *
    * @source C++ enum CScriptProfilerType::None
    * @group xr_profiler
    */
@@ -10,6 +12,8 @@ declare module "xray16" {
   /**
    * Hook-based Lua profiler.
    *
+   * @since OpenXRay 2025-03-19, ac4ba75d, PR #1771
+   *
    * @source C++ enum CScriptProfilerType::Hook
    * @group xr_profiler
    */
@@ -18,6 +22,8 @@ declare module "xray16" {
   /**
    * LuaJIT sampling profiler.
    *
+   * @since OpenXRay 2025-03-19, ac4ba75d, PR #1771
+   *
    * @source C++ enum CScriptProfilerType::Sampling
    * @group xr_profiler
    */
@@ -32,18 +38,51 @@ declare module "xray16" {
   export type TXR_ProfilerType = typeof PROFILER_TYPE_NONE | typeof PROFILER_TYPE_HOOK | typeof PROFILER_TYPE_SAMPLING;
 
   /**
+   * Lightweight script profile timer.
+   *
+   * @since OpenXRay 2025-03-19, ac4ba75d, PR #1771
+   *
    * @source C++ class profile_timer
    * @customConstructor profile_timer
    * @group xr_profiler
+   *
+   * @remarks
+   * The timer accumulates elapsed microseconds between matching `start()` and `stop()` calls. Nested starts are counted
+   * and only the outermost stop adds elapsed time.
    */
   export class profile_timer extends EngineBinding {
+    /**
+     * Create a stopped profile timer.
+     */
     public constructor();
+
+    /**
+     * Copy an existing timer.
+     *
+     * @param timer - Timer to copy.
+     */
     public constructor(timer: profile_timer);
 
+    /**
+     * Stop measuring elapsed time.
+     *
+     * @remarks
+     * Calling `stop()` on a timer that was not started is ignored.
+     */
     public stop(): void;
 
+    /**
+     * Start or restart measuring elapsed time.
+     *
+     * @remarks
+     * Calling `start()` while the timer is already running increases the recursion mark instead of restarting the
+     * underlying clock.
+     */
     public start(): void;
 
+    /**
+     * @returns Elapsed time in microseconds.
+     */
     public time(): f32;
 
     /**
@@ -55,8 +94,15 @@ declare module "xray16" {
   }
 
   /**
+   * Lua script profiler namespace.
+   *
+   * @since OpenXRay 2025-03-19, ac4ba75d, PR #1771
+   *
    * @source namespace profiler
    * @group xr_profiler
+   *
+   * @remarks
+   * Requires an engine script profiler instance. Starting an already active profiler is ignored by the engine.
    */
   export interface IXR_profiler {
     /**
@@ -71,12 +117,18 @@ declare module "xray16" {
 
     /**
      * Start lua scripts profiler in default mode.
+     *
+     * @remarks
+     * The default mode is hook profiling.
      */
     start(this: void): void;
 
     /**
      * Start lua scripts profiler of provided type.
      *
+     * @remarks
+     * Passing `PROFILER_TYPE_NONE` does not start profiling and only logs a message.
+     *
      * @param profiler_type - Type of profiler to start (note: see global exports of type constants).
      */
     start(this: void, profiler_type: TXR_ProfilerType): void;
@@ -84,28 +136,44 @@ declare module "xray16" {
     /**
      * Start profiler in hook mode.
      * Profiling performance based on lua call start/end events.
+     *
+     * @remarks
+     * Hook mode attaches a Lua hook. If another hook is already installed, start may fail and only log the failure.
      */
     start_hook_mode(this: void): void;
 
     /**
      * Start profiler in sampling mode with default sampling interval.
+     *
+     * @remarks
+     * Sampling mode uses LuaJIT profiling. It cannot start when LuaJIT profiling is unavailable, for example with
+     * `-nojit`.
      */
     start_sampling_mode(this: void): void;
 
     /**
      * Start profiler in sampling mode with provided sampling interval value.
      *
+     * @remarks
+     * The engine clamps the interval to its supported range.
+     *
      * @param sampling_interval - Interval to collect samples with luaJIT sampling profiler.
      */
     start_sampling_mode(this: void, sampling_interval: u32): void;
 
     /**
      * Stop currently active profiler.
+     *
+     * @remarks
+     * Stopping clears collected profiling data. Calling it while inactive only logs a message.
      */
     stop(this: void): void;
 
     /**
      * Reset measurements data of profiler.
+     *
+     * @remarks
+     * Reset keeps the current profiling mode active and clears collected samples.
      */
     reset(this: void): void;
 
@@ -124,6 +192,10 @@ declare module "xray16" {
 
     /**
      * Save report of profiler measurements in corresponding log/perf file.
+     *
+     * @remarks
+     * Hook reports are saved under `$logs$` as `*_hook_profile.log`. Sampling reports are saved as
+     * `*_sampling_profile.perf`.
      */
     save_report(this: void): void;
   }
@@ -131,6 +203,8 @@ declare module "xray16" {
   /**
    * Lua script profiler namespace.
    *
+   * @since OpenXRay 2025-03-19, ac4ba75d, PR #1771
+   *
    * @source namespace profiler
    * @group xr_profiler
    */
@@ -153,8 +227,14 @@ declare module "xray16" {
      */
     ZoneBeginN(this: void, name: string): void;
 
+    /**
+     * Begin a Tracy profiling zone with source location data.
+     */
     ZoneBeginS(this: void): void;
 
+    /**
+     * Begin a named Tracy profiling zone with source location data.
+     */
     ZoneBeginNS(this: void): void;
 
     /**

package/types/xr_lib/xr_properties.d.ts

@@ -17,6 +17,9 @@ declare module "xray16" {
      */
     public name: string;
 
+    /**
+     * Engine-created token.
+     */
     private constructor();
   }
 
@@ -26,6 +29,9 @@ declare module "xray16" {
    * @source C++ class rtoken_list
    * @customConstructor rtoken_list
    * @group xr_properties
+   *
+   * @remarks
+   * Used by editor property rows that need a list of strings computed at runtime.
    */
   export class rtoken_list {
     /**
@@ -36,6 +42,9 @@ declare module "xray16" {
     /**
      * Remove token by zero-based index.
      *
+     * @remarks
+     * Out-of-range indexes are ignored.
+     *
      * @param index - Token index.
      */
     public remove(index: u32): void;
@@ -44,9 +53,9 @@ declare module "xray16" {
      * Get token text by zero-based index.
      *
      * @param index - Token index.
-     * @returns Token text.
+     * @returns Token text, or `null` from native code when index is out of range.
      */
-    public get(index: u32): string;
+    public get(index: u32): string | null;
 
     /**
      * Get number of tokens in the list.
@@ -74,6 +83,9 @@ declare module "xray16" {
    * @source C++ class token_list
    * @customConstructor token_list
    * @group xr_properties
+   *
+   * @remarks
+   * The native list keeps a trailing sentinel entry for editor APIs; script code only works with named entries.
    */
   export class token_list {
     /**
@@ -84,6 +96,9 @@ declare module "xray16" {
     /**
      * Remove token by text.
      *
+     * @remarks
+     * Missing tokens are logged and otherwise ignored.
+     *
      * @param token - Token text.
      */
     public remove(token: string): void;
@@ -91,14 +106,20 @@ declare module "xray16" {
     /**
      * Find numeric id for a token.
      *
+     * @remarks
+     * The token must exist. Native code verifies the lookup result.
+     *
      * @param token - Token text.
-     * @returns Token id, or engine-defined missing value.
+     * @returns Token id.
      */
     public id(token: string): i32;
 
     /**
      * Find token text by numeric id.
      *
+     * @remarks
+     * The id must exist. Native code verifies the lookup result.
+     *
      * @param id - Token id.
      * @returns Token text.
      */
@@ -107,6 +128,9 @@ declare module "xray16" {
     /**
      * Add a token/id pair.
      *
+     * @remarks
+     * Both token text and id must be unique in the list.
+     *
      * @param token - Token text.
      * @param id - Numeric token id.
      */
@@ -124,11 +148,18 @@ declare module "xray16" {
    * @source C++ class properties_list_helper
    * @customConstructor properties_list_helper
    * @group xr_properties
+   *
+   * @remarks
+   * This is an editor bridge. Most methods require a real editor property item list and a server object that owns
+   * the wrapped field; they are not useful in ordinary gameplay scripts.
    */
   export class properties_list_helper extends EngineBinding {
     /**
      * Create a 3-axis angle property.
      *
+     * @remarks
+     * Bound object field must be an `Fvector`.
+     *
      * @returns Engine property value handle.
      */
     public create_vangle(): unknown;
@@ -136,6 +167,9 @@ declare module "xray16" {
     /**
      * Create an angle property.
      *
+     * @remarks
+     * Bound object field must be a float.
+     *
      * @returns Engine property value handle.
      */
     public create_angle(): unknown;
@@ -143,6 +177,9 @@ declare module "xray16" {
     /**
      * Create a time property.
      *
+     * @remarks
+     * Bound object field must be a float.
+     *
      * @returns Engine property value handle.
      */
     public create_time(): unknown;
@@ -150,6 +187,9 @@ declare module "xray16" {
     /**
      * Create a color property.
      *
+     * @remarks
+     * Bound object field must be a 32-bit color value.
+     *
      * @returns Engine property value handle.
      */
     public create_color(): unknown;
@@ -157,6 +197,9 @@ declare module "xray16" {
     /**
      * Create a vector color property.
      *
+     * @remarks
+     * Bound object field must be an `Fvector`.
+     *
      * @returns Engine property value handle.
      */
     public create_vcolor(): unknown;
@@ -164,6 +207,9 @@ declare module "xray16" {
     /**
      * Create a float color property.
      *
+     * @remarks
+     * Bound object field must be an `Fcolor`.
+     *
      * @returns Engine property value handle.
      */
     public create_fcolor(): unknown;
@@ -171,6 +217,9 @@ declare module "xray16" {
     /**
      * Create a runtime token list property.
      *
+     * @remarks
+     * Requires an `rtoken_list`; keep it alive while the editor property uses it.
+     *
      * @returns Engine property value handle.
      */
     public create_list(): unknown;
@@ -178,6 +227,9 @@ declare module "xray16" {
     /**
      * Create an 8-bit token property.
      *
+     * @remarks
+     * Requires a `token_list`; ids must fit into an unsigned 8-bit value.
+     *
      * @returns Engine property value handle.
      */
     public create_token8(): unknown;
@@ -185,6 +237,9 @@ declare module "xray16" {
     /**
      * Create a 16-bit token property.
      *
+     * @remarks
+     * Requires a `token_list`; ids must fit into an unsigned 16-bit value.
+     *
      * @returns Engine property value handle.
      */
     public create_token16(): unknown;
@@ -192,6 +247,9 @@ declare module "xray16" {
     /**
      * Create a 32-bit token property.
      *
+     * @remarks
+     * Requires a `token_list`; ids are stored as unsigned 32-bit values.
+     *
      * @returns Engine property value handle.
      */
     public create_token32(): unknown;
@@ -199,6 +257,9 @@ declare module "xray16" {
     /**
      * Create an 8-bit flag property.
      *
+     * @remarks
+     * Binds individual bit toggles to an unsigned 8-bit integer field.
+     *
      * @returns Engine property value handle.
      */
     public create_flag8(): unknown;
@@ -206,6 +267,9 @@ declare module "xray16" {
     /**
      * Create a 16-bit flag property.
      *
+     * @remarks
+     * Binds individual bit toggles to an unsigned 16-bit integer field.
+     *
      * @returns Engine property value handle.
      */
     public create_flag16(): unknown;
@@ -213,6 +277,9 @@ declare module "xray16" {
     /**
      * Create a 32-bit flag property.
      *
+     * @remarks
+     * Binds individual bit toggles to an unsigned 32-bit integer field.
+     *
      * @returns Engine property value handle.
      */
     public create_flag32(): unknown;
@@ -220,6 +287,9 @@ declare module "xray16" {
     /**
      * Create a vector property.
      *
+     * @remarks
+     * Bound object field must be an `Fvector`.
+     *
      * @returns Engine property value handle.
      */
     public create_vector(): unknown;
@@ -227,6 +297,9 @@ declare module "xray16" {
     /**
      * Create a boolean property bound to an object field.
      *
+     * @remarks
+     * The native helper wraps `value[id]` and attaches the wrapper to `object`, so `object` must be a server object.
+     *
      * @param items - Property item list to append to.
      * @param path - Property path or caption.
      * @param object - Spawn object owning the property.
@@ -245,6 +318,9 @@ declare module "xray16" {
     /**
      * Create a float property.
      *
+     * @remarks
+     * Bound object field must be a float. Native overloads may also carry min/max/default editor values.
+     *
      * @returns Engine property value handle.
      */
     public create_float(): unknown;
@@ -252,6 +328,9 @@ declare module "xray16" {
     /**
      * Create an unsigned 8-bit integer property.
      *
+     * @remarks
+     * Bound object field must fit into an unsigned 8-bit value.
+     *
      * @returns Engine property value handle.
      */
     public create_u8(): unknown;
@@ -259,6 +338,9 @@ declare module "xray16" {
     /**
      * Create an unsigned 16-bit integer property.
      *
+     * @remarks
+     * Bound object field must fit into an unsigned 16-bit value.
+     *
      * @returns Engine property value handle.
      */
     public create_u16(): unknown;
@@ -266,6 +348,9 @@ declare module "xray16" {
     /**
      * Create an unsigned 32-bit integer property.
      *
+     * @remarks
+     * Bound object field must fit into an unsigned 32-bit value.
+     *
      * @returns Engine property value handle.
      */
     public create_u32(): unknown;
@@ -273,6 +358,9 @@ declare module "xray16" {
     /**
      * Create a signed 32-bit integer property.
      *
+     * @remarks
+     * Bound object field must fit into a signed 32-bit value.
+     *
      * @returns Engine property value handle.
      */
     public create_s32(): unknown;
@@ -280,6 +368,9 @@ declare module "xray16" {
     /**
      * Create a signed 16-bit integer property.
      *
+     * @remarks
+     * Bound object field must fit into a signed 16-bit value.
+     *
      * @returns Engine property value handle.
      */
     public create_s16(): unknown;
@@ -287,6 +378,9 @@ declare module "xray16" {
     /**
      * Create an asset/object chooser property.
      *
+     * @remarks
+     * Requires a chooser mode and a string-like field that receives the selected section, asset, or path.
+     *
      * @returns Engine property value handle.
      */
     public create_choose(): unknown;
@@ -294,6 +388,9 @@ declare module "xray16" {
     /**
      * Create a button property.
      *
+     * @remarks
+     * Editor-only command row. Use it to expose an action callback, not persistent object data.
+     *
      * @returns Engine property value handle.
      */
     public create_button(): unknown;
@@ -301,6 +398,9 @@ declare module "xray16" {
     /**
      * Create a custom canvas property.
      *
+     * @remarks
+     * Editor-only drawing surface for custom property UI.
+     *
      * @returns Engine property value handle.
      */
     public create_canvas(): unknown;
@@ -308,6 +408,9 @@ declare module "xray16" {
     /**
      * Create a read-only caption row.
      *
+     * @remarks
+     * Editor-only label row used to group or explain nearby properties.
+     *
      * @returns Engine property value handle.
      */
     public create_caption(): unknown;
@@ -315,6 +418,9 @@ declare module "xray16" {
     /**
      * Callback used after editing a float property.
      *
+     * @remarks
+     * Editor bridge callback. Native code passes the edited value through an output argument.
+     *
      * @returns Engine callback result.
      */
     public float_on_after_edit(): unknown;
@@ -322,6 +428,9 @@ declare module "xray16" {
     /**
      * Callback used before editing a float property.
      *
+     * @remarks
+     * Editor bridge callback. Native code passes the current value through an output argument.
+     *
      * @returns Engine callback result.
      */
     public float_on_before_edit(): unknown;
@@ -329,6 +438,9 @@ declare module "xray16" {
     /**
      * Callback used after editing an object name.
      *
+     * @remarks
+     * Editor bridge callback. Native code passes the edited name through an output argument.
+     *
      * @returns Engine callback result.
      */
     public name_after_edit(): unknown;
@@ -336,6 +448,9 @@ declare module "xray16" {
     /**
      * Callback used before editing an object name.
      *
+     * @remarks
+     * Editor bridge callback. Native code passes the current name through an output argument.
+     *
      * @returns Engine callback result.
      */
     public name_before_edit(): unknown;
@@ -343,6 +458,9 @@ declare module "xray16" {
     /**
      * Callback used before editing a vector property.
      *
+     * @remarks
+     * Editor bridge callback for vector rows, usually used to prepare a value before the editor opens.
+     *
      * @returns Engine callback result.
      */
     public vector_on_before_edit(): unknown;
@@ -350,6 +468,9 @@ declare module "xray16" {
     /**
      * Callback used after editing a vector property.
      *
+     * @remarks
+     * Editor bridge callback for vector rows, usually used to accept or normalize the edited value.
+     *
      * @returns Engine callback result.
      */
     public vector_on_after_edit(): unknown;
@@ -361,7 +482,10 @@ declare module "xray16" {
    * @source C++ class properties_helper
    * @customConstructor properties_helper
    * @group xr_properties
-   * @remarks Only available when the editor property helper library is loaded.
+   *
+   * @remarks
+   * Only available when the editor property helper library is loaded. Outside that context the native accessor logs
+   * an error and returns no usable helper.
    */
   export class properties_helper extends properties_list_helper {}
 
@@ -371,11 +495,18 @@ declare module "xray16" {
    * @source C++ class prop_value
    * @customConstructor prop_value
    * @group xr_properties
+   *
+   * @remarks
+   * These helpers are downcasts to concrete editor property value types. Use only when the property was created as
+   * that matching kind.
    */
   export class prop_value {
     /**
      * Treat this property value as a 16-bit token value.
      *
+     * @remarks
+     * Use only for properties originally created as 16-bit token values.
+     *
      * @returns Engine property value handle.
      */
     public token16_value(): unknown;
@@ -383,6 +514,9 @@ declare module "xray16" {
     /**
      * Treat this property value as a 32-bit flag value.
      *
+     * @remarks
+     * Use only for properties originally created as 32-bit flag values.
+     *
      * @returns Engine property value handle.
      */
     public flag32_value(): unknown;
@@ -390,6 +524,9 @@ declare module "xray16" {
     /**
      * Treat this property value as text.
      *
+     * @remarks
+     * Use only for properties originally created as text values.
+     *
      * @returns Engine property value handle.
      */
     public text_value(): unknown;
@@ -397,6 +534,9 @@ declare module "xray16" {
     /**
      * Treat this property value as a boolean.
      *
+     * @remarks
+     * Use only for properties originally created as boolean values.
+     *
      * @returns Engine property value handle.
      */
     public bool_value(): unknown;
@@ -404,6 +544,9 @@ declare module "xray16" {
     /**
      * Treat this property value as an unsigned 16-bit integer.
      *
+     * @remarks
+     * Use only for properties originally created as unsigned 16-bit values.
+     *
      * @returns Engine property value handle.
      */
     public u16_value(): unknown;
@@ -411,6 +554,9 @@ declare module "xray16" {
     /**
      * Treat this property value as a signed 16-bit integer.
      *
+     * @remarks
+     * Use only for properties originally created as signed 16-bit values.
+     *
      * @returns Engine property value handle.
      */
     public s16_value(): unknown;
@@ -418,6 +564,9 @@ declare module "xray16" {
     /**
      * Treat this property value as a button.
      *
+     * @remarks
+     * Use only for properties originally created as button rows.
+     *
      * @returns Engine property value handle.
      */
     public button_value(): unknown;
@@ -425,6 +574,9 @@ declare module "xray16" {
     /**
      * Treat this property value as a caption.
      *
+     * @remarks
+     * Use only for properties originally created as caption rows.
+     *
      * @returns Engine property value handle.
      */
     public caption_value(): unknown;
@@ -436,6 +588,9 @@ declare module "xray16" {
    * @source C++ class TEX_INFO
    * @customConstructor TEX_INFO
    * @group xr_properties
+   *
+   * @remarks
+   * Metadata is borrowed from the engine UI texture atlas; use it for inspection, not ownership.
    */
   export class TEX_INFO {
     /**