xray16 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 stalker-xrts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# [📡 XRay-16 engine typescript definitions](https://github.com/xray-forge/xray-16-types)
+
+[![Node.js CI](https://github.com/xray-forge/xray-16-types/actions/workflows/build_and_test.yml/badge.svg)](https://github.com/xray-forge/xray-16-types/actions/workflows/build_and_test.yml)
+
+X-Ray16 engine bindings documentation and types. <br/>
+For usage with [TypeScriptToLua](https://typescripttolua.github.io/docs/getting-started).
+
+<p>
+Module contains xray engine globals typedefs for typescript. <br/>
+By default x-ray export many bindings that can be used from lua scripts, but without game API documentation.
+
+To check more details / correct typing you always can reference X-Ray source code.
+
+</p>
+
+## 🗻 Docs
+
+Types documentation can be checked [here](https://xray-forge.github.io/xray-16-types/modules.html).
+
+## 🧱 Usage
+
+Types are used with [xrf template](https://github.com/xray-forge/stalker-xrf-template) and can be referenced as an example.
+
+## 🎮 Updating types
+
+For easier navigation over codebase and typing following rules are applied:
+
+- Type declaration should have \@source docblock with matching c++ counterpart signature
+- Variable and class namings follow c++ conventions for easier binding and matching engine codebase
+- XRay types should be prefixed with IXR or TXR if they do not have runtime representation
+
+## 📦Extending C++ classes and overriding virtual methods
+
+### Lua
+
+<p>
+C++ classes can be extended in Lua code with 'class' keyword. 
+Class declaration registers table as userdata and adds constructor/destructor metamethods. <br/>
+</p>
+
+### Typescript
+
+<p>
+In TS codebase '@LuabindClass' decorator can be used to modify transformation and enable virtual calls. <br/>
+Separate transformer is needed to build luabind classes instead of table-based classes.
+</p>
+
+## 🧱 Getting up-to-date LUA bindings
+
+- Run game engine with `-dump_bindings` flag
+- Check userdata folder _(where game saves are stored)_ `scriptbindings_*.txt` files
+
+## 🧲 References
+
+- X-Ray C++ source code
+- LuaBind sources and docs
+- LuaJit sources and docs

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "xray16",
+  "version": "1.0.0",
+  "author": "Neloreck",
+  "repository": "https://github.com/stalker-xrts/xray-16-types",
+  "private": false,
+  "main": "src/index.d.ts",
+  "types": "src/index.d.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "typedoc": "typedoc",
+    "format": "prettier --write \"**/*.(js|ts|tsx|md)\" && eslint . --ext .ts,.tsx,.js --fix",
+    "lint": "eslint . --ext .ts,.tsx,.js"
+  },
+  "peerDependencies": {
+    "typescript-to-lua": "^1.16.3"
+  },
+  "devDependencies": {
+    "@types/node": "20.3.1",
+    "@typescript-eslint/eslint-plugin": "^5.54.0",
+    "@typescript-eslint/parser": "^5.54.0",
+    "@typescript-to-lua/language-extensions": "1.0.0",
+    "eslint": "^8.35.0",
+    "eslint-config-standard-with-typescript": "^34.0.0",
+    "eslint-plugin-import": "^2.27.5",
+    "eslint-plugin-jest": "^27.2.1",
+    "eslint-plugin-sort-keys-fix": "^1.1.2",
+    "prettier": "^3.0.1",
+    "typedoc": "^0.24.8",
+    "typescript": "^5.1.6"
+  },
+  "files": [
+    "plugins/**/*",
+    "src/**/*",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/plugins/built_at_info.ts

@@ -0,0 +1,18 @@
+import { Program } from "typescript";
+import { Plugin, CompilerOptions, EmitFile, EmitHost } from "typescript-to-lua";
+
+const comment: string = `-- Generated by xrf util at: ${new Date().toString()}\n\n`;
+
+const plugin: Plugin = {
+  beforeEmit(program: Program, options: CompilerOptions, emitHost: EmitHost, result: Array<EmitFile>) {
+    void program;
+    void options;
+    void emitHost;
+
+    for (const file of result) {
+      file.code = comment + file.code;
+    }
+  },
+};
+
+export default plugin;

package/plugins/from_cast_utils.ts

@@ -0,0 +1,34 @@
+import { isIdentifier, SyntaxKind } from "typescript";
+import { Plugin } from "typescript-to-lua";
+import { createErrorDiagnosticFactory } from "./utils/diagnostics";
+
+const FROM_CAST_METHODS: Array<string> = ["$fromObject", "$fromArray", "$fromLuaArray", "$fromLuaTable"];
+
+/**
+ * Push generic error to notify about usage issue.
+ */
+const createInvalidFunctionCallError = createErrorDiagnosticFactory((name?: string) => {
+  return `Invalid transformer call, expected function to have exactly 1 argument.`;
+});
+
+/**
+ * Plugin for transformation of casting methods.
+ * Simplifies TS/Lua testing and interoperation.
+ */
+const plugin: Plugin = {
+  visitors: {
+    [SyntaxKind.CallExpression]: (node, context) => {
+      if (isIdentifier(node.expression) && FROM_CAST_METHODS.includes(node.expression.text)) {
+        if (node.arguments.length !== 1) {
+          context.diagnostics.push(createInvalidFunctionCallError(node));
+        }
+
+        return context.transformExpression(node.arguments[0]);
+      }
+
+      return context.superTransformExpression(node);
+    },
+  },
+};
+
+export default plugin;

package/plugins/global_declarations_transform.ts

@@ -0,0 +1,24 @@
+import { SyntaxKind } from "typescript";
+import { Plugin } from "typescript-to-lua";
+
+const XRF_GLOBALS: Array<string> = ["xray16"];
+
+/**
+ * Plugin that removes imports from 'global' libraries like engine typedefs.
+ */
+const plugin: Plugin = {
+  visitors: {
+    [SyntaxKind.ImportDeclaration]: (node, context) => {
+      const module: string = node.moduleSpecifier.getText().slice(1, -1);
+      const shouldNotBeTransformed: boolean = XRF_GLOBALS.includes(module);
+
+      if (shouldNotBeTransformed) {
+        return undefined;
+      }
+
+      return context.superTransformStatements(node);
+    },
+  },
+};
+
+export default plugin;

package/plugins/inject_filename.ts

@@ -0,0 +1,22 @@
+import * as path from "path";
+import { SyntaxKind } from "typescript";
+import { createStringLiteral, Plugin } from "typescript-to-lua";
+
+const FILENAME_IDENTIFIER: string = "$filename";
+
+/**
+ * Plugin that injects FILE_NAME in compile-time.
+ */
+const plugin: Plugin = {
+  visitors: {
+    [SyntaxKind.Identifier]: (node, context) => {
+      if (node.text === FILENAME_IDENTIFIER) {
+        return createStringLiteral(path.parse(context.sourceFile.fileName).name);
+      }
+
+      return context.superTransformExpression(node);
+    },
+  },
+};
+
+export default plugin;

package/plugins/strip_lua_logger.ts

@@ -0,0 +1,73 @@
+import {
+  CallExpression,
+  factory,
+  Identifier,
+  PropertyAccessExpression,
+  SyntaxKind,
+  Type,
+  TypeChecker,
+  VariableDeclaration,
+  VariableDeclarationList,
+} from "typescript";
+import { Plugin } from "typescript-to-lua";
+
+const LUA_LOGGER_STRIP_TARGET: string = "LuaLogger";
+const IS_LUA_LOGGER_DISABLED: boolean = process.argv.includes("--no-lua-logs");
+
+/**
+ * Plugin that removes all LuaLogger instance creations and calls when possible.
+ */
+const plugin: Plugin = {
+  visitors: {
+    [SyntaxKind.VariableStatement]: (statement, context) => {
+      if (IS_LUA_LOGGER_DISABLED) {
+        let elementsCount: number = 0;
+        const list = statement.declarationList as VariableDeclarationList;
+        const nodes: Array<VariableDeclaration> = [];
+
+        list.forEachChild((it: VariableDeclaration) => {
+          const checker: TypeChecker = context.program.getTypeChecker();
+          const typeSymbol: Type = checker.getTypeAtLocation(it);
+
+          if (typeSymbol.symbol?.name === LUA_LOGGER_STRIP_TARGET) {
+            // nothing
+          } else {
+            nodes.push(it);
+          }
+
+          elementsCount += 1;
+        });
+
+        if (nodes.length === 0) {
+          return undefined;
+        } else if (nodes.length !== elementsCount) {
+          return context.superTransformStatements(
+            factory.createVariableStatement(statement.modifiers, factory.updateVariableDeclarationList(list, nodes))
+          );
+        }
+      }
+
+      return context.superTransformStatements(statement);
+    },
+    [SyntaxKind.ExpressionStatement]: (statement, context) => {
+      if (IS_LUA_LOGGER_DISABLED && statement.expression?.kind === SyntaxKind.CallExpression) {
+        const expression: CallExpression = statement.expression as CallExpression;
+        const propertyAccess: PropertyAccessExpression = expression.expression as PropertyAccessExpression;
+
+        if (propertyAccess.expression?.kind === SyntaxKind.Identifier) {
+          const checker: TypeChecker = context.program.getTypeChecker();
+          const identifier: Identifier = propertyAccess.expression as Identifier;
+          const typeSymbol: Type = checker.getTypeAtLocation(identifier);
+
+          if (typeSymbol.symbol?.name === LUA_LOGGER_STRIP_TARGET) {
+            return undefined;
+          }
+        }
+      }
+
+      return context.superTransformStatements(statement);
+    },
+  },
+};
+
+export default plugin;

package/plugins/transform_luabind_class/plugin.ts

@@ -0,0 +1,51 @@
+import {
+  transformLuabindClassDeclaration,
+  transformNewCallExpression,
+  isLuabindClassSuperCall,
+  transformClassSuperMethodExpression,
+  transformLuabindConstructorSuperCall,
+  ITransformationContext,
+  isLuabindClassType,
+  isLuabindDecoratedClass,
+  isLuabindClassSuperMethodCall,
+} from "./transformation";
+import { CallExpression, NewExpression, SuperExpression, SyntaxKind } from "typescript";
+import { Plugin } from "typescript-to-lua";
+
+/**
+ * Plugin that transform TS classes marked with decorator to luabind class declaration.
+ */
+const plugin: Plugin = {
+  visitors: {
+    [SyntaxKind.CallExpression]: (expression: CallExpression, context: ITransformationContext) => {
+      if (isLuabindClassSuperCall(expression, context)) {
+        return transformLuabindConstructorSuperCall(expression, context);
+      }
+
+      return context.superTransformExpression(expression);
+    },
+    [SyntaxKind.ClassDeclaration]: (declaration, context: ITransformationContext) => {
+      if (isLuabindDecoratedClass(declaration)) {
+        return transformLuabindClassDeclaration(declaration, context);
+      }
+
+      return context.superTransformStatements(declaration);
+    },
+    [SyntaxKind.NewExpression]: (expression: NewExpression, context: ITransformationContext) => {
+      if (isLuabindClassType(expression, context)) {
+        return transformNewCallExpression(expression, context);
+      }
+
+      return context.superTransformExpression(expression);
+    },
+    [SyntaxKind.SuperKeyword]: (expression: SuperExpression, context: ITransformationContext) => {
+      if (isLuabindClassSuperMethodCall(expression, context)) {
+        return transformClassSuperMethodExpression(expression, context);
+      }
+
+      return context.superTransformExpression(expression);
+    },
+  },
+};
+
+export default plugin;

package/plugins/transform_luabind_class/transformation/class_declaration.ts

@@ -0,0 +1,226 @@
+import { LUABIND_CONSTRUCTOR_METHOD } from "./constants";
+import { checkLuabindClassDecoratorExpression } from "./decorators";
+import { unsupportedStaticMethod } from "./errors";
+import { transformAccessorDeclarations } from "./members/accessors";
+import { createConstructorName, transformConstructorDeclaration } from "./members/constructor";
+import { verifyPropertyDecoratingExpression, transformClassInstanceFields } from "./members/fields";
+import { verifyMethodDecoratingExpression, transformMethodDeclaration } from "./members/method";
+import { createClassSetup } from "./setup";
+import { getExtendedNode, getExtendedType, isStaticNode, markTypeAsLuabind } from "./utils";
+import {
+  canHaveDecorators,
+  ClassLikeDeclaration,
+  ConstructorDeclaration,
+  ExpressionWithTypeArguments,
+  factory,
+  getDecorators,
+  isAccessor,
+  isConstructorDeclaration,
+  isMethodDeclaration,
+  isPropertyDeclaration,
+} from "typescript";
+import * as tstl from "typescript-to-lua";
+import { LuaTarget, TransformationContext } from "typescript-to-lua";
+import {
+  createDefaultExportExpression,
+  createExportedIdentifier,
+  hasDefaultExportModifier,
+  hasExportModifier,
+} from "typescript-to-lua/dist/transformation/utils/export";
+import { createSelfIdentifier } from "typescript-to-lua/dist/transformation/utils/lua-ast";
+import { transformInPrecedingStatementScope } from "typescript-to-lua/dist/transformation/utils/preceding-statements";
+import { createSafeName, isUnsafeName } from "typescript-to-lua/dist/transformation/utils/safe-names";
+import { transformIdentifier } from "typescript-to-lua/dist/transformation/visitors/identifier";
+
+export interface ITransformationContext extends TransformationContext {
+  classSuperInfos: Array<ClassSuperInfo>;
+}
+
+export const transformLuabindClassDeclaration = (declaration, context: TransformationContext) => {
+  // If declaration is a default export, transform to export variable assignment instead
+  if (hasDefaultExportModifier(declaration)) {
+    // Class declaration including assignment to ____exports.default are in preceding statements
+    const { precedingStatements } = transformInPrecedingStatementScope(context, () => {
+      transformClassAsExpression(declaration, context as ITransformationContext);
+      return [];
+    });
+    return precedingStatements;
+  }
+
+  const { statements } = transformClassLikeDeclaration(declaration, context as ITransformationContext);
+  return statements;
+};
+
+export function transformClassAsExpression(
+  expression: ClassLikeDeclaration,
+  context: ITransformationContext
+): tstl.Expression {
+  const { statements, name } = transformClassLikeDeclaration(expression, context);
+  context.addPrecedingStatements(statements);
+  return name;
+}
+
+/** @internal */
+export interface ClassSuperInfo {
+  className: tstl.Identifier;
+  classDeclaration: ClassLikeDeclaration;
+  extendedTypeNode?: ExpressionWithTypeArguments;
+}
+
+export function transformClassLikeDeclaration(
+  classDeclaration: ClassLikeDeclaration,
+  context: ITransformationContext,
+  nameOverride?: tstl.Identifier
+): { statements: tstl.Statement[]; name: tstl.Identifier } {
+  let className: tstl.Identifier;
+
+  if (nameOverride !== undefined) {
+    className = nameOverride;
+  } else if (classDeclaration.name !== undefined) {
+    className = transformIdentifier(context, classDeclaration.name);
+  } else {
+    className = tstl.createIdentifier(context.createTempName("class"), classDeclaration);
+  }
+
+  markTypeAsLuabind(classDeclaration, context);
+
+  // Get type that is extended
+  const extendedTypeNode = getExtendedNode(classDeclaration);
+  const extendedType = getExtendedType(context, classDeclaration);
+
+  context.classSuperInfos.push({ className, classDeclaration: classDeclaration, extendedTypeNode });
+
+  // Get all properties with value
+  const properties = classDeclaration.members.filter(isPropertyDeclaration).filter((member) => member.initializer);
+
+  // Divide properties into static and non-static
+  const instanceFields = properties.filter((prop) => !isStaticNode(prop));
+
+  const result: tstl.Statement[] = [];
+
+  let localClassName: tstl.Identifier;
+  if (isUnsafeName(className.text, context.options)) {
+    localClassName = tstl.createIdentifier(
+      createSafeName(className.text),
+      undefined,
+      className.symbolId,
+      className.text
+    );
+    tstl.setNodePosition(localClassName, className);
+  } else {
+    localClassName = className;
+  }
+
+  result.push(...createClassSetup(context, classDeclaration, className, localClassName));
+
+  // Find first constructor with body
+  const constructor = classDeclaration.members.find(
+    (n): n is ConstructorDeclaration => isConstructorDeclaration(n) && n.body !== undefined
+  );
+
+  if (constructor) {
+    // Add constructor plus initialization of instance fields
+    const constructorResult = transformConstructorDeclaration(
+      context,
+      constructor,
+      localClassName,
+      instanceFields,
+      classDeclaration
+    );
+
+    if (constructorResult) result.push(constructorResult);
+  } else if (!extendedType) {
+    // Generate a constructor if none was defined in a base class
+    const constructorResult = transformConstructorDeclaration(
+      context,
+      factory.createConstructorDeclaration([], [], factory.createBlock([], true)),
+      localClassName,
+      instanceFields,
+      classDeclaration
+    );
+
+    if (constructorResult) result.push(constructorResult);
+  } else {
+    // Generate a constructor if none was defined in a class with instance fields that need initialization
+    // localClassName.__init = function(self, ...)
+    //     baseClassName.__init(self, ...)  // or unpack(arg) for Lua 5.0
+    //     ...
+    // Also luabind always needs definition of call expression to use table as class.
+    const constructorBody = transformClassInstanceFields(context, instanceFields);
+    const argsExpression =
+      context.luaTarget === LuaTarget.Lua50
+        ? tstl.createCallExpression(tstl.createIdentifier("unpack"), [tstl.createArgLiteral()])
+        : tstl.createDotsLiteral();
+    const superCall = tstl.createExpressionStatement(
+      tstl.createCallExpression(
+        tstl.createTableIndexExpression(
+          context.transformExpression(factory.createSuper()),
+          tstl.createStringLiteral(LUABIND_CONSTRUCTOR_METHOD)
+        ),
+        [createSelfIdentifier(), argsExpression]
+      )
+    );
+    constructorBody.unshift(superCall);
+    const constructorFunction = tstl.createFunctionExpression(
+      tstl.createBlock(constructorBody),
+      [createSelfIdentifier()],
+      tstl.createDotsLiteral(),
+      tstl.NodeFlags.Declaration
+    );
+    result.push(
+      tstl.createAssignmentStatement(createConstructorName(localClassName), constructorFunction, classDeclaration)
+    );
+  }
+
+  // Transform accessors
+  for (const member of classDeclaration.members) {
+    if (!isAccessor(member)) continue;
+    const accessors = context.resolver.getAllAccessorDeclarations(member);
+    if (accessors.firstAccessor !== member) continue;
+
+    const accessorsResult = transformAccessorDeclarations(context, accessors, localClassName);
+    if (accessorsResult) {
+      result.push(accessorsResult);
+    }
+  }
+
+  const decorationStatements: tstl.Statement[] = [];
+
+  for (const member of classDeclaration.members) {
+    if (isAccessor(member)) {
+      verifyPropertyDecoratingExpression(context, member);
+    } else if (isMethodDeclaration(member)) {
+      const statement = transformMethodDeclaration(context, member, localClassName);
+      if (statement) result.push(statement);
+      if (member.body) {
+        verifyMethodDecoratingExpression(context, member);
+      }
+    } else if (isPropertyDeclaration(member)) {
+      if (isStaticNode(member)) {
+        context.diagnostics.push(unsupportedStaticMethod(member));
+      }
+
+      verifyPropertyDecoratingExpression(context, member);
+    }
+  }
+
+  result.push(...decorationStatements);
+
+  // Decorate the class
+  if (canHaveDecorators(classDeclaration) && getDecorators(classDeclaration)) {
+    getDecorators(classDeclaration)?.forEach((d) => checkLuabindClassDecoratorExpression(context, d));
+
+    if (hasExportModifier(classDeclaration)) {
+      const exportExpression = hasDefaultExportModifier(classDeclaration)
+        ? createDefaultExportExpression(classDeclaration)
+        : createExportedIdentifier(context, className);
+
+      const classAssignment = tstl.createAssignmentStatement(exportExpression, localClassName);
+      result.push(classAssignment);
+    }
+  }
+
+  context.classSuperInfos.pop();
+
+  return { statements: result, name: className };
+}

package/plugins/transform_luabind_class/transformation/constants.ts

@@ -0,0 +1,4 @@
+export const LUABIND_NAME_FIELD: string = "__name";
+export const LUABIND_DECORATOR: string = "LuabindClass";
+export const LUABIND_CONSTRUCTOR_METHOD: string = "__init";
+export const LUABIND_SYMBOL: symbol = Symbol("IS_LUABIND_CLASS");

package/plugins/transform_luabind_class/transformation/decorators.ts

@@ -0,0 +1,16 @@
+import { unsupportedClassDecorator } from "./errors";
+import { LUABIND_DECORATOR } from "./constants";
+import { CallExpression, Decorator, Identifier } from "typescript";
+import { TransformationContext } from "typescript-to-lua";
+
+/**
+ * Transform decorator call expressions for luabind class.
+ */
+export function checkLuabindClassDecoratorExpression(context: TransformationContext, decorator: Decorator) {
+  const expression = decorator.expression;
+
+  // Do not transform luabind decorator.
+  if (((expression as CallExpression).expression as Identifier).text !== LUABIND_DECORATOR) {
+    context.diagnostics.push(unsupportedClassDecorator(expression));
+  }
+}

package/plugins/transform_luabind_class/transformation/errors.ts

@@ -0,0 +1,31 @@
+import { createErrorDiagnosticFactory } from "../../utils/diagnostics";
+
+export const unsupportedStaticMethod = createErrorDiagnosticFactory((name?: string) => {
+  const nameReference = name ? ` '${name}'` : "";
+  return `Unable transform static properties for luabind classes${nameReference}.`;
+});
+
+export const unsupportedClassDecorator = createErrorDiagnosticFactory((name?: string) => {
+  const nameReference = name ? ` '${name}'` : "";
+  return `Unable transform class decorators for luabind classes${nameReference}.`;
+});
+
+export const unsupportedPropertyDecorator = createErrorDiagnosticFactory((name?: string) => {
+  const nameReference = name ? ` '${name}'` : "";
+  return `Unable transform property decorator for luabind classes${nameReference}.`;
+});
+
+export const unsupportedParameterDecorator = createErrorDiagnosticFactory((name?: string) => {
+  const nameReference = name ? ` '${name}'` : "";
+  return `Unable transform parameter decorator for luabind classes${nameReference}.`;
+});
+
+export const unsupportedMethodDecorator = createErrorDiagnosticFactory((name?: string) => {
+  const nameReference = name ? ` '${name}'` : "";
+  return `Unable transform method decorator for luabind classes${nameReference}.`;
+});
+
+export const unsupportedStaticAccessor = createErrorDiagnosticFactory((name?: string) => {
+  const nameReference = name ? ` '${name}'` : "";
+  return `Unable transform static accessors for luabind classes${nameReference}.`;
+});

package/plugins/transform_luabind_class/transformation/index.ts

@@ -0,0 +1,5 @@
+export * from "./constants";
+export * from "./utils";
+export * from "./class_declaration";
+export * from "./super";
+export * from "./new";