xray16 1.5.3 → 1.6.0

package/README.md

@@ -61,6 +61,7 @@ Plugins can be included in [tstl tsconfig](https://typescripttolua.github.io/doc
       { "name": "xray16/plugins/strip_lua_logger" },
       { "name": "xray16/plugins/inject_filename" },
       { "name": "xray16/plugins/from_cast_utils" },
+      { "name": "xray16/plugins/optimize_return_ternary" },
       { "name": "xray16/plugins/inject_tracy_zones" }
     ]
   }
@@ -106,6 +107,11 @@ 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.
 
+### optimize_return_ternary
+
+Plugin rewrites returned ternary expressions into direct `if` / `else` branch returns when it is safe.\
+This avoids temporary result locals for patterns like `return condition ? first : second` while preserving general ternary semantics.
+
 ### inject_tracy_zones
 
 Plugin designed to work specifically with [tracy profiler](https://github.com/wolfpld/tracy).\

package/package.json

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

package/plugins/optimize_return_ternary.d.ts

@@ -0,0 +1,6 @@
+import { type Plugin } from "typescript-to-lua";
+/**
+ * Plugin that rewrites returned ternary expressions as direct branch returns.
+ */
+declare const plugin: Plugin;
+export default plugin;

package/plugins/optimize_return_ternary.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const ts = require("typescript");
+const lua = require("typescript-to-lua");
+const assignment_validation_1 = require("typescript-to-lua/dist/transformation/utils/assignment-validation");
+const preceding_statements_1 = require("typescript-to-lua/dist/transformation/utils/preceding-statements");
+const conditional_1 = require("typescript-to-lua/dist/transformation/visitors/conditional");
+const multi_1 = require("typescript-to-lua/dist/transformation/visitors/language-extensions/multi");
+const return_1 = require("typescript-to-lua/dist/transformation/visitors/return");
+function getConditionalExpression(expression) {
+    let current = expression;
+    while (ts.isParenthesizedExpression(current) ||
+        ts.isAsExpression(current) ||
+        ts.isTypeAssertionExpression(current) ||
+        ts.isNonNullExpression(current) ||
+        ts.isSatisfiesExpression(current)) {
+        current = current.expression;
+    }
+    return ts.isConditionalExpression(current) ? current : null;
+}
+function hasMultiReturnBranch(context, expression) {
+    return ((0, multi_1.isMultiReturnType)(context.checker.getTypeAtLocation(expression.whenTrue)) ||
+        (0, multi_1.isMultiReturnType)(context.checker.getTypeAtLocation(expression.whenFalse)));
+}
+function transformExpressionToReturnStatements(context, statement, expression) {
+    const conditionalExpression = getConditionalExpression(expression);
+    if (conditionalExpression !== null && !hasMultiReturnBranch(context, conditionalExpression)) {
+        return transformConditionalReturnStatement(context, statement, conditionalExpression);
+    }
+    const value = (0, preceding_statements_1.transformInPrecedingStatementScope)(context, () => context.transformExpression(expression));
+    return [...value.precedingStatements, (0, return_1.createReturnStatement)(context, [value.result], statement)];
+}
+function transformConditionalReturnStatement(context, statement, expression) {
+    (0, conditional_1.checkOnlyTruthyCondition)(expression.condition, context);
+    const condition = (0, preceding_statements_1.transformInPrecedingStatementScope)(context, () => context.transformExpression(expression.condition));
+    const whenTrue = transformExpressionToReturnStatements(context, statement, expression.whenTrue);
+    const whenFalse = transformExpressionToReturnStatements(context, statement, expression.whenFalse);
+    return [
+        ...condition.precedingStatements,
+        lua.createIfStatement(condition.result, lua.createBlock(whenTrue), lua.createBlock(whenFalse), expression),
+    ];
+}
+/**
+ * Plugin that rewrites returned ternary expressions as direct branch returns.
+ */
+const plugin = {
+    visitors: {
+        [ts.SyntaxKind.ReturnStatement]: (statement, context) => {
+            if (statement.expression === undefined) {
+                return context.superTransformStatements(statement);
+            }
+            const expression = getConditionalExpression(statement.expression);
+            if (expression === null || hasMultiReturnBranch(context, expression)) {
+                return context.superTransformStatements(statement);
+            }
+            const expressionType = context.checker.getTypeAtLocation(statement.expression);
+            const returnType = context.checker.getContextualType(statement.expression);
+            if (returnType !== undefined) {
+                (0, assignment_validation_1.validateAssignment)(context, statement, expressionType, returnType);
+            }
+            return transformConditionalReturnStatement(context, statement, expression);
+        },
+    },
+};
+exports.default = plugin;

package/types/internal.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Internal helper for engine APIs that accept Lua nil values.
+ */
+export type Nillable<T> = T | null | undefined;
+
+export type Nullable<T> = T | null;

package/types/xr_ai/xr_action.d.ts

@@ -818,9 +818,10 @@ declare module "xray16" {
   export class patrol extends EngineBinding {
     /**
      * Engine enum value for `patrol.stop`.
+     *
+     * @source `src/xrAICore/Navigation/PatrolPath/patrol_path_params_script.cpp`, route stop enum.
      */
     public static readonly stop: 0;
-    // Public static readonly stop: 1;
 
     /**
      * Engine enum value for `patrol.start`.

package/types/xr_ai/xr_alife.d.ts

@@ -1,3 +1,5 @@
+import type { Nillable, Nullable } from "../internal";
+
 declare module "xray16" {
   /**
    * Access point for ALife simulation objects and registries.
@@ -123,7 +125,7 @@ declare module "xray16" {
      * @param object - Object to remove.
      * @param flag - Compatibility flag accepted by the engine binding.
      */
-    public release(object: cse_alife_object | null, flag: boolean): void;
+    public release(object: Nillable<cse_alife_object>, flag: boolean): void;
 
     /**
      * Remove all restrictions of one type from an object.
@@ -212,7 +214,7 @@ declare module "xray16" {
      * @param storyId - Story id.
      * @returns Matching server object, or `null` when it is not registered.
      */
-    public story_object(storyId: u32): cse_alife_object | null;
+    public story_object(storyId: u32): Nullable<cse_alife_object>;
 
     /**
      * @returns Alife server-client switch distance.
@@ -287,7 +289,7 @@ declare module "xray16" {
      * @param no_assert - Return `null` instead of asserting when the object is missing.
      * @returns Matching server object, or `null`.
      */
-    public object<T extends cse_alife_object = cse_alife_object>(object_id: u16, no_assert?: boolean): T | null;
+    public object<T extends cse_alife_object = cse_alife_object>(object_id: u16, no_assert?: boolean): Nullable<T>;
 
     /**
      * Get a server object by its engine replacement name.
@@ -295,7 +297,7 @@ declare module "xray16" {
      * @param name - Server object replacement name.
      * @returns Matching server object, or `null`.
      */
-    public object<T extends cse_alife_object = cse_alife_object>(name: string): T | null;
+    public object<T extends cse_alife_object = cse_alife_object>(name: string): Nullable<T>;
 
     /**
      * Create an object from a spawn graph id.

package/types/xr_ai/xr_goap.d.ts

@@ -1,3 +1,5 @@
+import type { Nillable } from "../internal";
+
 declare module "xray16" {
   /**
    * GOAP property and action id constants for stalker AI.
@@ -646,13 +648,13 @@ declare module "xray16" {
     /**
      * @param object - Target game object to work with, `null` is OK since correct object will be injected on setup.
      */
-    public constructor(object: game_object | null);
+    public constructor(object: Nillable<game_object>);
 
     /**
      * @param object - Target game object to work with, `null` is OK since correct object will be injected on setup.
      * @param name - Name of the evaluator, used for debug purposes mainly.
      */
-    public constructor(object: game_object | null, name: string);
+    public constructor(object: Nillable<game_object>, name: string);
 
     /**
      * Handle setup of the evaluator and binding to a specific object.
@@ -715,13 +717,13 @@ declare module "xray16" {
     /**
      * @param object - Target game object to work with, `null` is OK since correct object will be injected on setup.
      */
-    public constructor(object?: game_object | null);
+    public constructor(object?: Nillable<game_object>);
 
     /**
      * @param object - Target game object to work with, `null` is OK since correct object will be injected on setup.
      * @param name - Name of the action, used for debug purposes mainly.
      */
-    public constructor(object: game_object | null, name: string);
+    public constructor(object: Nillable<game_object>, name: string);
 
     /**
      * Handle setup of the action and binding to a specific object.
@@ -1000,13 +1002,13 @@ declare module "xray16" {
     /**
      * @param object - Target game object to work with, `null` is OK since correct object will be injected on setup.
      */
-    public constructor(object?: game_object | null);
+    public constructor(object?: Nillable<game_object>);
 
     /**
      * @param object - Target game object to work with, `null` is OK since correct object will be injected on setup.
      * @param name - Name of the action, used for debug purposes mainly.
      */
-    public constructor(object: game_object | null, name: string);
+    public constructor(object: Nillable<game_object>, name: string);
 
     /**
      * Lifecycle method called once on action execution start.

package/types/xr_ai/xr_memory.d.ts

@@ -1,3 +1,5 @@
+import type { Nullable } from "../internal";
+
 declare module "xray16" {
   /**
    * Base memory record with timing information.
@@ -352,7 +354,7 @@ declare module "xray16" {
      *
      * @returns Source object, or `null` when the source is not a game object.
      */
-    public object(): game_object | null;
+    public object(): Nullable<game_object>;
 
     /**
      * @returns How the danger was perceived.
@@ -367,7 +369,7 @@ declare module "xray16" {
      *
      * @returns Dependent object, or `null` when there is none.
      */
-    public dependent_object(): game_object | null;
+    public dependent_object(): Nullable<game_object>;
   }
 
   /**

package/types/xr_lib/xr_debug.d.ts

@@ -1,3 +1,5 @@
+import type { Nullable } from "../internal";
+
 declare module "xray16" {
   /**
    * Engine console interface.
@@ -97,7 +99,7 @@ declare module "xray16" {
      * @param key - Console variable name.
      * @returns String value.
      */
-    public get_string(key: string): string | null;
+    public get_string(key: string): Nullable<string>;
 
     /**
      * Read console variable token text.
@@ -108,7 +110,7 @@ declare module "xray16" {
      * @param key - Console variable name.
      * @returns Token text.
      */
-    public get_token(key: string): string | null;
+    public get_token(key: string): Nullable<string>;
   }
 
   /**

package/types/xr_lib/xr_fs.d.ts

@@ -1,3 +1,5 @@
+import type { Nillable, Nullable } from "../internal";
+
 declare module "xray16" {
   /**
    * File list returned by the engine filesystem.
@@ -437,7 +439,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 | null;
+    public exist(alias: string, filename: string, fs_type: TXR_fs_type): Nullable<FileStatus>;
 
     /**
      * Check whether a file exists below a path alias.
@@ -449,7 +451,7 @@ declare module "xray16" {
      * @param filename - File name.
      * @returns File descriptor pointer or `null`.
      */
-    public exist(alias: string, filename: string): i32 | null;
+    public exist(alias: string, filename: string): Nullable<i32>;
 
     /**
      * Check whether a file exists.
@@ -460,7 +462,7 @@ declare module "xray16" {
      * @param path - File path.
      * @returns File descriptor pointer or `null`.
      */
-    public exist(path: string): i32 | null;
+    public exist(path: string): Nullable<i32>;
 
     /**
      * Check whether a file exists.
@@ -472,7 +474,7 @@ declare module "xray16" {
      * @param fs_type - Filesystem source to search.
      * @returns File status.
      */
-    public exist(path: string, fs_type: TXR_fs_type): FileStatus | null;
+    public exist(path: string, fs_type: TXR_fs_type): Nullable<FileStatus>;
 
     /**
      * Add a path alias.
@@ -562,7 +564,7 @@ declare module "xray16" {
      *
      * @param writer - Writer returned by `w_open`.
      */
-    public w_close(writer: IWriter | null): void;
+    public w_close(writer: Nillable<IWriter>): void;
 
     /**
      * Open a binary writer below a path alias.
@@ -574,7 +576,7 @@ declare module "xray16" {
      * @param filename - Relative file path.
      * @returns Binary writer, or `null`.
      */
-    public w_open(path: string, filename: string): IWriter | null;
+    public w_open(path: string, filename: string): Nullable<IWriter>;
 
     /**
      * Open a binary writer.
@@ -585,7 +587,7 @@ declare module "xray16" {
      * @param path - File path.
      * @returns Binary writer, or `null`.
      */
-    public w_open(path: string): IWriter | null;
+    public w_open(path: string): Nullable<IWriter>;
   }
 
   /**

package/types/xr_lib/xr_game.d.ts

@@ -59,26 +59,26 @@ declare module "xray16" {
      */
     public static readonly GAME_DEATHMATCH: 2;
 
