Skip to content

xray-forge/xray-16-types

Repository files navigation

types book
Node.js CI

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

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