xray16 1.5.0 → 1.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xray16",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "author": "Neloreck",
   "repository": "https://github.com/xray-forge/xray-16-types",
   "private": false,

package/types/xr_lib/xr_fs.d.ts

@@ -180,6 +180,68 @@ declare module "xray16" {
     private constructor();
   }
 
+  /**
+   * Registered filesystem path alias descriptor.
+   *
+   * @source C++ class FS_Path
+   * @customConstructor FS_Path
+   * @group xr_fs
+   *
+   * @remarks
+   * Returned by filesystem alias lookups. The object is owned by the engine filesystem. Missing aliases assert in
+   * the single-argument `get_path` binding instead of returning `null`.
+   */
+  export class FS_Path {
+    /**
+     * Resolved full path.
+     */
+    public readonly m_Path: string;
+
+    /**
+     * Root path used by this alias.
+     */
+    public readonly m_Root: string;
+
+    /**
+     * Relative path segment added to the root.
+     */
+    public readonly m_Add: string;
+
+    /**
+     * Default extension used by this alias.
+     */
+    public readonly m_DefExt: string;
+
+    /**
+     * File dialog filter caption.
+     */
+    public readonly m_FilterCaption: string;
+
+    /**
+     * Engine-created path descriptor.
+     */
+    private constructor();
+  }
+
+  /**
+   * Opaque filesystem writer handle.
+   *
+   * @source C++ class IWriter
+   * @customConstructor IWriter
+   * @group xr_fs
+   *
+   * @remarks
+   * Returned by {@link FS.w_open}. The writer class is not registered with script-callable write methods in this
+   * binding, so scripts normally only pass it back to {@link FS.w_close}. Writer creation can return `null` when
+   * native writer setup fails.
+   */
+  export class IWriter {
+    /**
+     * Engine-created writer handle.
+     */
+    private constructor();
+  }
+
   /**
    * Engine filesystem facade.
    *
@@ -375,7 +437,7 @@ declare module "xray16" {
      * @param fs_type - Filesystem source to search.
      * @returns File status.
      */
-    public exist(alias: string, filename: string, fs_type: TXR_fs_type): FileStatus;
+    public exist(alias: string, filename: string, fs_type: TXR_fs_type): FileStatus | null;
 
     /**
      * Check whether a file exists below a path alias.
@@ -410,18 +472,22 @@ declare module "xray16" {
      * @param fs_type - Filesystem source to search.
      * @returns File status.
      */
-    public exist(path: string, fs_type: TXR_fs_type): FileStatus;
+    public exist(path: string, fs_type: TXR_fs_type): FileStatus | null;
 
     /**
      * Add a path alias.
      *
+     * @remarks
+     * Native code asserts if `root` is invalid or `alias` is already registered. On success it returns a path
+     * descriptor.
+     *
      * @param alias - Alias name.
      * @param root - Root path.
      * @param path - Relative path.
      * @param recursive - Whether subfolders should be scanned.
      * @returns Native filesystem path descriptor.
      */
-    public append_path(alias: string, root: string, path: string, recursive: boolean): unknown; /* FS_Path */
+    public append_path(alias: string, root: string, path: string, recursive: boolean): FS_Path;
 
     /**
      * Check whether a path alias exists.
@@ -458,10 +524,14 @@ declare module "xray16" {
     /**
      * Get native path descriptor for an alias.
      *
+     * @remarks
+     * Native code asserts when the alias is missing. Use {@link FS.path_exist} before calling when the alias is
+     * optional.
+     *
      * @param alias - Filesystem path alias.
      * @returns Native filesystem path descriptor.
      */
-    public get_path(alias: string): unknown;
+    public get_path(alias: string): FS_Path;
 
     /**
      * Close a binary reader.
@@ -492,24 +562,30 @@ declare module "xray16" {
      *
      * @param writer - Writer returned by `w_open`.
      */
-    public w_close(writer: unknown /* IWriter */): void;
+    public w_close(writer: IWriter | null): void;
 
     /**
      * Open a binary writer below a path alias.
      *
+     * @remarks
+     * Can return `null` when native writer setup fails.
+     *
      * @param path - Filesystem path alias.
      * @param filename - Relative file path.
-     * @returns Binary writer.
+     * @returns Binary writer, or `null`.
      */
-    public w_open(path: string, filename: string): unknown; /* IWriter */
+    public w_open(path: string, filename: string): IWriter | null;
 
     /**
      * Open a binary writer.
      *
+     * @remarks
+     * Can return `null` when native writer setup fails.
+     *
      * @param path - File path.
-     * @returns Binary writer.
+     * @returns Binary writer, or `null`.
      */
-    public w_open(path: string): unknown; /* IWriter */
+    public w_open(path: string): IWriter | null;
   }
 
   /**