xray16 1.2.3 → 1.3.0

package/README.md

@@ -69,7 +69,23 @@ Following ones are available:
 - from_cast_utils - additional utils that should be removed in runtime
 - global_declarations_transform - transforms xray16 imports and removes them from runtime
 - inject_filename - adds $filename global variable to access current file name
-- strip_lua_logger - removes lua logger from runtime
+- strip_lua_logger - removes lua logger from runtime (if path param is provided or ENV variable is set)
+- inject_tracy_zones - removes lua logger from runtime (if path param is provided or ENV variable is set)
+
+Path params:
+
+- `--no-lua-logs`
+- `--inject-tracy-zones`
+
+Env variables:
+
+- `XR_NO_LUA_LOGS `
+- `XR_INJECT_TRACY_ZONES `
+
+export const IS_LUA_LOGGER_DISABLED: boolean = process.argv.includes("--no-lua-logs")
+|| process.env.NO_LUA_LOGS === "true";
+export const IS_TRACY_ZONES_INJECTION_ENABLED: boolean = process.argv.includes("--inject-tracy-zones")
+|| process.env.INJECT_TRACY_ZONES === "true";
 
 Plugins can be included in tsconfig file as following:
 
@@ -82,7 +98,8 @@ Plugins can be included in tsconfig file as following:
       { "name": "xray16/plugins/built_at_info" },
       { "name": "xray16/plugins/strip_lua_logger" },
       { "name": "xray16/plugins/inject_filename" },
-      { "name": "xray16/plugins/from_cast_utils" }
+      { "name": "xray16/plugins/from_cast_utils" },
+      { "name": "xray16/plugins/inject_tracy_zones" }
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xray16",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "author": "Neloreck",
   "repository": "https://github.com/stalker-xrts/xray-16-types",
   "private": false,

package/plugins/inject_tracy_zones.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const typescript_1 = require("typescript");
+const environment_1 = require("./utils/environment");
+const tracy_1 = require("./utils/tracy");
+const ast_1 = require("./utils/ast");
+/**
+ * Plugin that injects FILE_NAME in compile-time.
+ */
+const plugin = {
+    visitors: {
+        [typescript_1.SyntaxKind.FunctionDeclaration]: (node, context) => {
+            return context.superTransformStatements(environment_1.IS_TRACY_ZONES_INJECTION_ENABLED ? (0, tracy_1.transformWithInjectedZones)(node) : node);
+        },
+        [typescript_1.SyntaxKind.ClassDeclaration]: (node, context) => {
+            if (environment_1.IS_TRACY_ZONES_INJECTION_ENABLED) {
+                const name = node.name ? node.name.getText() : null;
+                return context.superTransformStatements(typescript_1.factory.updateClassDeclaration(node, node.modifiers, node.name, node.typeParameters, node.heritageClauses, node.members.map((it) => {
+                    if ((0, typescript_1.isMethodDeclaration)(it)) {
+                        return (0, tracy_1.transformWithInjectedZones)(it, name);
+                    }
+                    return it;
+                })));
+            }
+            return context.superTransformStatements(node);
+        },
+        [typescript_1.SyntaxKind.ExpressionStatement]: (statement, context) => {
+            if (environment_1.IS_TRACY_ZONES_INJECTION_ENABLED) {
+                const expression = statement.expression;
+                if ((0, typescript_1.isCallExpression)(expression) &&
+                    expression.expression?.kind === typescript_1.SyntaxKind.Identifier &&
+                    expression.expression.getText() === "extern" &&
+                    expression.arguments.length === 2) {
+                    const first = expression.arguments[0];
+                    const second = expression.arguments[1];
+                    if (!(0, typescript_1.isStringLiteral)(first)) {
+                        return context.transformStatements(statement);
+                    }
+                    if ((0, typescript_1.isObjectLiteralExpression)(second)) {
+                        return context.superTransformStatements(typescript_1.factory.updateExpressionStatement(statement, typescript_1.factory.updateCallExpression(expression, expression.expression, expression.typeArguments, [
+                            first,
+                            typescript_1.factory.updateObjectLiteralExpression(second, second.properties.map((it) => {
+                                if ((0, typescript_1.isPropertyAssignment)(it) && (0, typescript_1.isArrowFunction)(it.initializer)) {
+                                    return typescript_1.factory.updatePropertyAssignment(it, it.name, (0, tracy_1.transformArrowFunctionWithInjectedZones)(it.initializer, `${(0, ast_1.getIdentifierText)(first)}.${it.name.getText()}`));
+                                }
+                                return it;
+                            })),
+                        ])));
+                    }
+                    else if ((0, typescript_1.isArrowFunction)(second)) {
+                        return context.superTransformStatements(typescript_1.factory.updateExpressionStatement(statement, typescript_1.factory.updateCallExpression(expression, expression.expression, expression.typeArguments, [
+                            first,
+                            (0, tracy_1.transformArrowFunctionWithInjectedZones)(second, (0, ast_1.getIdentifierText)(first)),
+                        ])));
+                    }
+                }
+            }
+            return context.superTransformStatements(statement);
+        },
+    },
+};
+exports.default = plugin;

