📡 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 bindings that can be accessed from lua scripts, but without any 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.

📦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

🧲 Plugins

Package includes plugins for typescript-to-lua for easier work with xray16 typings.
Plugins can be included in tstl tsconfig file as following section:

{
  "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" }
    ]
  }
}
Copy

Arguments for TSTL:

• --no-lua-logs
• --inject-tracy-zones

Env variables for custom CLI scripts:

• XR_NO_LUA_LOGS
• XR_INJECT_TRACY_ZONES

transform_luabind_class

Custom plugin overriding transformation of classes marked with @LuaClass decorator.
Instead of using prototypes and metatables use luabind API to declare such classes.\

built_at_info

Plugin injecting time and generic metadata on top of built lua scripts.

global_declarations_transform

Plugin stripping all the runtime imports from xray16 package. Default tstl behaviour does not work well with engine imports and I tried to avoid implicit globals.

strip_lua_logger

Plugin to strip all LuaLogger calls from runtime if env variable is set or path param is provided.
Logger can consume a lot of processing time that does not benefit player.

inject_filename

Plugin adding $filename global variable replaced with actual file name on build time.
Lua does not provide convenient API do get filename in runtime and static step is much simpler.

from_cast_utils

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

Plugin designed to work specifically with tracy profiler.
Once it is enabled with env variable or path parameter, tracy zone marking calls are injected for every method.
This way you will be able to build profiling bundle to understand bottlenecks and what takes CPU time.