xray16

📡 XRay-16 engine typescript definitions

X-Ray16 engine bindings documentation and types.
For usage with TypeScriptToLua.

Module contains xray engine globals typedefs for typescript.
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.

🗻 Docs

Types documentation can be checked here.

🧱 Usage

Types are used with 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

C++ classes can be extended in Lua code with 'class' keyword. Class declaration registers table as userdata and adds constructor/destructor metamethods.

Typescript

In TS codebase 'LuabindClass' decorator can be used to modify transformation and enable virtual calls.
Separate transformer is needed to build luabind classes instead of table-based classes.

🧱 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

🧱 Plugins

Package includes plugins for typescript-to-lua for easier work with xray16 typings.
Following ones are available:

• transform_luabind_class - transforms LuaBind decorated classes in a specific way
• built_at_info - adds build information in resulting files
• 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 (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:

{
  "tstl": {
    "luaPlugins": [
      { "name": "xray16/plugins/transform_luabind_class/plugin" },
      { "name": "xray16/plugins/global_declarations_transform" },
      { "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/inject_tracy_zones" }
    ]
  }
}