-    //	GAME_CTF							= 3,
-    //	GAME_ASSAULT						= 4,	// Team1 - assaulting, Team0 - Defending
-
     /**
      * Engine enum value for `GAME_TYPE.GAME_CS`.
      */
     public static readonly GAME_CS: 5;
+
     /**
      * Engine enum value for `GAME_TYPE.GAME_TEAMDEATHMATCH`.
      */
     public static readonly GAME_TEAMDEATHMATCH: 6;
+
     /**
      * Engine enum value for `GAME_TYPE.GAME_ARTEFACTHUNT`.
      */
     public static readonly GAME_ARTEFACTHUNT: 7;
+
     /**
      * Engine enum value for `GAME_TYPE.GAME_CAPTURETHEARTEFACT`.
      */
     public static readonly GAME_CAPTURETHEARTEFACT: 8;
-    // Identifiers in range [100...254] are registered for script game type
+
     /**
      * Engine enum value for `GAME_TYPE.GAME_DUMMY`.
      */

package/types/xr_lib/xr_hit.d.ts

@@ -1,3 +1,5 @@
+import type { Nullable } from "../internal";
+
 declare module "xray16" {
   /**
    * Hit packet that can be sent to game objects.
@@ -70,7 +72,7 @@ declare module "xray16" {
      * @remarks
      * Leave `null` for world or scripted damage that should not be attributed to a game object.
      */
-    public draftsman: game_object | null;
+    public draftsman: Nullable<game_object>;
 
     /**
      * Physics impulse applied with the hit.

package/types/xr_lib/xr_ini.d.ts

@@ -1,3 +1,5 @@
+import type { Nillable } from "../internal";
+
 declare module "xray16" {
   /**
    * LTX/INI file reader and writer.
@@ -74,7 +76,7 @@ declare module "xray16" {
      * @param section - Section name.
      * @returns Whether the section exists.
      */
-    public section_exist(section: string | null): boolean;
+    public section_exist(section: Nillable<string>): boolean;
 
     /**
      * Read a floating-point value.
@@ -198,7 +200,7 @@ declare module "xray16" {
      * @param field - Section field to check.
      * @returns Whether line exists.
      */
-    public line_exist(section: string | null, field: string): boolean;
+    public line_exist(section: Nillable<string>, field: string): boolean;
 
     /**
      * Write a 2D vector value.

package/types/xr_lib/xr_level.d.ts

@@ -1,3 +1,5 @@
+import type { Nillable, Nullable } from "../internal";
+
 declare module "xray16" {
   /**
    * Global helpers for the currently loaded level.
@@ -243,7 +245,7 @@ declare module "xray16" {
      *
      * @returns Target object, or `null` when nothing is targeted.
      */
-    get_target_obj(this: void): game_object | null;
+    get_target_obj(this: void): Nullable<game_object>;
 
     /**
      * Get current game day count.
@@ -437,7 +439,7 @@ declare module "xray16" {
      * @param object_id - Game object id.
      * @returns Matching object, or `null` when it is not online.
      */
-    object_by_id(this: void, object_id: u16): game_object | null;
+    object_by_id(this: void, object_id: u16): Nullable<game_object>;
 
     /**
      * Check whether a patrol path exists on this level.
@@ -782,7 +784,7 @@ declare module "xray16" {
       range: f32,
       target: unknown,
       result: unknown,
-      ignore_object: game_object | null
+      ignore_object: Nillable<game_object>
     ): boolean;
   }
 

package/types/xr_lib/xr_map.d.ts

@@ -1,3 +1,5 @@
+import type { Nullable } from "../internal";
+
 declare module "xray16" {
   /**
    * Manages active PDA/minimap locations.
@@ -95,7 +97,7 @@ declare module "xray16" {
      *
      * @returns Hint text shown for the spot.
      */
-    public GetHint(): string | null;
+    public GetHint(): Nullable<string>;
 
     /**
      * @remarks

package/types/xr_lib/xr_multiplayer.d.ts

@@ -1,3 +1,5 @@
+import type { Nillable, Nullable } from "../internal";
+
 declare module "xray16" {
   /**
    * Metadata stored inside a recorded multiplayer demo.
@@ -356,7 +358,7 @@ declare module "xray16" {
      *
      * @returns Current logged-in profile, or null when offline.
      */
-    public get_current_profile(): profile | null;
+    public get_current_profile(): Nullable<profile>;
 
     /**
      * @returns Saved email from registry.
@@ -548,7 +550,7 @@ declare module "xray16" {
      * @param object - Lua object used as callback `this`.
      * @param cb - Called with login profile and status description.
      */
-    public constructor(object: object, cb: (this: object, profile: profile | null, description: string) => void);
+    public constructor(object: object, cb: (this: object, profile: Nillable<profile>, description: string) => void);
 
     /**
      * Replace the bound callback.
@@ -556,7 +558,7 @@ declare module "xray16" {
      * @param object - Lua object used as callback `this`.
      * @param cb - Called with login profile and status description.
      */
-    public bind(object: object, cb: (this: object, profile: profile | null, description: string) => void): void;
+    public bind(object: object, cb: (this: object, profile: Nillable<profile>, description: string) => void): void;
 
     /**
      * Clear the bound callback.

package/types/xr_lib/xr_properties.d.ts

@@ -1,3 +1,5 @@
+import type { Nullable } from "../internal";
+
 declare module "xray16" {
   /**
    * Named integer token used by editor property lists.
@@ -55,7 +57,7 @@ declare module "xray16" {
      * @param index - Token index.
      * @returns Token text, or `null` from native code when index is out of range.
      */
-    public get(index: u32): string | null;
+    public get(index: u32): Nullable<string>;
 
     /**
      * Get number of tokens in the list.

package/types/xr_lib/xr_save.d.ts

@@ -1,3 +1,5 @@
+import type { Nillable } from "../internal";
+
 declare module "xray16" {
   /**
    * Network client identifier.
@@ -507,7 +509,7 @@ declare module "xray16" {
      *
      * @param value - String value.
      */
-    public w_stringZ(value: string | null): void;
+    public w_stringZ(value: Nillable<string>): void;
 
     /**
      * Get current write cursor offset.

package/types/xr_lib/xr_sound.d.ts

@@ -1,3 +1,5 @@
+import type { Nillable } from "../internal";
+
 declare module "xray16" {
   /**
    * Current playback parameters for a launched sound.
@@ -164,7 +166,7 @@ declare module "xray16" {
      *
      * @param object - Object used as sound owner.
      */
-    public play(object: game_object | null): void;
+    public play(object: Nillable<game_object>): void;
 
     /**
      * Play the sound after a delay.
@@ -174,7 +176,7 @@ declare module "xray16" {
      * @param object - Object used as sound owner.
      * @param delay - Delay in seconds.
      */
-    public play(object: game_object | null, delay: f32): void;
+    public play(object: Nillable<game_object>, delay: f32): void;
 
     /**
      * Play the sound with engine sound flags.
@@ -185,7 +187,7 @@ declare module "xray16" {
      * @param delay - Delay in seconds.
      * @param flags - Playback flags such as `sound_object.looped` or `sound_object.s2d`.
      */
-    public play(object: game_object | null, delay: f32, flags: i32): void;
+    public play(object: Nillable<game_object>, delay: f32, flags: i32): void;
 
     /**
      * Play the sound at a fixed world position.
@@ -195,7 +197,7 @@ declare module "xray16" {
      * @param object - Optional object used as sound owner.
      * @param position - World position for playback.
      */
-    public play_at_pos(object: game_object | null, position: vector): void;
+    public play_at_pos(object: Nillable<game_object>, position: vector): void;
 
     /**
      * Play the sound at a fixed world position after a delay.
@@ -206,7 +208,7 @@ declare module "xray16" {
      * @param position - World position for playback.
      * @param delay - Delay in seconds.
      */
-    public play_at_pos(object: game_object | null, position: vector, delay: f32): void;
+    public play_at_pos(object: Nillable<game_object>, position: vector, delay: f32): void;
 
     /**
      * Play the sound at a fixed world position with engine sound flags.
@@ -218,7 +220,7 @@ declare module "xray16" {
      * @param delay - Delay in seconds.
      * @param flags - Playback flags such as `sound_object.looped` or `sound_object.s2d`.
      */
-    public play_at_pos(object: game_object | null, position: vector, delay: f32, flags: i32): void;
+    public play_at_pos(object: Nillable<game_object>, position: vector, delay: f32, flags: i32): void;
 
     /**
      * Play without tracking feedback.
@@ -235,7 +237,7 @@ declare module "xray16" {
      * @param position - Optional playback position.
      * @param volume - Optional playback volume.
      */
-    public play_no_feedback(object: game_object | null, flags: i32, delay: f32, position: vector, volume: f32): void;
+    public play_no_feedback(object: Nillable<game_object>, flags: i32, delay: f32, position: vector, volume: f32): void;
 
     /**
      * Stop playback immediately.

package/types/xr_lib/xr_stats.ts

@@ -1,3 +1,5 @@
+import type { Nullable } from "../internal";
+
 declare module "xray16" {
   /**
    * Actor statistics helpers exposed through the `actor_stats` namespace.
@@ -37,7 +39,7 @@ declare module "xray16" {
      *
      * @param object_id - Object id to remove.
      */
-    remove_from_ranking(this: void, object_id: number): void | null;
+    remove_from_ranking(this: void, object_id: number): Nullable<void>;
   }
 
   /**

package/types/xr_lib/xr_task.d.ts

@@ -1,3 +1,5 @@
+import type { Nullable } from "../internal";
+
 declare module "xray16" {
   /**
    * Task state and task type constants.
@@ -102,7 +104,7 @@ declare module "xray16" {
     /**
      * @returns Objective icon name, or null when none is set.
      */
-    public get_icon_name<T extends string = string>(): T | null;
+    public get_icon_name<T extends string = string>(): Nullable<T>;
 
     /**
      * Set objective description text.

package/types/xr_lib/xr_type.d.ts

@@ -53,11 +53,6 @@ declare module "xray16" {
    */
   type u64 = number;
 
-  /**
-   * @group xr_type
-   */
-  type Maybe<T> = T | null | undefined;
-
   /**
    * @group xr_type
    */

package/types/xr_object/client/xr_level.d.ts

@@ -1,3 +1,5 @@
+import type { Nillable } from "../../internal";
+
 declare module "xray16" {
   /**
    * Campfire anomaly object.
@@ -642,7 +644,7 @@ declare module "xray16" {
      *
      * @param game_object - Enemy object, or null to clear.
      */
-    public SetEnemy(game_object: game_object | null): void;
+    public SetEnemy(game_object: Nillable<game_object>): void;
 
     /**
      * Track an enemy point.