xray16 1.5.1 → 1.5.3

package/README.md

@@ -1,5 +1,6 @@
 # [📡 XRay-16 engine typescript definitions](https://github.com/xray-forge/xray-16-types)
 
+[![npm version](https://img.shields.io/npm/v/xray16)](https://www.npmjs.com/package/xray16)
 [![types](https://img.shields.io/badge/docs-types-blue.svg?style=flat)](https://xray-forge.github.io/xray-16-types/index.html)
 [![book](https://img.shields.io/badge/docs-book-blue.svg?style=flat)](https://xray-forge.github.io/stalker-xrf-book)
 <br/>
@@ -105,7 +106,7 @@ Lua does not provide convenient API do get filename in runtime and static step i
 Plugin to simplify casting from `LuaTable` to typescript array/map objects.\
 All the calls are completely gets stripped and removed from runtime.
 
-### from_cast_utils
+### inject_tracy_zones
 
 Plugin designed to work specifically with [tracy profiler](https://github.com/wolfpld/tracy).\
 Once it is enabled with env variable or path parameter, tracy zone marking calls are injected for every method.\

package/package.json

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

package/plugins/from_cast_utils.js

@@ -1,8 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const typescript_1 = require("typescript");
+const lua = require("typescript-to-lua");
 const diagnostics_1 = require("./utils/diagnostics");
 const FROM_CAST_METHODS = ["$fromObject", "$fromArray", "$fromLuaArray", "$fromLuaTable"];
+const NIL_CHECK_METHODS = new Map([
+    ["$isNil", lua.SyntaxKind.EqualityOperator],
+    ["$isNotNil", lua.SyntaxKind.InequalityOperator],
+]);
 /**
  * Push generic error to notify about usage issue.
  */
@@ -22,6 +27,13 @@ const plugin = {
                 }
                 return context.transformExpression(node.arguments[0]);
             }
+            if ((0, typescript_1.isIdentifier)(node.expression) && NIL_CHECK_METHODS.has(node.expression.text)) {
+                if (node.arguments.length !== 1) {
+                    context.diagnostics.push(createInvalidFunctionCallError(node));
+                    return context.superTransformExpression(node);
+                }
+                return lua.createBinaryExpression(context.transformExpression(node.arguments[0]), lua.createNilLiteral(node), NIL_CHECK_METHODS.get(node.expression.text), node);
+            }
             return context.superTransformExpression(node);
         },
     },

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.
    *
@@ -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;
   }
 
   /**

package/types/xr_object/script/xr_script_object.d.ts

@@ -1649,15 +1649,6 @@ declare module "xray16" {
      */
     public get_current_point_index(): u32;
 
-    /**
-     * @remarks
-     * Requires this object to be a base monster. Other object types log a script error and return a
-     * default value or do nothing.
-     *
-     * @returns Whether monster anti-aim is forced.
-     */
-    public get_force_anti_aim(): boolean;
-
     /**
      * Cast this object to a hanging lamp.
      *

package/types/xrf_plugin.d.ts

@@ -13,6 +13,26 @@ declare global {
    */
   const $dirname: string;
 
+  /**
+   * Check whether a value is nil-compatible in Lua and Jest runtimes.
+   *
+   * @group xrf_plugin
+   *
+   * @param value - Value to check.
+   * @returns Whether value is `null` or `undefined`.
+   */
+  function $isNil<T>(value: T): value is null | undefined;
+
+  /**
+   * Check whether a value is not nil-compatible in Lua and Jest runtimes.
+   *
+   * @group xrf_plugin
+   *
+   * @param value - Value to check.
+   * @returns Whether value is neither `null` nor `undefined`.
+   */
+  function $isNotNil<T>(value: T): value is NonNullable<T>;
+
   /**
    * Treat a TypeScript array as a Lua array.
    *