package/plugins/strip_lua_logger.js

@@ -1,15 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const typescript_1 = require("typescript");
+const environment_1 = require("./utils/environment");
 const LUA_LOGGER_STRIP_TARGET = "LuaLogger";
-const IS_LUA_LOGGER_DISABLED = process.argv.includes("--no-lua-logs") || process.env.NO_LUA_LOGS === "true";
 /**
  * Plugin that removes all LuaLogger instance creations and calls when possible.
  */
 const plugin = {
     visitors: {
         [typescript_1.SyntaxKind.VariableStatement]: (statement, context) => {
-            if (IS_LUA_LOGGER_DISABLED) {
+            if (environment_1.IS_LUA_LOGGER_DISABLED) {
                 let elementsCount = 0;
                 const list = statement.declarationList;
                 const nodes = [];
@@ -34,7 +34,7 @@ const plugin = {
             return context.superTransformStatements(statement);
         },
         [typescript_1.SyntaxKind.ExpressionStatement]: (statement, context) => {
-            if (IS_LUA_LOGGER_DISABLED && statement.expression?.kind === typescript_1.SyntaxKind.CallExpression) {
+            if (environment_1.IS_LUA_LOGGER_DISABLED && statement.expression?.kind === typescript_1.SyntaxKind.CallExpression) {
                 const expression = statement.expression;
                 const propertyAccess = expression.expression;
                 if (propertyAccess.expression?.kind === typescript_1.SyntaxKind.Identifier) {

package/plugins/utils/ast.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getIdentifierText = getIdentifierText;
+function getIdentifierText(node) {
+    const text = node.getText();
+    if (text.length > 2 && (text.startsWith('"') || text.startsWith("'"))) {
+        return text.substring(1, text.length - 1);
+    }
+    return text;
+}

package/plugins/utils/environment.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IS_TRACY_ZONES_INJECTION_ENABLED = exports.IS_LUA_LOGGER_DISABLED = void 0;
+exports.IS_LUA_LOGGER_DISABLED = process.argv.includes("--no-lua-logs") || process.env.XR_NO_LUA_LOGS === "true";
+exports.IS_TRACY_ZONES_INJECTION_ENABLED = process.argv.includes("--inject-tracy-zones") || process.env.XR_INJECT_TRACY_ZONES === "true";

package/plugins/utils/tracy.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTraceBeginExpression = isTraceBeginExpression;
+exports.isTraceEndExpression = isTraceEndExpression;
+exports.createTraceZoneBeginExpression = createTraceZoneBeginExpression;
+exports.createTraceZoneBeginNExpression = createTraceZoneBeginNExpression;
+exports.createTraceZoneBeginSExpression = createTraceZoneBeginSExpression;
+exports.createTraceZoneEndExpression = createTraceZoneEndExpression;
+exports.remapStatementsWithZoneEnd = remapStatementsWithZoneEnd;
+exports.transformNestedStatementsToInjectEndZones = transformNestedStatementsToInjectEndZones;
+exports.transformWithInjectedZones = transformWithInjectedZones;
+exports.transformArrowFunctionWithInjectedZones = transformArrowFunctionWithInjectedZones;
+const typescript_1 = require("typescript");
+function isTraceBeginExpression(node) {
+    return ((0, typescript_1.isExpressionStatement)(node) &&
+        (0, typescript_1.isCallExpression)(node.expression) &&
+        (0, typescript_1.isPropertyAccessExpression)(node.expression.expression) &&
+        (node.expression.expression.name.escapedText === "ZoneBegin" ||
+            node.expression.expression.name.escapedText === "ZoneBeginS" ||
+            node.expression.expression.name.escapedText === "ZoneBeginN" ||
+            node.expression.expression.name.escapedText === "ZoneBeginNS"));
+}
+function isTraceEndExpression(node) {
+    return ((0, typescript_1.isExpressionStatement)(node) &&
+        (0, typescript_1.isCallExpression)(node.expression) &&
+        (0, typescript_1.isPropertyAccessExpression)(node.expression.expression) &&
+        node.expression.expression.name.escapedText === "ZoneEnd");
+}
+function createTraceZoneBeginExpression() {
+    return typescript_1.factory.createExpressionStatement(typescript_1.factory.createCallExpression(typescript_1.factory.createPropertyAccessExpression(typescript_1.factory.createIdentifier("tracy"), "ZoneBegin"), undefined, []));
+}
+function createTraceZoneBeginNExpression(name) {
+    return typescript_1.factory.createExpressionStatement(typescript_1.factory.createCallExpression(typescript_1.factory.createPropertyAccessExpression(typescript_1.factory.createIdentifier("tracy"), "ZoneBeginN"), undefined, [typescript_1.factory.createStringLiteral(name)]));
+}
+function createTraceZoneBeginSExpression(name) {
+    return typescript_1.factory.createExpressionStatement(typescript_1.factory.createCallExpression(typescript_1.factory.createPropertyAccessExpression(typescript_1.factory.createIdentifier("tracy"), "ZoneBeginS"), undefined, [typescript_1.factory.createStringLiteral(name)]));
+}
+function createTraceZoneEndExpression() {
+    return typescript_1.factory.createExpressionStatement(typescript_1.factory.createCallExpression(typescript_1.factory.createPropertyAccessExpression(typescript_1.factory.createIdentifier("tracy"), "ZoneEnd"), undefined, []));
+}
+function remapStatementsWithZoneEnd(target) {
+    const statements = [...target.statements];
+    let index = 0;
+    while (statements[index]) {
+        if ((0, typescript_1.isReturnStatement)(statements[index])) {
+            statements.splice(index, 0, createTraceZoneEndExpression());
+            index += 1;
+        }
+        index++;
+    }
+    return statements;
+}
+function transformNestedStatementsToInjectEndZones(statement) {
+    if (!statement || isTraceBeginExpression(statement) || isTraceEndExpression(statement)) {
+        return statement;
+    }
+    if ((0, typescript_1.isBlock)(statement)) {
+        const statements = [...statement.statements];
+        let index = 0;
+        while (statements[index]) {
+            if ((0, typescript_1.isReturnStatement)(statements[index])) {
+                statements.splice(index, 0, createTraceZoneEndExpression());
+                index += 1;
+            }
+            index++;
+        }
+        return typescript_1.factory.updateBlock(statement, remapStatementsWithZoneEnd(statement).map((it) => transformNestedStatementsToInjectEndZones(it)));
+    }
+    else if ((0, typescript_1.isForStatement)(statement)) {
+        if ((0, typescript_1.isBlock)(statement.statement)) {
+            return typescript_1.factory.updateForStatement(statement, statement.initializer, statement.condition, statement.incrementor, transformNestedStatementsToInjectEndZones(statement.statement));
+        }
+        else {
+            throw new Error(`Unexpected nested for statement: ${statement.statement.kind} (${typescript_1.SyntaxKind[statement.statement.kind]}).`);
+        }
+    }
+    else if ((0, typescript_1.isForInStatement)(statement)) {
+        if ((0, typescript_1.isBlock)(statement.statement)) {
+            return typescript_1.factory.updateForInStatement(statement, statement.initializer, statement.expression, transformNestedStatementsToInjectEndZones(statement.statement));
+        }
+        else {
+            throw new Error(`Unexpected nested for-in statement: ${statement.statement.kind} (${typescript_1.SyntaxKind[statement.statement.kind]}).`);
+        }
+    }
+    else if ((0, typescript_1.isForOfStatement)(statement)) {
+        if ((0, typescript_1.isBlock)(statement.statement)) {
+            return typescript_1.factory.updateForOfStatement(statement, statement.awaitModifier, statement.initializer, statement.expression, transformNestedStatementsToInjectEndZones(statement.statement));
+        }
+        else {
+            throw new Error(`Unexpected nested for-of statement: ${statement.statement.kind} (${typescript_1.SyntaxKind[statement.statement.kind]}).`);
+        }
+    }
+    else if ((0, typescript_1.isIfStatement)(statement)) {
+        return typescript_1.factory.updateIfStatement(statement, statement.expression, transformNestedStatementsToInjectEndZones(statement.thenStatement), transformNestedStatementsToInjectEndZones(statement.elseStatement));
+    }
+    else if ((0, typescript_1.isSwitchStatement)(statement)) {
+        return typescript_1.factory.updateSwitchStatement(statement, statement.expression, typescript_1.factory.updateCaseBlock(statement.caseBlock, statement.caseBlock.clauses.map((it) => {
+            if ((0, typescript_1.isCaseClause)(it)) {
+                return typescript_1.factory.updateCaseClause(it, it.expression, remapStatementsWithZoneEnd(it).map((it) => transformNestedStatementsToInjectEndZones(it)));
+            }
+            else if ((0, typescript_1.isDefaultClause)(it)) {
+                return typescript_1.factory.updateDefaultClause(it, remapStatementsWithZoneEnd(it).map((it) => transformNestedStatementsToInjectEndZones(it)));
+            }
+            else {
+                return it;
+            }
+        })));
+    }
+    return statement;
+}
+function transformWithInjectedZones(node, parentName) {
+    const name = node.name ? node.name.getText() : null;
+    if (!name || !node.body?.statements.length) {
+        return node;
+    }
+    const hasReturnStatement = (0, typescript_1.isReturnStatement)(node.body.statements[node.body.statements.length - 1]);
+    // Single line function declaration with return, nothing to profile here without complex assign transformations.
+    if (hasReturnStatement && node.body.statements.length === 1) {
+        return node;
+    }
+    const statements = remapStatementsWithZoneEnd(node.body).map(transformNestedStatementsToInjectEndZones);
+    // Zone start declaration.
+    statements.unshift(createTraceZoneBeginNExpression(`${parentName ? `${parentName}.` : ""}${name}@lua`));
+    // Zone end declaration without explicit return.
+    if (!hasReturnStatement) {
+        statements.push(createTraceZoneEndExpression());
+    }
+    if ((0, typescript_1.isMethodDeclaration)(node)) {
+        return typescript_1.factory.updateMethodDeclaration(node, node.modifiers, node.asteriskToken, node.name, node.questionToken, node.typeParameters, node.parameters, node.type, typescript_1.factory.updateBlock(node.body, statements));
+    }
+    else if ((0, typescript_1.isConstructorDeclaration)(node)) {
+        return typescript_1.factory.updateConstructorDeclaration(node, node.modifiers, node.parameters, typescript_1.factory.updateBlock(node.body, statements));
+    }
+    else {
+        return typescript_1.factory.updateFunctionDeclaration(node, node.modifiers, node.asteriskToken, node.name, node.typeParameters, node.parameters, node.type, typescript_1.factory.updateBlock(node.body, statements));
+    }
+}
+function transformArrowFunctionWithInjectedZones(node, name) {
+    if (!node || !name || (0, typescript_1.isExpression)(node.body) || !node.body.statements.length) {
+        return node;
+    }
+    const hasReturnStatement = (0, typescript_1.isReturnStatement)(node.body.statements[node.body.statements.length - 1]);
+    // Single line function declaration with return, nothing to profile here without complex assign transformations.
+    if (hasReturnStatement && node.body.statements.length === 1) {
+        return node;
+    }
+    const statements = remapStatementsWithZoneEnd(node.body).map(transformNestedStatementsToInjectEndZones);
+    // Zone start declaration.
+    statements.unshift(createTraceZoneBeginNExpression(`${name}@lua`));
+    // Zone end declaration without explicit return.
+    if (!hasReturnStatement) {
+        statements.push(createTraceZoneEndExpression());
+    }
+    return typescript_1.factory.updateArrowFunction(node, node.modifiers, node.typeParameters, node.parameters, node.type, node.equalsGreaterThanToken, typescript_1.factory.updateBlock(node.body, statements));
+}

package/types/index.d.ts

@@ -20,6 +20,7 @@ import "./xr_lib/xr_luabind";
 import "./xr_lib/xr_map";
 import "./xr_lib/xr_math";
 import "./xr_lib/xr_multiplayer";
+import "./xr_lib/xr_profile";
 import "./xr_lib/xr_properties";
 import "./xr_lib/xr_relation";
 import "./xr_lib/xr_render";

package/types/xr_lib/xr_debug.d.ts

@@ -1,27 +1,4 @@
 declare module "xray16" {
-  /**
-   * @source C++ class profile_timer
-   * @customConstructor profile_timer
-   * @group xr_debug
-   */
-  export class profile_timer extends EngineBinding {
-    public constructor();
-    public constructor(timer: profile_timer);
-
-    public stop(): void;
-
-    public start(): void;
-
-    public time(): f32;
-
-    /**
-     * Overridden string cast is implemented for profiling timer.
-     *
-     * @returns serialized profile time.
-     */
-    public toString(): string;
-  }
-
   /**
    * @source C++ class CConsole
    * @customConstructor CConsole

package/types/xr_lib/xr_profile.d.ts

@@ -0,0 +1,160 @@
+declare module "xray16" {
+  export const PROFILER_TYPE_NONE: 0;
+  export const PROFILER_TYPE_HOOK: 1;
+  export const PROFILER_TYPE_SAMPLING: 2;
+
+  export type TXR_ProfilerType = typeof PROFILER_TYPE_NONE | typeof PROFILER_TYPE_HOOK | typeof PROFILER_TYPE_SAMPLING;
+
+  /**
+   * @source C++ class profile_timer
+   * @customConstructor profile_timer
+   * @group xr_profile
+   */
+  export class profile_timer extends EngineBinding {
+    public constructor();
+    public constructor(timer: profile_timer);
+
+    public stop(): void;
+
+    public start(): void;
+
+    public time(): f32;
+
+    /**
+     * Overridden string cast is implemented for profiling timer.
+     *
+     * @returns serialized profile time.
+     */
+    public toString(): string;
+  }
+
+  /**
+   * @source namespace profiler
+   * @group xr_profile
+   */
+  export interface IXR_profiler {
+    /**
+     * @returns whether lua scripts profiler is active
+     */
+    is_active(this: void): boolean;
+
+    /**
+     * @returns currently active profiler type
+     */
+    get_type(this: void): typeof PROFILER_TYPE_NONE | typeof PROFILER_TYPE_HOOK | typeof PROFILER_TYPE_SAMPLING;
+
+    /**
+     * Start lua scripts profiler in default mode.
+     */
+    start(this: void): void;
+
+    /**
+     * Start lua scripts profiler of provided type.
+     *
+     * @param profiler_type - type of profiler to start (note: see global exports of type constants)
+     */
+    start(this: void, profiler_type: TXR_ProfilerType): void;
+
+    /**
+     * Start profiler in hook mode.
+     * Profiling performance based on lua call start/end events.
+     */
+    start_hook_mode(this: void): void;
+
+    /**
+     * Start profiler in sampling mode with default sampling interval.
+     */
+    start_sampling_mode(this: void): void;
+
+    /**
+     * Start profiler in sampling mode with provided sampling interval value.
+     *
+     * @param sampling_interval - interval to collect samples with luaJIT sampling profiler
+     */
+    start_sampling_mode(this: void, sampling_interval: u32): void;
+
+    /**
+     * Stop currently active profiler.
+     */
+    stop(this: void): void;
+
+    /**
+     * Reset measurements data of profiler.
+     */
+    reset(this: void): void;
+
+    /**
+     * Log report of profiler measurements in game console/log file.
+     * Use default engine limit to print top N entries.
+     */
+    log_report(this: void): void;
+
+    /**
+     * Log report of profiler measurements in game console/log file.
+     *
+     * @param entries_limit - limit of top profiling entries to print
+     */
+    log_report(this: void, entries_limit: u32): void;
+
+    /**
+     * Save report of profiler measurements in corresponding log/perf file.
+     */
+    save_report(this: void): void;
+  }
+
+  /**
+   * @group xr_profile
+   */
+  export const profiler: IXR_profiler;
+
+  /**
+   * @source namespace profiler
+   * @group xr_profile
+   */
+  export interface IXR_tracy {
+    /**
+     * Begin tracy profiling zone.
+     */
+    ZoneBegin(this: void): void;
+
+    /**
+     * Begin tracy profiling zone with defined name.
+     *
+     * @param name - name to display in tracy logs for current zone
+     */
+    ZoneBeginN(this: void, name: string): void;
+
+    ZoneBeginS(this: void): void;
+
+    ZoneBeginNS(this: void): void;
+
+    /**
+     * End tracy profiling zone.
+     */
+    ZoneEnd(this: void): void;
+
+    /**
+     * Set zone text.
+     *
+     * @param text - text description of the zone
+     */
+    ZoneText(this: void, text: string): void;
+
+    /**
+     * Set zone name on per-call basis.
+     *
+     * @param name - name of zone
+     */
+    ZoneName(this: void, name: string): void;
+
+    /**
+     * Send message to tracy profiler.
+     */
+    Message(this: void): void;
+  }
+
+  /**
+   * @group xr_profile
+   */
+  export const tracy: IXR_tracy;
+}