Getting Started

xray16 provides TypeScript declarations, Node test helpers, and TypeScriptToLua plugins for Lua-visible X-Ray 16 APIs. Use it to compile XRF game scripts from TypeScript, including with stalker-xrf-engine.

Install

Install the SDK and its required TypeScriptToLua peer dependency:

npm install xray16 typescript-to-lua

typescript-to-lua is the only required peer dependency. Install jest, ts-jest, and typescript when using xray16/testing. The fengari and ini dependencies used by xray16/mocks install automatically.

Add the base declarations to compilerOptions.types. Include only the ambient typedef packages your project uses.

{
  "compilerOptions": {
    "types": [
      "@typescript-to-lua/language-extensions",
      "xray16",
      "xray16/typedefs/extensions",
      "xray16/typedefs/luajit",
    ],
  },
}

For an unreleased build, install xray16@experimental from npm or use the rolling nightly GitHub release:

npm install https://github.com/xray-forge/stalker-xrf-xray16-sdk/releases/download/nightly/xray16-nightly.tgz

Entry points

Import	Use it for
xray16	Engine globals, luabind classes, UI and GOAP classes, and script objects.
xray16/alias	Readable aliases for engine declaration names and virtual engine enums.
xray16/macros	Compile-time helpers with a Node/Jest fallback.
xray16/lib	Shared aliases, constants, and small runtime helpers.
xray16/testing	Jest configuration and setup helpers.
xray16/mocks	Lua-like runtime helpers for Node-based tests.
xray16/typedefs/*	Opt-in ambient declarations for X-Ray and bundled Lua libraries.
xray16/plugins/*	TypeScriptToLua build plugins.

Next steps

• Engine types and aliases — import declarations that match the Lua binding dump, or TypeScript-friendly aliases.
• Macros and shared lib — compile-time helpers and shared constants.
• Testing — run X-Ray script code under Node with jest.
• Ambient typedefs — opt-in globals for bundled Lua libraries.
• TypeScriptToLua plugins — build transforms for game builds.