Stalker XRF Book

This book documents the X-Ray Forge script engine, build pipeline, CLI tools, and supporting modding workflow for S.T.A.L.K.E.R.: Call of Pripyat projects.

Use it when you need to:

• set up the XRF engine project locally;
• build scripts, configs, UI forms, translations, and resources into target/gamedata;
• use the local CLI for linking, verification, packaging, engine switching, and asset utilities;
• understand how the rewritten TypeScript script engine maps to X-Ray Lua scripts;
• debug game logic, UI, weather, logs, and runtime state.

The implementation source lives in stalker-xrf-engine. This book should describe behavior that is implemented there or in the sibling XRF tool/resource repositories.

Links

• XRF X-Ray 16 SDK
• XRF engine repository
• XRF tools repository
• XRF binaries repository
• Book repository

Resource Repositories

• Base assets
• Extended assets
• English locale assets
• Ukrainian locale assets
• Russian locale assets

References

• This site is built with mdBook.
• XRF targets OpenXRay as the main engine fork.

Changes

This page summarizes the main differences XRF introduces compared with a vanilla Call of Pripyat script and data setup.

Development Workflow

• TypeScript source is compiled to Lua scripts with TypeScriptToLua.
• The repository includes a local CLI for building, linking, verification, packaging, engine switching, and asset tools.
• UI XML can be generated from JSX sources.
• LTX/XML configs can be generated from TypeScript sources.
• Translations can be generated from JSON sources and checked with CLI utilities.
• Jest tests and X-Ray/Lua fixtures cover runtime logic without launching the game.

Build Pipeline

• Build targets are split into scripts, UI, configs, translations, and resources.
• Generated output is written to target/gamedata.
• Static resources can be copied from base, override, and locale-specific roots.
• Package commands can create mod or game output under target.
• Verification commands check project setup, gamedata, LTX, and particles data.

Script Engine

• The original Lua script engine is rewritten in TypeScript.
• Runtime logic is organized into managers, schemes, binders, registries, utilities, and typed domain constants.
• The project uses typed declarations for X-Ray engine APIs through xray16 and local typedefs.
• Events and callbacks are centralized so game systems can be tested and extended more predictably.

Gameplay and Extensions

XRF aims to preserve the original plot and baseline behavior while making systems easier to test, optimize, and extend. Larger gameplay changes should be isolated as extensions where possible.

Current extension-oriented work includes optional start-position behavior and other modular gameplay changes under src/engine/extensions.

Documentation and Tasks

Project task boards track ongoing work:

• Script engine
• Game engine
• CLI and tools
• Documentation

Credits

XRF builds on work from the S.T.A.L.K.E.R. and OpenXRay modding ecosystem.

• TypeScriptToLua
• OpenXRay
• Absolute Nature
• AtmosFear
• Call of Chernobyl
• Anomaly
• Universal ACDC

This community project is not affiliated with GSC Game World.

Installation

This page describes a local development setup for stalker-xrf-engine.

Requirements

• Windows development environment.
• Node.js with npm.
• Git with submodule support.
• Installed S.T.A.L.K.E.R.: Call of Pripyat.

The project can locate the Steam installation for app id 41700. For a non-Steam copy, configure the fallback game path in cli/config.json.

Set Up the Project

Clone the engine repository and install dependencies:

git clone https://github.com/xray-forge/stalker-xrf-engine.git
cd stalker-xrf-engine
npm install
npm run setup

npm run setup initializes and updates the repository submodules. The important submodules are src/resources for base game resources and cli/bin for bundled binaries and tooling.

Link the Game

Run the project verification before linking:

npm run verify

Link the built target/gamedata folder, logs, and game folder paths:

npm run cli -- link

Switch to one of the bundled engine variants:

npm run cli -- engine list
npm run cli -- engine use release

Use engine rollback if you need to restore the default game executable.

Build and Start

Build the gamedata output:

npm run build

Start the configured game executable:

npm run cli -- start_game

The build output is written to target/gamedata. Do not edit files there by hand; edit sources under src/engine and rebuild.

Updating Submodules

Update submodules when resource or binary repositories change:

git submodule update --init --recursive

Local OpenXRay Builds

For a locally built OpenXRay executable, follow the OpenXRay Windows build guide, then configure or copy the executable into the engine location used by the CLI. Use npm run cli -- engine info to inspect the currently selected engine.

XRF Engine

XRF is a TypeScript rewrite of the S.T.A.L.K.E.R.: Call of Pripyat script engine. The source is compiled to Lua scripts with TypeScriptToLua and packaged with generated configs, UI XML, translations, and static game resources.

The engine repository also includes a Node-based CLI for common modding tasks:

• building target/gamedata;
• linking the project to a local game installation;
• switching bundled OpenXRay engine binaries;
• verifying project data;
• packing mod or game distributions;
• formatting and checking generated data sources.

Source Layout

The main engine source is under src/engine:

• scripts contains TypeScript entry points that become Lua scripts.
• core contains runtime systems, schemes, managers, objects, and utilities.
• configs contains static and generated LTX/XML config sources.
• forms contains JSX/XML UI form sources.
• translations contains JSON and XML translation sources.
• extensions contains optional gameplay modules.

Build output and generated artifacts go under target/.

Development Model

Most work starts in TypeScript or source data files and then goes through the CLI build pipeline. The generated files are runtime artifacts for X-Ray; the source of truth stays in the repository.

Building

The build command compiles and copies XRF source files into X-Ray-compatible gamedata output under target/gamedata.

npm run build
npm run cli -- build

Build Targets

The build target names are:

• scripts
• ui
• configs
• translations
• resources

By default, build runs all targets. Use --include for focused builds and --exclude to skip targets:

npm run cli -- build --include scripts configs
npm run cli -- build --exclude resources

Options

• -i, --include <targets...>: build only selected targets.
• -e, --exclude <targets...>: build all targets except selected targets.
• -v, --verbose: print verbose build logs.
• -l, --language <language>: build with a locale from cli/config.json.
• -f, --filter <targets...>: filter source files by regular-expression strings.
• -c, --clean: remove target/gamedata before building.
• --nl, --no-lua-logs: strip Lua logger calls from the compiled script output.
• --na, --no-asset-overrides: skip configured override and locale resource roots.
• --itz, --inject-tracy-zones: inject Tracy profiling zones into compiled scripts.

Filters must be used with an explicit --include target. The build command rejects filtered implicit all builds.

Build Steps

When all targets run, the build performs these steps:

1. optionally clean target/gamedata;
2. compile TypeScript scripts to Lua;
3. render dynamic UI forms and copy static UI XML;
4. render dynamic configs and copy static LTX/XML configs;
5. build translations;
6. copy static resources;
7. write metadata.json;
8. collect the build log.

Examples

npm run cli -- build
npm run cli -- build --clean
npm run cli -- build --include ui
npm run cli -- build --include configs --filter system.ltx
npm run cli -- build --exclude resources
npm run cli -- build --no-lua-logs --inject-tracy-zones

Output

The command writes generated gamedata to target/gamedata and collects a build log in target/xrf_build.log.

Do not edit target/gamedata by hand. Change the source file and rebuild.

Build Clean

Clean builds remove the previous target/gamedata output before the selected build targets run.

The option is implemented by the build command, not by individual config or script generators. When --clean is set, the build process removes the whole target/gamedata directory before running the selected build filters.

Use a clean build when generated output may contain stale files, for example after deleting or renaming scripts, configs, forms, translations, or resources:

npm run cli -- build --clean
npm run cli -- build -c

The clean step removes target/gamedata. It does not change source files under src/engine, src/resources, or external resource repositories.

When to use it

Use a clean build after:

• deleting or renaming source files;
• changing build filters and wanting to remove output from previous filters;
• switching between resource sets or generated config layouts;
• preparing output before compress, pack game, or pack mod.

Skip it during tight iteration when you are only changing a file that the selected build step overwrites deterministically.

Building Scripts

The scripts build target compiles TypeScript under src/engine/scripts and related imported engine code to Lua with TypeScriptToLua.

The output is written into target/gamedata as X-Ray script files. The generated bundle also includes lualib_bundle.script, which provides helper functions emitted by TypeScriptToLua.

Build Only Scripts

npm run cli -- build --include scripts
npm run cli -- build -i scripts

Use --no-lua-logs when you want compiled scripts without Lua logger calls:

npm run cli -- build -i scripts --no-lua-logs

Use --inject-tracy-zones when profiling with Tracy support:

npm run cli -- build -i scripts --inject-tracy-zones

Watch Mode

Use watch mode during script development:

npm run watch:scripts

Additional script watch commands are available for optimized and Tracy-instrumented builds:

npm run watch:scripts-optimized
npm run watch:scripts-tracy
npm run watch:scripts-tracy-optimized

Type Checking

Run TypeScriptToLua type checking without emitting files:

npm run typecheck

When script compilation reports diagnostics, use typecheck for a focused failure report.

Type Definitions

X-Ray engine APIs are exposed through TypeScript declarations from the xray16 package and the XRF typedefs under src/typedefs. Use the generated type documentation when checking engine class, method, and enum names:

• XRF X-Ray 16 SDK source
• XRF X-Ray 16 SDK documentation

Luabind Classes

XRF uses custom TypeScriptToLua transforms for luabind-style classes. Classes that need engine-compatible luabind registration use project decorators and generated Lua class shapes instead of plain TypeScriptToLua metatable classes.

Building UI

The UI build target writes game UI XML files to target/gamedata/configs/ui.

It processes sources from src/engine/forms:

• .ts and .tsx files that export create() are rendered to .xml with renderJsxToXmlText;
• static .xml files are copied as-is;
• *.test.* files are ignored by the replication helper.

Build Only UI

npm run cli -- build --include ui
npm run cli -- build -i ui

Use a filter when you only need a subset of files:

npm run cli -- build -i ui --filter main_menu

Filters are regular-expression strings matched against source file paths.

Authoring Forms

Dynamic forms use JSX-compatible TypeScript. The generated output is XML for the game engine, so form layout still has to respect X-Ray UI constraints such as absolute coordinates and parent-relative positioning.

Look at existing files in src/engine/forms before adding new forms. Reuse shared helpers and components where they already exist.

Aspect Ratios

X-Ray UI XML often has separate layout expectations for 16:9 and 4:3 modes. Keep generated forms compatible with the target screen mode and verify in game when changing layout-sensitive XML.

Building Configs

The configs build target writes LTX and XML files to target/gamedata/configs.

It processes sources from src/engine/configs:

• dynamic .ts files export create() or config and render to .ltx;
• dynamic .tsx files export create() and render to .xml;
• static .ltx and .xml files are copied as-is;
• *.test.* files are ignored.

Build Only Configs

npm run cli -- build --include configs
npm run cli -- build -i configs

Use filters for focused rebuilds:

npm run cli -- build -i configs --filter system.ltx

Filters are regular-expression strings matched against source file paths. The build command does not allow filters with the implicit all target, so combine --filter with --include.

Dynamic LTX

Dynamic LTX configs use structured TypeScript descriptors and renderJsonToLtx. This is useful when a config needs shared constants, loops, generated sections, or tests.

Static LTX is still appropriate for simple files that do not need build-time logic.

Dynamic XML

Dynamic XML configs use JSX and renderJsxToXmlText. They are separate from UI forms: config XML is built from src/engine/configs, while UI XML is built from src/engine/forms.

Validation

Use the LTX verifier after config changes:

npm run cli -- verify ltx

Strict mode is available for stricter checks:

npm run cli -- verify ltx --strict

Building Translations

The translations build target writes text files to target/gamedata/configs/text.

Translation sources live in src/engine/translations. The build step delegates to the bundled XRF tools binary and passes the source path, output path, and verbosity mode.

Build Only Translations

npm run cli -- build --include translations
npm run cli -- build -i translations

Selecting a Language

The default locale is configured in cli/config.json as locale. The current default is ukr.

Override it for a build with --language:

npm run cli -- build --include translations --language eng

Supported locale keys are listed in cli/config.json under available_locales.

Locale Resource Packs

Resource packs for voice and localized assets are configured under resources.mod_assets_locales in cli/config.json. When asset overrides are enabled, the resources build includes override folders plus the locale folders for the selected language.

JSON and XML Sources

XRF uses JSON translation sources for generated multilingual output and can also copy static XML translation files where they are part of the source tree. Use the translation CLI commands when converting existing game XML into JSON sources.

Building Resources

The resources build target copies static game assets into target/gamedata.

The base resource root is configured in cli/config.json as resources.mod_assets_base_folder and points to src/resources. Additional override and locale roots can be configured in the same file.

Build Only Resources

npm run cli -- build --include resources
npm run cli -- build -i resources

Use filters for focused resource copies:

npm run cli -- build -i resources --filter textures

Filters are regular-expression strings matched against source file paths.

Diff Checking

Directory resources use a diff check before copy. On non-clean builds, unchanged files are skipped, which keeps static asset rebuilds faster.

Use --clean when you need to force a fresh target/gamedata tree.

Additional Assets

Clone configured resource repositories with:

npm run cli -- clone --list
npm run cli -- clone extended
npm run cli -- clone locale-ukr

The configured roots are:

• resources.mod_assets_override_folders for general overrides;
• resources.mod_assets_locales for locale-specific assets.

Disable override roots for a build with --no-asset-overrides:

npm run cli -- build --no-asset-overrides

Resource Links

• Base assets
• Extended assets
• English locale assets
• Ukrainian locale assets
• Russian locale assets

CLI

The XRF engine repository includes a local Node CLI. It is wired in cli/run.ts with Commander and is normally run from the repository root.

Use the npm wrapper:

npm run cli -- <command>

Common package scripts wrap frequently used commands:

npm run build
npm run verify
npm test

Command Groups

The CLI registers commands for building, cloning extra resources, compression, engine management, formatting, icons, linking, logs, opening folders, packaging, parsing, particles, spawn files, starting the game, translations, and verification.

See the command list for a quick index.

Working directories and output

Run commands from the repository root unless a page says otherwise. Most defaults are repository-relative and come from cli/config.json.

Generated output belongs under target/: built gamedata, parsed helper files, coverage, packed archives, and package output. Source edits belong under src/engine, src/resources, cli, or the relevant external resource repository.

Global Alias

package.json exposes the binary name xrf, but local development should prefer npm run cli -- ... so the command uses the repository version and local dependencies.

If the package is installed globally or run through an npm executor, the equivalent command shape is:

xrf build
xrf verify project

Configuration

Most CLI defaults live in cli/config.json: locale, resource roots, build source paths, target paths, compression tools, package roots, and game executable settings.

When a command cannot find the game, resources, or generated output, check the command page first and then inspect the matching config key in cli/config.json.

CLI Configuration

The engine CLI reads its defaults from cli/config.json.

This file controls:

• default locale and supported locale keys;
• base, override, and locale resource roots;
• source paths for configs, scripts, translations, extensions, and UI forms;
• target output path;
• compression and helper binary paths;
• default package engine and root package assets;
• game executable and fallback game path.

Locale

locale is the default language used by builds. available_locales defines the accepted locale keys.

Override the locale for a build with:

npm run cli -- build --language eng

Locale-specific resource roots are configured in resources.mod_assets_locales.

Resources

resources.mod_assets_base_folder points to the base resources folder. In the engine repo this is src/resources.

resources.mod_assets_override_folders lists additional asset roots. resources.mod_assets_locales maps locale keys to locale resource roots. These roots are included by the resources build unless --no-asset-overrides is passed.

Build Paths

The build section maps source folders:

• configs -> src/engine/configs
• scripts -> src/engine/scripts
• translations -> src/engine/translations
• extensions -> src/engine/extensions
• ui -> src/engine/forms

Generated output goes under target/gamedata.

Non-Steam Game Path

The targets section contains the Steam app id, fallback game path, and game executable name. Update stalker_game_fallback_path if the CLI cannot locate a non-Steam installation automatically.

Project Commands and Scripts

Run package scripts from the repository root:

npm run <script>

Run CLI commands through the local wrapper:

npm run cli -- <command>

Package Scripts

• setup: initialize and update submodules.
• verify: run verify project.
• build: build scripts, configs, UI, translations, and resources.
• pack:mod: build a mod package.
• pack:game: build a game package.
• watch:scripts: rebuild scripts when TypeScript sources change.
• typecheck: run TypeScriptToLua type checking without emitting files.
• typecheck:tests: type-check test sources with TypeScript.
• lint: run ESLint.
• lint:strict: run the stricter ESLint config.
• test: run Jest.
• test:coverage: run Jest coverage.
• format: run Prettier, ESLint fix, and LTX formatting.
• help: print CLI help.

CLI Commands

• build: build target/gamedata.
• clone: clone configured additional resource repositories.
• compress: compress built gamedata into archives.
• engine: inspect, switch, list, or roll back bundled engines.
• format ltx: format LTX files.
• icons: pack and unpack equipment icons and texture descriptions.
• link, unlink, relink: manage project links to the local game installation.
• logs: print the last lines from the linked game log.
• open_game_folder, open_project_folder: open configured folders.
• pack: create mod or game packages.
• particles: pack or unpack particles.xr.
• parse: parse directory trees or game externals.
• spawn: unpack ALife spawn files.
• start_game: start the configured game executable.
• translations: initialize, convert, and check translation files.
• verify: run project, gamedata, LTX, and particles verification commands.

Use npm run cli -- <command> --help for command-specific options.

Build

build compiles and copies XRF source assets into target/gamedata. Use it before linking the project into a game installation, packaging a mod, or validating generated configs/scripts.

npm run cli -- build

What it builds

The build also writes target/gamedata/metadata.json and stores a build log under target/logs.

Options

• -i, --include <targets...>: build only selected targets. Choices are scripts, ui, configs, translations, and resources.
• -e, --exclude <targets...>: skip selected targets. This conflicts with --include.
• -f, --filter <targets...>: filter copied/generated files by regular-expression strings. Use it only with a specific included target, not with the default all target set.
• -l, --language <language>: use a locale from cli/config.json. The default is ukr.
• -c, --clean: remove target/gamedata before building.
• --nl, --no-lua-logs: strip Lua logger calls from the compiled script output.
• --na, --no-asset-overrides: skip configured override and locale resource roots when copying resources.
• --itz, --inject-tracy-zones: inject Tracy profiling zones while compiling scripts.
• -v, --verbose: print verbose build logs.

Examples

npm run cli -- build --clean
npm run cli -- build --include scripts configs
npm run cli -- build --include configs --filter system.ltx
npm run cli -- build --exclude resources
npm run cli -- build --include scripts --no-lua-logs

Failure notes

• Unsupported locales fail before asset copying starts.
• --filter with the default all include set fails; choose a concrete target first.
• TypeScriptToLua diagnostics fail the script build. Run npm run typecheck for a focused error list.

Clone

clone downloads optional resource repositories configured in cli/config.json. The command clones into the parent folder of the engine repository, next to stalker-xrf-engine.

npm run cli -- clone <repository>

Repository names

Use --list to print the configured names:

npm run cli -- clone --list

Current configured names include:

• extended: full base gamedata assets for custom game packages;
• locale-eng: English locale resources;
• locale-ukr: Ukrainian locale resources;
• locale-rus: Russian locale resources.

Options

• -l, --list: print configured repository names and exit.
• -v, --verbose: print verbose logs.
• -f, --force: remove an existing target folder before cloning.
• -s, --safe: treat an already cloned target folder as success.

--force and --safe conflict with each other.

Examples

npm run cli -- clone extended
npm run cli -- clone locale-ukr --safe
npm run cli -- clone extended --force

Failure notes

The command fails when the repository name is missing, not configured, or already cloned without --safe or --force. It runs git clone, so network and credentials errors come from Git.

Compress

compress packs built target/gamedata content into database archives with xrCompress. Use it after build when you need DB archives for a game package.

npm run cli -- compress

Targets

Compression target definitions live in cli/compress/configs/compress.json.

Output archives are written under target/db as <target>.dbN.

Options

• -i, --include <targets...>: compress selected targets. Defaults to all.
• -c, --clean: remove target/db before writing archives.
• -v, --verbose: print xrCompress output.

Examples

npm run cli -- build --clean
npm run cli -- compress --clean
npm run cli -- compress --include configs shaders

Inputs and output

The command reads built files from target/gamedata and writes database archives under target/db. It does not build missing gamedata by itself, so run build first when source files changed.

Use --include for fast package checks when only one archive group changed. Use --clean before producing a package that should not contain stale archives from a previous target set.

Failure notes

target/gamedata must exist. If compression target names are wrong, the command prints the valid names from the compression config.

Engine

engine manages bundled OpenXRay engine binaries under cli/bin/engines. It switches the game installation’s bin folder to a selected bundled engine by creating a junction.

npm run cli -- engine <command>

Commands

Examples

npm run cli -- engine list
npm run cli -- engine use release
npm run cli -- engine info
npm run cli -- engine rollback

How switching works

When engine use <engine> sees an unlinked game bin folder, it renames it to the XRF backup path and then links the selected bundled engine. When the current bin is already linked, it removes the old link and creates a new one.

engine rollback only restores the backup when a backup folder exists and the current bin folder is an XRF-linked engine with bin.json.

Related commands

pack game --engine <type> selects a bundled engine for package output without switching the local game installation.

Format

format contains project-specific formatting commands. The current CLI subcommand formats LTX config sources with the same formatter used by validation tooling.

npm run cli -- format ltx

Options

• -c, --check: check formatting without rewriting LTX files.
• -v, --verbose: print verbose formatter logs.

Examples

npm run cli -- format ltx
npm run cli -- format ltx --check

Inputs and output

format ltx reads LTX config sources from the repository and either rewrites them or reports formatting differences when --check is set. It is useful before verify ltx because it normalizes layout without changing config meaning.

Run the check form in review or CI-style validation. Run the writing form when you intentionally want the formatter to update files.

Package script difference

The package script is broader:

npm run format

It runs Prettier for JavaScript, TypeScript, TSX, and Markdown, then ESLint fix, then npm run cli -- format ltx. Use the CLI command when you only want LTX formatting.

Icons

icons wraps texture tooling from cli/bin/tools/xrf-cli. It packs and unpacks equipment icon sprites and UI texture description sprites using project paths from cli/config.json.

npm run cli -- icons <command>

Commands

Options

All icon commands support:

• -v, --verbose: print verbose logs.
• -s, --strict: enable strict mode.

Description commands also support:

• -d, --description <name>: process one file under src/engine/forms/textures_descr.

Examples

npm run cli -- icons unpack-equipment
npm run cli -- icons pack-equipment --strict
npm run cli -- icons unpack-descriptions --description ui_actor.xml
npm run cli -- icons pack-descriptions --description ui_actor.xml

Workflow

Unpack before editing icon sprites or checking generated sprite coordinates. Pack after editing the unpacked files or texture descriptions. Use --description when working on a single UI texture description file instead of the whole description set.

Equipment commands are tied to the equipment icon atlas. Description commands are tied to XML texture description files under src/engine/forms/textures_descr.

Failure notes

Equipment commands depend on valid system.ltx icon coordinates. Description commands depend on XML description names and matching source textures.

Link

link, unlink, and relink connect the build output and game folders used during local development.

npm run cli -- link

What gets linked

Game paths come from Steam detection or the fallback values in cli/config.json.

Commands

• link: create the game, gamedata, and logs links.
• unlink: remove the gamedata link, logs link, and game link.
• relink: run unlink, then link.

link and relink support -f, --force to remove existing link targets first. Use it carefully: if a real game gamedata folder exists, --force removes it before creating the link.

Examples

npm run cli -- build --clean
npm run cli -- link
npm run cli -- relink --force
npm run cli -- unlink

Failure notes

If linking fails, verify the configured game path, executable name, and Steam installation detection. verify project checks the same paths.

Lint

Linting is exposed through package scripts, not a Commander subcommand. Use it for TypeScript, TSX, and CLI source style checks.

npm run lint

Commands

The standard command stores its cache under target/eslint/cache.json.

Examples

npm run lint
npm run lint:strict
npm run lint -- --fix

Inputs and output

Lint reads TypeScript, TSX, and JavaScript sources from the repository and reports rule violations to the terminal. The standard script reuses the ESLint cache, so repeated runs after small edits are faster than a cold run.

Use the normal lint command during documentation-adjacent code edits or focused implementation work. Use strict lint before larger changes when you want the additional repository checks.

Related checks

Use npm run typecheck for TypeScriptToLua script type checks and npm run typecheck:tests for test TypeScript checks. Use npm test for Jest.

Logs

logs prints the tail of the active engine log from the configured game logs folder.

npm run cli -- logs
npm run cli -- logs 100

Behavior

The optional argument is the number of lines to print. Invalid values fall back to 15, and the command caps output at 200 lines.

The command detects the log file from the configured game paths:

• when bin/bin.json exists, it expects openxray_<username>.log;
• otherwise it expects xray_<username>.log.

It reads from the real game logs folder. If you ran link, the same folder is also reachable through target/logs_link.

Examples

npm run cli -- logs
npm run cli -- logs 50
npm run cli -- logs 500

The last example still prints at most 200 lines.

When to use it

Use logs after start_game or a manual game launch to inspect the newest script/runtime messages without navigating to the game logs folder. It is the fastest check after a crash during startup, a failed script reload, or a missing file reported by the engine.

For longer inspection, open the linked logs folder or the real game logs directory and use an editor that can follow file updates.

Failure notes

If no active log is found, start the game once, check the configured game path, or run npm run cli -- link to create the logs link for easier inspection.

Open

Open commands launch the system file explorer for common project and game folders.

npm run cli -- open_game_folder
npm run cli -- open_project_folder

Commands

open_game_folder uses the same game path resolution as link, logs, start_game, and verify project. open_project_folder uses the repository root detected from the CLI process location.

Examples

npm run cli -- open_game_folder
npm run cli -- open_project_folder

When to use it

Use open_game_folder when checking linked gamedata, engine logs, or installed game binaries after build and link. Use open_project_folder when a script or tool printed a project-relative path and you want to inspect the source tree from Explorer.

These commands do not build, link, or verify files. They only open the resolved folders.

Failure notes

If the game folder does not open, check cli/config.json under targets or run npm run cli -- verify project to see which path is being resolved.

Pack

pack creates distributable mod or game folders from the project.

npm run cli -- pack <type>

<type> must be mod or game.

Output

Options

• --nb, --no-build: package already built assets without running build.
• --nc, --no-compress: for game packages, skip archive compression and copy all gamedata.
• --na, --no-asset-overrides: pass through to build and skip override/locale resource roots.
• -e, --engine <type>: use a bundled engine from cli/bin/engines.
• --se, --skip-engine: do not include engine binaries. This is allowed for mod packages and rejected for game.
• -o, --optimize: build scripts without Lua logs.
• -v, --verbose: print verbose logs.
• -c, --clean: remove the package output folder first.

Examples

npm run cli -- pack mod --clean
npm run cli -- pack mod --skip-engine --no-build
npm run cli -- pack game --clean --optimize
npm run cli -- pack game --engine release
npm run pack:mod
npm run pack:game

Failure notes

Game packages require a valid bundled engine. Compressed game packages also require successful build and compression steps, because target/db is copied into the package.

Particles

particles wraps the external XRF tools binary for packing and unpacking particles.xr.

npm run cli -- particles <command>

Commands

Options

Both subcommands support:

• -p, --path <path>: source file or source directory.
• -d, --dest <dest>: output file or output directory.
• -v, --verbose: print verbose logs.
• -f, --force: remove an existing output before writing.

Examples

npm run cli -- particles unpack
npm run cli -- particles unpack --force
npm run cli -- particles pack
npm run cli -- particles pack --path src/resources/particles_unpacked --dest src/resources/particles.xr

Workflow

Unpack first when you need to inspect or edit particle definitions as files. Pack after edits to rebuild particles.xr for resources or packaging. Use --force when replacing a previous unpacked folder or packed output.

The command delegates to the bundled XRF tools binary. If you need lower-level particle conversion commands outside the engine repository defaults, use the Tools CLI particle commands directly.

Related verification

npm run cli -- verify particles-packed
npm run cli -- verify particles-unpacked

Parse

parse contains utility commands that generate JSON or HTML support files under target/parsed.

npm run cli -- parse <command>

Commands

dir_as_json resolves <path> relative to the repository root.

Options

parse dir_as_json supports:

• -e, --no-extension: omit file extensions in JSON values.

Examples

npm run cli -- parse dir_as_json src/resources/textures
npm run cli -- parse dir_as_json src/resources/textures --no-extension
npm run cli -- parse externals

Output usage

Use dir_as_json when another script needs a compact index of files under a resource folder. The command writes generated support data under target/parsed, so treat the result as disposable build output.

Use parse externals when checking the script declaration surface exposed by conditions, effects, and dialogs. The generated HTML is a local reference; edit the TypeScript declaration sources to change the exported behavior.

Failure notes

dir_as_json requires a path argument. parse externals reads TypeScript declaration sources under src/engine/scripts/declarations and skips tests and index files.

Spawn

spawn contains ALife spawn file utilities. The engine CLI currently exposes the unpack workflow.

npm run cli -- spawn unpack

Defaults

The command delegates to cli/bin/tools/xrf-cli unpack-spawn.

Options

• -p, --path <path>: source spawn file path.
• -d, --dest <dest>: output directory.
• -v, --verbose: print verbose logs.
• -f, --force: remove an existing unpacked destination before writing.

Examples

npm run cli -- spawn unpack
npm run cli -- spawn unpack --force
npm run cli -- spawn unpack --path src/resources/spawns/all.spawn --dest target/all_spawn

Output

The output directory contains the unpacked spawn representation produced by the XRF tools CLI. The engine wrapper is intended for inspection and verification workflows in this repository; it does not expose pack or repack commands.

Keep generated unpack output under target/ unless you are intentionally preparing source data for another tool.

Failure notes

The source spawn file must exist. Use the Tools CLI spawn commands when you need lower-level spawn info, pack, repack, or verification operations.

Start

start_game starts the configured game executable.

npm run cli -- start_game

The executable path is resolved from the same game-path logic used by link, open_game_folder, logs, and verify project. Configuration lives in cli/config.json under targets:

• stalker_game_steam_id: Steam app id used for automatic detection;
• stalker_game_fallback_path: fallback game folder when Steam detection is not enough;
• stalker_app_path: executable name inside the game folder.

Typical workflow

npm run cli -- build --clean
npm run cli -- link
npm run cli -- start_game

Inputs and output

The command reads the configured game target and launches the executable from that folder. It does not rebuild scripts, copy gamedata, or wait for the engine process to finish.

Use it after build and link when you want to test the currently linked project output. Use logs after the game starts if you need the script engine error output.

Failure notes

If the process does not start, run npm run cli -- verify project and check the resolved game folder and executable. The command starts the executable asynchronously, so later runtime errors are written to the engine log rather than to the CLI process.

Test

Tests are run through package scripts rather than a Commander subcommand. The project uses Jest with the config at cli/test/jest.config.ts.

npm test

Common commands

Coverage output is written under target/coverage_report.

Examples

npm test
npm test -- src/engine/scripts/register.test.ts
npm run test:coverage
npm run typecheck
npm run typecheck:tests

Notes

Runtime tests use fixtures and mocks under src/fixtures for X-Ray APIs, Lua behavior, engine helpers, and CLI utilities. Use focused Jest paths first when changing a specific manager, scheme, binder, or CLI helper.

The typecheck commands do not execute tests. They catch TypeScript and TypeScriptToLua issues that can pass Jest when a mocked runtime path is not exercised. For gameplay logic changes, run the focused Jest test and npm run typecheck before broader validation.

Translations

translations contains helper commands for JSON translation sources and original X-Ray XML string tables.

npm run cli -- translations <command>

Commands

The configured languages come from cli/config.json. Current locales are eng, fra, ger, ita, pol, rus, spa, and ukr.

Options

init supports:

• -v, --verbose: print verbose logs.

to_json supports:

• -l, --language <locale>: language key to fill from the XML text.
• -c, --clean: clean the output path before writing.
• -o, --output <path>: output file or directory. Defaults to target/parsed.
• -e, --encoding <encoding>: source XML encoding. If omitted, the command tries to read the XML header and then uses locale defaults.
• -v, --verbose: print verbose logs.

check supports:

• -l, --language <locale>: check one language instead of all languages.
• -s, --strict: fail on missing entries.
• -v, --verbose: print verbose logs.

Examples

npm run cli -- translations init src/engine/translations/st_dialogs.json
npm run cli -- translations to_json configs/text/eng --language eng --output src/engine/translations
npm run cli -- translations check
npm run cli -- translations check --language ukr --strict

Failure notes

to_json requires a known locale. When converting a folder, the output path must be a directory, not a single file.

Verify

verify runs project and gamedata validation commands.

npm run cli -- verify <command>

The package script npm run verify is shorthand for npm run cli -- verify project.

Commands

Options

• verify gamedata -v, --verbose: print verbose external-tool logs.
• verify ltx -s, --strict: run strict LTX validation.
• verify ltx -v, --verbose: print verbose external-tool logs.
• Particle verification commands support -v, --verbose.

Examples

npm run verify
npm run cli -- verify project
npm run cli -- verify ltx
npm run cli -- verify ltx --strict
npm run cli -- verify gamedata --verbose
npm run cli -- verify particles-packed

Failure notes

verify project reports setup problems but catches its own top-level error. verify ltx and particle verification delegate to the tools binary and fail the process on invalid data.

Extensions

Extensions are optional script modules loaded from gamedata/extensions. They let XRF keep larger gameplay changes separate from the core script engine.

The engine scans extension folders, loads each main.script, synchronizes the list with saved user preferences, and registers enabled extensions during game start.

Extension Entry Point

Each extension has its own folder under extensions and an entry file named main.script after build output.

The module can export:

• register(isNewGame, extension): called when the extension is enabled.
• unregister(isNewGame, extension): optional cleanup hook called when the extension is disabled.
• save(data): optional hook for extension dynamic data.
• load(data): optional hook for restoring extension dynamic data.

The TypeScript sources for built-in extensions live under src/engine/extensions.

Runtime State

Loaded extensions are stored in the runtime registry by name. The load order and enabled state are saved to extensions_order.scopo in the game saves folder.

The main menu includes an extensions dialog. It lets the user reorder extensions and toggle extensions that declare they can be toggled.

Built-In Extensions

The current engine source includes these extension folders:

Use the built-in extension pages as implementation references when adding a new extension:

• Achievement rewards
• Enhanced items drop
• Enhanced location progression
• Enhanced treasures
• Original start position

Config Files

Extensions can open extension-local LTX files through the extension utilities. main.ltx is the default relative file name when no file name is provided.

Limitations

The current implementation covers discovery, ordering, enabling/disabling, registry registration, and save/load hooks. More advanced extension packaging, dependency declarations, and extension-specific build steps should be treated as future work unless the source adds them.

Achievement Rewards

Achievement rewards restores periodic reward spawns for selected vanilla achievements.

The source lives under src/engine/extensions/achievements_rewards.

Default State

The extension exports:

export const name = "Achievement rewards";
export const enabled = true;

It is enabled by default unless saved extension state overrides it.

Runtime Behavior

On registration, the extension subscribes to EGameEvent.ACTOR_UPDATE.

Each update checks whether the actor has gained these info portions:

• detective_achievement_gained;
• mutant_hunter_achievement_gained.

When the configured period has elapsed, it spawns reward items into the configured actor treasure box and emits a tip notification.

Rewards

The reward period is 12 * 60 * 60 game seconds.

Reward targets:

The spawn count is fixed in the update code: detective rewards spawn with count 4, and mutant hunter rewards spawn with count 5.

Save Data

The extension persists two timestamps in dynamic extension data:

• lastDetectiveAchievementSpawnAt;
• lastMutantAchievementSpawnAt.

The timestamps are serialized through the time helpers and restored on extension load.

Editing Notes

• Keep reward timing in AchievementRewardsConfig.ts.
• Keep achievement checks in update.ts.
• Add save/load fields when adding a new persistent reward timer.
• Keep notification captions aligned with translation ids.

Enhanced Items Drop

Enhanced items drop (with upgrades) adds random upgrades to weapons, outfits, and helmets when those items go online for the first time.

The source lives under src/engine/extensions/enhanced_items_drop.

Default State

The extension exports:

export const name = "Enhanced items drop (with upgrades)";
export const enabled = false;

It is disabled by default. Saved extension state can enable it.

Runtime Behavior

On registration, the extension subscribes to:

• ITEM_WEAPON_GO_ONLINE_FIRST_TIME;
• ITEM_OUTFIT_GO_ONLINE_FIRST_TIME;
• ITEM_HELMET_GO_ONLINE_FIRST_TIME.

For each item, onItemGoOnlineFirstTime reads the owner id. Actor-owned items are skipped.

The extension then calculates a random chance and applies a different rate depending on whether the item belongs to:

• a trader;
• another owner;
• the world.

If the chance passes one of the configured thresholds, the extension calls addRandomUpgrades.

Upgrade Tiers

The default config lives in EnhancedDropConfig.ts.

The final upgrade count includes random dispersion from ADD_RANDOM_DISPERSION.

Save Data

This extension does not export save or load. It changes items when first-online item events are emitted.

Editing Notes

• Keep chance and count tuning in EnhancedDropConfig.ts.
• Keep item filtering in enhanced_items_drop_utils.ts.
• Do not apply this extension to actor-owned starting items unless that behavior is intentional.

Enhanced Location Progression

Enhanced location progression requires smart terrains to be discovered before some map and travel behavior can use them.

The source lives under src/engine/extensions/enhanced_location_progression.

Default State

The extension exports:

export const name = "Enhanced location progression";
export const enabled = true;

It is enabled by default unless saved extension state overrides it.

Runtime Behavior

On registration, the extension sets:

mapDisplayConfig.REQUIRE_SMART_TERRAIN_VISIT = true;

This flag is checked by map display and travel code.

Map Spots

updateTerrainsMapSpotDisplay shows global terrain spots only when:

• REQUIRE_SMART_TERRAIN_VISIT is disabled; or
• the actor has the "<terrain>_visited" info portion.

Restrictor lifecycle code gives visited info portions when the actor reaches the matching restrictor.

Travel

TravelManager.isSmartAvailableToReach rejects smart terrain travel targets on the current level when REQUIRE_SMART_TERRAIN_VISIT is enabled and the terrain has not been visited.

Save Data

This extension does not export save or load. It changes runtime config during extension registration.

Editing Notes

• Keep the progression toggle in main.ts.
• Check map and travel behavior together when changing this flag.
• Preserve visited info portion naming because other code checks "<terrain>_visited".

Enhanced Treasures

Enhanced treasures enables typed treasure map spots.

The source lives under src/engine/extensions/enhanced_treasures.

Default State

The extension exports:

export const name = "Enhanced treasures";
export const enabled = true;

It is enabled by default unless saved extension state overrides it.

Runtime Behavior

On registration, the extension sets:

treasureConfig.ENHANCED_MODE_ENABLED = true;

The treasure map helper uses this flag when choosing the map spot icon for a treasure descriptor.

Map Spots

When enhanced mode is disabled, every treasure uses the generic treasure map mark.

When enhanced mode is enabled, getTreasureMapSpot maps treasure type to mark:

Treasure state itself is still owned by TreasureManager and treasureConfig.TREASURES.

Save Data

This extension does not export save or load. Treasure manager state is saved by TreasureManager.

Editing Notes

• Keep the extension toggle in main.ts.
• Keep treasure type-to-icon behavior in map_spot_treasure.ts.
• Keep treasure state changes in TreasureManager, not in this extension.

Original Start Position

Original start position changes the actor’s start vertex and position for new games.

The source lives under src/engine/extensions/original_start_position.

Default State

The extension exports:

export const name = "Original start position";
export const enabled = false;

It is disabled by default. Saved extension state can enable it.

Runtime Behavior

The extension receives isNewGame from the extension registration flow.

When isNewGame is true, it calls:

set_start_game_vertex_id(287);
set_start_position(createVector(268, 20, 560));

When isNewGame is false, it does nothing. This prevents loaded saves from having their actor position changed.

Save Data

This extension does not export save or load.

Editing Notes

• Keep the isNewGame guard.
• Use engine start-position APIs only during new-game startup.
• Update tests if the vertex id or vector changes.
• Check the extension registration state when the code looks correct but the actor still starts elsewhere.

XRF Tools

stalker-xrf-tools is the companion tools workspace for XRF development. It contains reusable Rust crates, a CLI, and a Tauri desktop application.

Use it for tasks that are awkward to do by hand:

• reading and unpacking X-Ray archives;
• verifying and formatting LTX configs;
• converting and checking translations;
• inspecting script exports;
• packing and unpacking equipment icons and texture descriptions;
• inspecting or converting spawn, particles, OGF, and OMF data.

Repository Layout

• crates/: reusable Rust crates for X-Ray formats and project validation.
• bin/xrf-cli: command-line tool.
• bin/xrf-app: Tauri backend for the desktop application.
• bin/xrf-ui: React frontend for the desktop application.

The engine repository uses a bundled tools binary from cli/bin for some build and asset operations.

Interfaces

Use the desktop app for manual inspection and editing workflows. Use the CLI for repeatable scripts, CI checks, and engine build integration.

Choosing an interface

Use the CLI when the command must be repeatable, run in CI, or become part of an engine build step. Examples include LTX verification, translation builds, archive unpacking, spawn conversion, and texture packing.

Use the desktop app when you need to inspect structured project data with navigation: archives, configs, dialogs, exports, icons, spawns, and translations. Some app routes are read-only or prototype workflows; the page for each app tool calls out what is currently wired.

Source truth

Tool behavior comes from the tools workspace, not from the book text:

• CLI commands: stalker-xrf-tools/bin/xrf-cli/src/commands;
• desktop backend commands: stalker-xrf-tools/bin/xrf-app/src;
• desktop frontend routes: stalker-xrf-tools/bin/xrf-ui/src/applications;
• reusable format logic: stalker-xrf-tools/crates.

Tools Application

The XRF tools application is a Tauri desktop app backed by Rust commands and a React UI. Use it for manual inspection, visual browsing, and one-off conversion tasks while working with X-Ray game data.

The application source is split across:

• stalker-xrf-tools/bin/xrf-app: Tauri backend plugins and commands;
• stalker-xrf-tools/bin/xrf-ui: React routes, pages, stores, and components;
• stalker-xrf-tools/crates/*: reusable parsers, verifiers, packers, and project readers.

Tools

Project paths

The app stores selected XRF project and configs paths in local storage. Several tools use those paths to prefill common locations such as src/engine/configs, target/gamedata/spawns/all.spawn, target/game_link, and src/engine/translations.

CLI vs app

Use the app when you need to inspect data interactively. Use Tools CLI when the task should be repeatable, scripted, or run in CI.

Archive Editor

The archive editor works with X-Ray .db archive projects. It can open an archive set, show project metadata, read individual files as text, and unpack archives to a destination folder.

Screens

Backend commands

The Tauri archives-editor plugin exposes:

• open_archives_project;
• close_archives_project;
• has_archives_project;
• get_archives_project;
• read_archive_file;
• unpack_archives_path.

unpack_archives_path opens the selected archive path as an ArchiveProject and unpacks it in parallel with 32 workers.

Workflow

1. Use Open to inspect archives without extracting everything.
2. Use file reading from the editor view when you need to inspect a text file inside the archive.
3. Use Unpack when you need the archive contents on disk.

Default project-aware paths point the unpacker at target/game_link for source archives and target/unpacked_archives for output when an XRF project path is configured.

CLI equivalent

Use xrf-tool unpack-archive for repeatable unpacking from scripts.

Dialog Editor

The dialog editor is currently a prototype UI surface for dialog graph work. It is useful for checking the shape of the future graph editor, not for production dialog data editing.

Current routes

The current app source does not register a dialog-editor Tauri plugin and does not expose import, export, save, or validation commands for real dialog XML.

What is implemented

• A navigator page.
• A test graph with dialog and phrase node components.
• Client-side graph interactions through React Flow.

What is not implemented

• Opening engine dialog XML.
• Saving dialog XML.
• Validating phrase links or script predicates/actions.
• Synchronizing dialog text with translation files.

Production workflow

For real dialog changes, edit the engine sources directly:

• dialog XML under src/engine/configs/gameplay;
• dialog extern declarations under src/engine/scripts/declarations/dialogs;
• dialog text under src/engine/translations.

See Dialog configs for the current production documentation.

Config Editor

The config editor works with LTX config projects. The current production-ready workflows are verification and formatting.

Screens

Backend commands

The Tauri configs-editor plugin exposes:

• verify_configs_path;
• check_format_configs_path;
• format_configs_path.

Verification opens the folder with scheme checking enabled and strict checking disabled. Formatting uses the shared xray-ltx formatter.

Workflow

1. Select the configs folder. When an XRF project path is configured, the app can prefill src/engine/configs.
2. Run Verifier after config edits to inspect include, inheritance, section, and scheme errors.
3. Run Formatter in check mode first when reviewing changes.
4. Disable check mode only when you want the formatter to rewrite files.

CLI equivalent

Use xrf-tool verify-ltx and xrf-tool format-ltx for repeatable checks. In the engine repository, use npm run cli -- verify ltx and npm run cli -- format ltx.

Exports Viewer

The exports viewer reads script declaration folders and displays exported conditions, dialog functions, effects, and their parameter declarations.

Use it when editing config logic and you need to confirm which script externs are available.

Screens

Backend commands

The Tauri exports-editor plugin exposes:

• open_xr_exports: parse conditions, dialogs, and effects folders together;
• get_xr_exports;
• close_xr_exports;
• open_xr_effects;
• parse_xr_effects;
• get_xr_effects;
• close_xr_effects;
• has_xr_effects.

Source folders

When an XRF project path is configured, the UI can derive default declaration paths from:

• src/engine/scripts/declarations/conditions;
• src/engine/scripts/declarations/dialogs;
• src/engine/scripts/declarations/effects.

Notes

The viewer is read-only. To change exports, edit the declaration source files in the engine repository and reload the viewer.

Use the CLI-generated externs reference when you need a static artifact under target/parsed. Use the app viewer when you are browsing declarations interactively while editing configs.

If a condition or effect is missing from the viewer, check that it is declared in the expected conditions, dialogs, or effects folder and that the project path points at the engine repository you are editing.

Icon Editor

The icon editor works with equipment icon sprites and icon descriptor data. The fully wired workflow is equipment sprite opening and equipment icon packing.

Screens

Backend commands

The Tauri icons-editor plugin exposes:

• open_equipment_sprite;
• reopen_equipment_sprite;
• get_equipment_sprite;
• close_equipment_sprite;
• pack_equipment.

open_equipment_sprite reads the DDS as a PNG preview and reads equipment descriptors from system.ltx. pack_equipment packs source icons into a DDS using BC3 RGBA compression.

Workflow

1. Open the equipment sprite with the matching system.ltx.
2. Inspect section icon rectangles in the equipment editor.
3. Use Equipment pack when separate icon files should be packed into the final equipment DDS.

When an XRF project path is configured, the app tries to prefill common paths such as src/engine/configs/system.ltx and src/resources/textures/ui/ui_icon_equipment.dds.

CLI equivalent

Use xrf-tool unpack-equipment-icons, xrf-tool pack-equipment-icons, xrf-tool unpack-texture-description, and xrf-tool pack-texture-description when you need workflows that are not fully wired in the app.

Spawn Editor

The spawn editor opens and inspects ALife spawn data. It can read packed spawn files, import unpacked spawn folders, export unpacked data, and save packed spawn files.

Screens

Data views

The backend exposes accessors for:

• header data;
• graph data;
• ALife spawn objects;
• artefact spawn points;
• patrols;
• full loaded spawn file data.

Backend commands

The Tauri spawns-editor plugin exposes:

• open_spawn_file;
• import_spawn_file;
• export_spawn_file;
• save_spawn_file;
• close_spawn_file;
• get_spawn_file;
• get_spawn_file_header;
• get_spawn_file_graphs;
• get_spawn_file_alife_spawns;
• get_spawn_file_artefact_spawns;
• get_spawn_file_patrols;
• has_spawn_file.

Workflow

1. Use Open for a packed all.spawn file.
2. Inspect header, graph, ALife, artefact, and patrol chunks in the editor.
3. Use Unpack to export a packed spawn file into editable structured data.
4. Use Pack to rebuild a packed spawn file from an unpacked folder.

When an XRF project path is configured, default paths point at target/gamedata/spawns/all.spawn, target/spawns/unpacked, and target/spawns/repacked/repacked.spawn.

Safety note

Spawn files are binary game data. Keep a backup before saving or replacing a spawn file.

Translation Editor

The translation editor opens and reads XRF translation projects. The current app workflow is read-only inspection.

Screens

Backend commands

The Tauri translations-editor plugin exposes:

• open_translations_project;
• read_translations_project;
• get_translations_project;
• close_translations_project.

Both open/read paths use TranslationProject::read_project.

Workflow

1. Open a translation project folder or file.
2. Inspect loaded translation ids and language values in the project view.
3. Close and reopen after editing translation sources outside the app.

When an XRF project path is configured, the app can prefill src/engine/translations.

Output and limitations

The app keeps the parsed translation project in the Tauri plugin state and displays it in the project view. It does not currently expose a save action, build XML output, or run translation verification from the UI.

Use the app for inspection while comparing ids across languages. Use the CLI when you need to initialize files, build game XML, or validate translation structure.

CLI equivalent

Use xrf-tool initialize-translation, xrf-tool build-translation, and xrf-tool verify-translation for write, build, and verification workflows. In the engine repository, use npm run cli -- translations ... for XML-to-JSON conversion and project translation checks.

Tools CLI

The Tools CLI is the Rust xrf-tool binary from stalker-xrf-tools/bin/xrf-cli. Use it for repeatable asset inspection, conversion, packing, unpacking, formatting, and verification outside the engine repository wrapper.

xrf-tool <command> --help

The engine CLI wraps some of these commands through npm run cli -- ..., but xrf-tool is the lower-level interface used by both the engine scripts and the desktop tools.

Command groups

Logging

Most commands support command-specific --silent or --verbose flags. The binary also initializes Rust logging from RUST_LOG when the environment variable is present.

Read and write commands

Inspection commands such as info-ogf, info-omf, info-dds, info-spawn, and info-particles read input files and print parsed metadata. Conversion commands such as archive unpacking, spawn packing, particle packing, texture packing, and translation building write output paths.

Use explicit --path and --dest values when documenting or scripting a command. Defaults are useful for local manual work, but explicit paths make generated assets easier to reproduce.

Usage pattern

Use the command-specific page when working with a file format. Each page lists the required input, output behavior, and the commands that are safe to run as read-only inspection versus commands that write files.

When running from the engine repository, prefer the engine CLI wrapper if it already exposes the workflow. Use xrf-tool directly when you need a lower-level command that the engine wrapper does not register.

Archive CLI

Archive commands work with X-Ray .db database archives.

unpack-archive

unpack-archive opens an archive project and exports the contained files to a folder.

xrf-tool unpack-archive --path gamedata.db0 --dest unpacked

Options

• -p, --path <path>: path to a .db archive file. Required.
• -d, --dest <dest>: destination folder. Defaults to unpacked.
• --parallel <count>: number of parallel unpack workers. Defaults to 32.
• --dry: read and summarize the archive without writing files.
• -s, --silent: disable command logging.

Relative destination paths are resolved from the current working directory.

Output

Without --silent, the command prints:

• archive count;
• file count;
• compressed size;
• real unpacked size;
• unpack duration when files are written.

With --dry, the command still reads the archive metadata but does not write the extracted files. Use it to confirm that a database can be opened before spending time on a full unpack.

Examples

xrf-tool unpack-archive --path .\db\configs.db0 --dest .\unpacked\configs
xrf-tool unpack-archive --path .\db\textures.db0 --dest .\unpacked\textures --parallel 8
xrf-tool unpack-archive --path .\db\sounds.db0 --dry

Failure notes

The source path must point to a readable X-Ray database archive. If the destination already contains files, choose a new folder or clean it before running the command.

Gamedata CLI

Gamedata commands validate a project across one or more gamedata roots. Use them before packaging or when investigating missing textures, meshes, animations, scripts, configs, particles, or weather data.

verify-gamedata

xrf-tool verify-gamedata --root ./gamedata --configs ./gamedata/configs

Options

• -r, --root <paths...>: one or more gamedata roots. Required. Multiple paths are comma-separated.
• -i, --ignore <names...>: ignored files or folders. Multiple names are comma-separated.
• -c, --configs <path>: configs folder. Defaults to configs under the first root.
• --checks <checks...>: selected verification checks. If omitted, all checks run.
• --silent: disable logging.
• -v, --verbose: enable verbose logging.
• -s, --strict: enable strict mode.

If --ignore is omitted, the command ignores common repository and unpacked-source entries: .git, .idea, particles_unpacked, textures_unpacked, .gitignore, .gitattributes, README.md, and LICENSE.

Examples

xrf-tool verify-gamedata --root ./gamedata
xrf-tool verify-gamedata --root ./base,./override --configs ./override/configs
xrf-tool verify-gamedata --root ./gamedata --ignore .git,textures_unpacked --strict

Result

The command exits with a non-zero status when the project is invalid. In normal logging mode it prints each failure message before exiting.

LTX CLI

LTX commands format and verify .ltx and .ini config files. Use them for standalone config projects or when you need the lower-level tool behind the engine repository’s format ltx and verify ltx commands.

format-ltx

Formats one file or every LTX file under a folder.

xrf-tool format-ltx --path ./gamedata/configs
xrf-tool format-ltx --path ./gamedata/configs --check

Options:

• -p, --path <path>: file or folder to format. Required.
• -c, --check: check formatting without rewriting project files.
• -s, --silent: disable logging.
• -v, --verbose: enable verbose logging.

--check is implemented for folders. Single-file mode formats the file.

verify-ltx

Verifies an LTX project folder with scheme and strict-project options enabled.

xrf-tool verify-ltx --path ./gamedata/configs
xrf-tool verify-ltx --path ./gamedata/configs --strict

Options:

• -p, --path <path>: configs root folder. Required.
• --silent: disable logging.
• -v, --verbose: enable verbose logging.
• -s, --strict: enable strict checking.

Failure notes

verify-ltx expects a directory, not a single file. It fails when includes, inheritance, section fields, or scheme validation produce errors.

Scheme definitions are documented in Script config schemes.

OGF CLI

OGF commands inspect X-Ray model files.

info-ogf

xrf-tool info-ogf --path ./meshes/example.ogf

Options:

• -p, --path <path>: path to an .ogf file. Required.

Output

The command reads the model and prints available metadata:

• header version, model type, shader id, bounding box, and bounding sphere;
• texture and shader names;
• description chunk data when present;
• bones and parent names when present;
• motion references when present;
• child model texture and shader names for nested OGF data.

When to use it

Use info-ogf to confirm that a mesh file can be parsed, to inspect texture references, or to compare model metadata without opening a graphical tool.

Workflow

Run info-ogf before texture or model packaging when you need to confirm what a mesh references. The command is read-only: it does not rewrite chunks, normalize paths, or repair model data.

If a model fails to parse, first confirm the file is an OGF from the expected game version. Then compare the reported failure with neighboring meshes from the same source archive.

OMF CLI

OMF commands inspect X-Ray motion files.

info-omf

xrf-tool info-omf --path ./meshes/example.omf

Options:

• -p, --path <path>: path to an .omf file. Required.

Output

The command reads the motion file and prints:

• OMF version;
• motion count and motion names;
• total bone count;
• animation part names;
• bones assigned to each animation part.

When to use it

Use info-omf when checking whether a motion file is readable, whether expected motions are present, or how motion parts map to skeleton bones.

Workflow

Run info-omf when debugging missing animations or checking a packed resource set. The command is read-only and prints the parsed structure; it does not merge, split, or repair motion files.

If an expected animation is absent, check the source OMF first and then inspect the model or config that references the motion name.

Failure notes

The command expects a readable .omf file. It reports parsed metadata to stdout and leaves the source file unchanged. When comparing animation packages, run the command on both files and compare motion names before checking higher-level config references.

Particles CLI

Particle commands inspect, verify, pack, unpack, and round-trip particles.xr data.

Commands

Examples

xrf-tool info-particles --path ./particles.xr
xrf-tool unpack-particles --path ./particles.xr --dest ./particles_unpacked --force
xrf-tool pack-particles --path ./particles_unpacked --dest ./particles.xr --force
xrf-tool repack-particles --path ./particles.xr --dest ./particles.repacked.xr
xrf-tool re-unpack-particles --path ./particles_unpacked --dest ./particles_unpacked_roundtrip
xrf-tool verify-particles --path ./particles.xr
xrf-tool verify-particles --path ./particles_unpacked --unpacked

Shared options

Read commands require -p, --path <path>. Write commands that create output also use -d, --dest <dest>. unpack-particles and pack-particles support -f, --force to remove an existing destination before writing.

Failure notes

Packing fails if the output file already exists and --force is not supplied. Unpacking fails if the destination folder already exists and --force is not supplied.

Spawn CLI

Spawn commands inspect, verify, pack, unpack, and round-trip ALife .spawn files.

Commands

Examples

xrf-tool info-spawn --path ./all.spawn
xrf-tool unpack-spawn --path ./all.spawn --dest ./all_spawn --force
xrf-tool pack-spawn --path ./all_spawn --dest ./all.spawn --force
xrf-tool repack-spawn --path ./all.spawn --dest ./all.repacked.spawn
xrf-tool verify-spawn --path ./all.spawn

Options

pack-spawn:

• -p, --path <path>: unpacked spawn folder. Required.
• -d, --dest <dest>: output .spawn file. Defaults to unpacked.
• -f, --force: remove an existing output file first.

unpack-spawn:

• -p, --path <path>: source .spawn file. Required.
• -d, --dest <dest>: output folder. Defaults to unpacked.
• -f, --force: remove an existing output folder first.
• -s, --silent: disable logging.

info-spawn, verify-spawn, and repack-spawn require -p, --path <path>. repack-spawn also requires -d, --dest <dest>.

Failure notes

Packing and unpacking reject existing destinations unless --force is supplied.

Texture CLI

Texture commands inspect DDS files and pack or unpack icon-related assets.

Commands

DDS inspection

xrf-tool info-dds --path ./textures/ui/ui_icon_equipment.dds

The command prints file size, metadata size, pixel data size, dimensions, mipmap information, pitch or linear size when present, block size, bits per pixel, FourCC, and D3D/DXGI format when known.

Equipment icons

xrf-tool unpack-equipment-icons --system-ltx ./configs/system.ltx --source ./textures/ui/ui_icon_equipment.dds --output ./textures_unpacked/ui/ui_icon_equipment
xrf-tool pack-equipment-icons --system-ltx ./configs/system.ltx --source ./textures_unpacked/ui/ui_icon_equipment --output ./textures/ui/ui_icon_equipment.dds --strict

pack-equipment-icons also accepts --gamedata <path> for resource lookup, plus -v, --verbose and -s, --strict. unpack-equipment-icons supports -v, --verbose.

Texture descriptions

xrf-tool unpack-texture-description --description ./configs/ui/textures_descr/ui_actor.xml --base ./textures --output ./textures_unpacked --parallel
xrf-tool pack-texture-description --description ./configs/ui/textures_descr/ui_actor.xml --base ./textures_unpacked --output ./textures --strict

Description commands require --description and --base. If --output is omitted, output defaults to the base path. Both support -v, --verbose, -s, --strict, and --parallel.

The engine repository wraps the common equipment and description workflows through npm run cli -- icons ....

Translation CLI

Translation commands work with XRF JSON translation projects and generated gamedata string tables.

Commands

Initialize

xrf-tool initialize-translation --path ./translations

Options:

• -p, --path <path>: translation file or folder. Required.
• -s, --silent: disable logging.
• -v, --verbose: enable verbose logging.

Build

xrf-tool build-translation --path ./translations --output ./gamedata/configs/text --language ukr

Options:

• -p, --path <path>: translation file or folder. Required.
• -o, --output <path>: output folder. Required.
• -l, --language <language>: target language. Defaults to all.
• -s, --silent: disable logging.
• -v, --verbose: enable verbose logging.
• --sort: toggles sorting for dynamic translation files.

Verify

xrf-tool verify-translation --path ./translations --language ukr --strict

Options:

• -p, --path <path>: translation file or folder. Required.
• -l, --language <language>: target language. Defaults to all.
• --strict: exit with a non-zero status when translations are missing.
• -s, --silent: disable logging.
• -v, --verbose: enable verbose logging.

Notes

The engine repository’s npm run cli -- translations ... command provides a separate XML-to-JSON conversion workflow implemented in TypeScript. Use that wrapper when converting original X-Ray XML string tables into XRF JSON sources.

Useful Links

This page collects external tools and references commonly useful for X-Ray and S.T.A.L.K.E.R. modding.

X-Ray Engine and Modding

• OpenXRay: open-source X-Ray engine fork used by XRF.
• Anomaly modding book: community documentation for Anomaly-style modding concepts.
• STALKER Anomaly modded exes: useful reference for engine-side ideas and DLTX-related behavior.

Asset Tools

• AXRToolset: utilities for unpacking and working with gamedata.
• NVIDIA Texture Tools Exporter: DDS texture import/export tooling.
• xray-skls-file-browser: animation-related file browser and converter.

Development Tools

• Windows Terminal: terminal for running build, CLI, and validation commands on Windows.
• TypeScriptToLua: TypeScript-to-Lua compiler used by the XRF script build.
• Tauri: framework used by the XRF tools desktop app.

Game SDK

The X-Ray Game SDK is the editor/toolchain used for assets such as levels, spawns, particles, models, and other engine-native data.

XRF does not replace the SDK. The project adds source-controlled script/config/UI/translation workflows and helper tools around game data, while SDK-style tools remain useful for native X-Ray asset authoring.

When to Use the SDK

Use SDK tools when you need to work with data that is not represented well as text source:

• level editing;
• spawn and graph authoring;
• particle authoring;
• model or animation workflows;
• engine-native visual/editor data.

Use XRF source files and CLI tools when the change belongs to scripts, LTX/XML configs, UI XML, translations, or repeatable validation.

OpenXRay Reference

OpenXRay includes SDK-related work and documentation in its repository:

• OpenXRay repository
• OpenXRay game editor wiki

When SDK output is committed back to a project, keep generated binary output separate from hand-authored XRF sources.

Boundary with XRF

Treat SDK output as source only when the project intentionally owns that binary or editor-authored asset. Do not edit target/ output by hand and do not treat packed game data as the source of truth.

For script/config changes, prefer XRF text sources and validation commands. For native asset changes, use the SDK or format-specific XRF tools, then document how the generated asset should be reproduced.

Common handoff pattern

1. Author or inspect the native asset in the SDK or a format-specific tool.
2. Export the asset into the project-owned resource location.
3. Rebuild or repack with XRF CLI commands.
4. Verify the resulting game data in game, especially for spawn, level, model, animation, and particle changes.

Lua Debugger

Lua debugging for X-Ray scripts is limited by the engine runtime, luabind objects, and the fact that XRF source starts as TypeScript before being emitted as Lua.

For most day-to-day script work, start with:

• focused Jest tests around TypeScript source;
• XRF logs and game logs;
• generated Lua inspection under target/gamedata;
• engine-side debugging when the issue crosses into C++ or luabind behavior.

Breakpoints

Breakpoints in original TypeScript source are not equivalent to breakpoints in emitted Lua. If you attach a Lua debugger, set breakpoints against generated Lua paths and verify that the generated script names match what the engine loads.

Luabind classes, userdata, and C++ callbacks may not expose enough Lua-level state for convenient inspection.

Practical workflow

Start with the generated Lua file that corresponds to the TypeScript module. Confirm that the file exists under target/gamedata/scripts after a script build, then compare the emitted Lua names with the stack trace or log line from the engine.

Use Lua debugging for runtime-only questions such as callback order, engine object state, and values passed through luabind. Use Jest and TypeScript tests for parser, manager, scheme, and utility behavior that can be reproduced outside the engine.

When a Lua debugger cannot inspect userdata, add temporary logging around the TypeScript source and rebuild scripts. Keep those logs local or remove them before committing documentation or code changes.

Visual Studio Lua Debugger Research

The previous research link for Lua debugging is:

• LuaDkmDebugger
• LuaDkmDebugger pull request 26

Treat this as research material, not a documented XRF-supported debugging workflow.

Related Pages

• Debugging engine
• Logs
• Building scripts

AI and Logics

Use this page when an NPC is alive in game but its scheme, planner, relation, or animation state does not match what you expect.

Start with the in-game overlays when you need visual context. Switch to log dumps when you need the exact script state or GOAP action IDs.

Capturing an NPC

NPC capture is an engine debug feature. It is useful when you need to inspect the world from the NPC perspective.

1. Run the game with a mixed or debug engine build.
2. Hold left Alt.
3. Click the NPC.

The camera switches to the captured object. Release the capture before continuing normal gameplay testing.

AI Overlays

Enable stalker and monster overlays from the console:

ai_dbg_stalker on
ai_dbg_monster on

ai_dbg_stalker on renders debug details for stalker objects:

ai_dbg_monster on renders debug details for monster objects:

Use the matching off command to hide each overlay.

Planner and Scheme Logs

The XRF debug panel can print the selected object’s script state to the log. Open the main menu, press F11, switch to the object section, then choose one of the log buttons.

The object section can print:

• the active scheme, active section, logic section, smart terrain, enemy, portable store, and scheme-specific state;
• the engine action planner and the XRF state planner action IDs;
• the state manager target state, current animation state, animstate, look target, combat flag, and ALife flag;
• inventory contents, best weapon, best item, and relation data.

Planner show(...) output is only available when the engine exposes it. If the log says to run in mixed or debug mode, restart with a debug-capable engine build and repeat the dump.

Performance Stats

Use engine stats when you need frame-level AI cost, not a script-level dump:

rs_stats on
ai_stats on

The AI stats overlay shows rows in this shape:

[name][min_time][avg_time][max_time][call_rate][call_count][total_time]

For Lua call profiling, use the XRF debug panel general section. It can start or stop the ProfilingManager, print hooked call counts, print manually marked profiling portions, show Lua memory use, and force Lua garbage collection.

Run Lua profiling with -nojit when you need cleaner call stats. The profiler logs a warning when LuaJIT is enabled because JIT compilation can change the measured call pattern.

Useful Console Commands

Common AI debug toggles are listed in the game engine command reference:

AI debug console commands

Engine Debug (C++)

Use engine debugging when the problem crosses from TypeScript/Lua into xray runtime behavior: scheduler timing, rendering, physics, UI initialization, luabind bindings, or console command implementation.

For script-only behavior, start with logs and the XRF debug panel first. They are faster and do not require rebuilding the engine.

Set Up the Engine Project

OpenXRay has build guides for both supported development paths:

• OpenXRay Windows build guide
• OpenXRay Linux build guide

For local XRF development on Windows, the usual flow is:

1. Build or select a mixed/debug-capable engine.
2. Link XRF output and logs to the game folder with the XRF CLI link command.
3. Start the engine from Visual Studio when you need C++ breakpoints.
4. Start from the XRF CLI when you only need game logs and Lua output.

Debugging Lua from Visual Studio

Lua debugging is possible through the Visual Studio Lua debugger extension, but it is limited by the engine and by the compiled Lua output.

1. Install the LuaDkmDebugger Visual Studio extension.
2. Use an engine configuration that loads Lua debug symbols.
3. Run the game from Visual Studio.
4. Set breakpoints in the generated Lua files, not in TypeScript source.

XRF TypeScript is compiled to Lua by TypeScriptToLua. Visual Studio will see the generated Lua code that the engine executes.

What to Debug in C++

Use the engine source when you need to verify:

• console command behavior such as rs_stats, rs_fps, ai_stats, set_weather, or run_string;
• luabind signatures exposed through level, game, game_object, UI classes, planners, and packets;
• UI XML initialization behavior in CScriptXmlInit and CUI controls;
• engine-only debug overlays, stats, scheduler, physics, and renderer behavior.

Limitations

• TypeScript breakpoints are not available in the engine. Debug generated Lua or C++ instead.
• LuaDkmDebugger support is old and does not reliably inspect every luabind class or userdata value.
• Some debug console commands are compiled only into mixed/debug engine builds.
• Optimized script builds can strip Lua logger calls when built with --no-lua-logs.

Logs

Logs are the quickest way to inspect XRF runtime behavior. By default, forge.ltx enables debug mode, regular Lua logging, and the separate Lua log file.

Where Logs Go

The engine writes the main log into the game logs folder. XRF tooling can link that folder into the project as target/logs_link.

Common files are:

• openxray_<username>.log when a custom OpenXRay binary descriptor is present;
• xray_<username>.log for the base engine name;
• xrf_lua.log when separate Lua logging is enabled;
• module-specific files such as xrf_profiling.log when a logger is configured with a file target.

The exact prefix depends on the logger configuration and the engine variant.

Checking Logs

With a prebuilt engine:

1. Select the engine build you want to run.
2. Link the game folders with the XRF link command.
3. Start the game.
4. Inspect target/logs_link.

With Visual Studio:

1. Start the engine project from Visual Studio.
2. Check the Visual Studio Output window.
3. Check the same game log files if the message was written through the engine logger.

Printing Logs with the CLI

The XRF CLI can print the end of the active engine log:

npm run cli -- logs
npm run cli -- logs 100

The default count is 15 lines. Values are capped at 200 lines. The CLI looks for the linked logs folder and then chooses openxray_<username>.log or xray_<username>.log depending on the detected engine.

Writing Lua Logs

Use LuaLogger from runtime code:

const logger: LuaLogger = new LuaLogger($filename);

logger.info("Spawned object: %s", object.name());
logger.table(state);
logger.pushSeparator();
logger.printStack();

LuaLogger formats messages with the current engine time, file prefix, level, and formatted text. It writes to the engine log unless a file-only logger is configured. When separate_lua_log_enabled is true, it also writes to the shared Lua log file.

Use a file logger when the stream is noisy or belongs to a specific subsystem:

const logger: LuaLogger = new LuaLogger($filename, {
  mode: ELuaLoggerMode.DUAL,
  file: "profiling",
});

DUAL writes both to the named file and to the normal engine log.

Flushing

Use the engine flush console command after generating important logs:

flush

The profiling manager calls flush after printing profiling reports so the latest stats are persisted before you leave the session.

Build-Time Logging Flag

For performance or release-like builds, script compilation can strip Lua logger calls:

npm run cli -- build -i scripts --no-lua-logs

Do not use that flag when you are investigating runtime behavior.

Debugging UI Forms

XRF UI forms are authored as TSX/XML sources and loaded at runtime through xray CUI classes. Debug UI problems by checking both sides: the generated form structure and the runtime code that initializes named nodes.

Source and Runtime Files

Most UI work touches one of these areas:

• form sources in src/engine/forms;
• reusable form components in src/engine/forms/components;
• runtime window classes in src/engine/core/ui;
• XML render/build helpers in cli/utils/xml;
• generated output under target, which should be regenerated instead of edited by hand.

When a runtime class calls xml.InitStatic, xml.Init3tButton, xml.InitScrollView, or another CScriptXmlInit method, the named XML node must exist in the form source.

Check the Form Path

Runtime code usually resolves a form by path:

const base: TPath = "menu\\debug\\DebugDialog.component";
this.xml = resolveXmlFile(base);

If a form does not appear, verify:

• the base path matches the TSX/XML source path;
• the build generated the matching XML file;
• every node name used by the runtime class exists in the form;
• both 4:3 and 16:9 variants were updated when the form has paired variants.

Use Engine UI Debugging

OpenXRay includes UI inspection tools for layout and control rectangles. They are most useful for positioning issues, wrong sizes, and overlapping controls.

The show_wnd_rect_all console command is available in XRF command constants and can help identify active UI control bounds in debug builds:

show_wnd_rect_all 1
show_wnd_rect_all 0

Some UI debug tools depend on the engine build. If the command has no effect, run with a mixed/debug-capable engine.

Common Failure Points

• A runtime Init... call references a missing XML node.
• A section exists in TSX but is not registered by the runtime dialog.
• A button is visible but not registered with Register and AddCallback.
• Text or controls fit in one aspect ratio but not in the paired 16:9 form.
• The generated XML in target is stale after changing the TSX source.

References

• OpenXRay UI debugger article

Circular References

Circular references usually show up in XRF as initialization problems: a manager asks for another manager while modules are still loading, or a debug dump walks a graph of tables that point back to each other.

Manager Resolution

Use getManager(ManagerClass) for normal manager access. It initializes the manager on first use and stores it in the runtime registry.

Use getManagerByName("ManagerName") only when importing the manager class would create a circular module dependency. It returns an already initialized manager by name and cannot create one by itself.

const surgeManager: SurgeManager = getManagerByName("SurgeManager") as SurgeManager;

If the result can be missing during startup, handle null instead of assuming the manager exists.

Resolve Logging

forge.ltx has a debug flag for logger creation:

[debug]
resolve_log_enabled = true

When enabled, each LuaLogger prints a Declared logger message when it is created. This is noisy, but useful when you need to see which modules are loaded before a crash or circular dependency failure.

Turn it back off after the investigation:

[debug]
resolve_log_enabled = false

Dumping Circular Data

The XRF JSON helper used by debug dumps is circular-reference aware. When it sees a table it has already visited, it writes:

"<circular_reference>"

When the dump exceeds the configured depth limit, it writes:

"<depth_limit>"

Use the debug panel general section to dump Lua state to _appdata_\\dumps\\lua_data.json, then search for these markers to find strongly connected runtime state.

Practical Checks

• Move type-only imports to import type when the dependency is only needed by TypeScript.
• Prefer event callbacks or weak manager lookup when two managers need to observe each other.
• Avoid top-level runtime work in modules that are imported by many systems.
• Keep debug dumps bounded; do not serialize raw engine userdata.

Generating Externals Docs

External functions are script functions that configs can call from condlists, effects, dialogs, and other game data. The XRF CLI can scan declaration sources and generate an HTML reference for them.

Run the Generator

From the XRF engine repository:

npm run cli -- parse externals

The command scans declaration files under:

src/engine/scripts/declarations

It skips *.test.ts files and index.ts files, groups declarations by parent folder, and writes:

target/parsed/externals.html

Open the generated file in a browser when you need to inspect the currently exported external names.

What Gets Documented

The generator reads TypeScript declaration sources, extracts external function metadata, renders the result as HTML, and writes the rendered file with the project XML renderer.

Keep extern declarations close to the runtime implementation and tests. The generated page is only as useful as the names, parameters, and comments present in the declaration files.

Updating JSDoc

When adding or changing an external:

1. Update the declaration function and its JSDoc.
2. Keep the exported external name exactly aligned with the function registered for game configs.
3. Add or update the focused tests for the declaration.
4. Regenerate the externals HTML with npm run cli -- parse externals.

Prefer short comments that explain what config authors need: required arguments, optional arguments, side effects, and what happens when the target object or parameter is missing.

Running Custom Scripts

The engine exposes two development console commands for running Lua from the game console: run_script and run_string. They are useful for short investigations on a throwaway save.

These commands are engine debug tools. Availability depends on the engine build.

Run a Script File

Use run_script to run a .script file from the game scripts directory:

run_script my_debug_script

The engine rescans the scripts path before adding the script to the level script processor. Use this for repeatable debug snippets that are too large for a single console line.

Run One Lua Expression

Use run_string for a single Lua command:

run_string level.set_weather("default_clear", true)
run_string db.actor:set_actor_position(vector():set(0, 0, 0))

The engine preserves argument casing for run_string, sends the string to the level script processor when one exists, and otherwise loads the buffer directly as @console_command.

XRF Helper Examples

Many XRF declarations are available through registered Lua modules after scripts are loaded. For example, debug notes in spawn configs use command shapes like:

run_string xr_effects.clear_smart_terrain(nil,nil,{"sim_smart_1"})
run_string alife():object(56):set_squad_position(patrol("tst"):point(0))

Prefer existing effects and helpers over hand-mutating unrelated manager state.

Safety

• Test on a disposable save.
• Keep commands small enough to read in logs.
• Use logs or the debug panel to verify the effect after running the command.
• Restart the session if you mutate state that the current manager lifecycle would normally own.

Stats

Use engine stats for frame/render timing and script stats for Lua-side call patterns. They answer different questions, so enable the smallest view that matches the problem.

Rendering and Frame Stats

Use these console commands while the game is running:

rs_stats on
rs_fps on
rs_fps_graph on

rs_stats enables the engine statistics overlay. rs_fps shows the FPS counter. rs_fps_graph shows the FPS graph. Use off to disable each toggle.

These commands are implemented by the engine, not by XRF scripts. Availability can depend on the engine build and renderer configuration.

AI Stats

For AI scheduler and planner timing:

ai_stats on

The AI stats overlay is useful when you need to see whether a cost is coming from engine AI updates rather than an XRF manager or scheme.

Lua Profiling

The XRF ProfilingManager measures Lua call counts and manually marked profiling portions.

Open the XRF debug panel, switch to general, then use:

• start/stop profiling to attach or clear the Lua debug hook;
• log profiling stats to print hooked call counts;
• log portions to print manually captured ProfilingPortion measurements;
• refresh or collect memory to inspect Lua memory use.

For cleaner Lua hook stats, start the game with -nojit. LuaJIT can inline or alter execution in ways that make hook counts less representative.

Manual Profiling Portions

Use ProfilingPortion when you need to measure a specific code block:

const portion: ProfilingPortion = ProfilingPortion.mark("my_operation");

// Code to measure.

portion.commit();

The debug panel prints count, total duration, average duration, min, and max for captured portions.

Weather

XRF weather is managed by WeatherManager. It reads level weather settings, dynamic weather graphs, AtmosFear-style configuration, and weather FX state, then updates weather on actor spawn and on hourly game-time changes.

Runtime Weather Flow

On actor network spawn, the manager:

1. reads the current level’s weathers setting from game.ltx;
2. parses it as a condlist;
3. initializes the current weather period and graph state;
4. applies the first weather immediately.

During actor updates, it:

• advances graph state when the game hour changes;
• switches between good and bad weather periods;
• marks transition and pre-blowout weather states;
• updates depth-of-field settings for AtmosFear weather;
• resumes weather FX from saved state when an FX is active.

Use the debug panel general section to dump Lua state when you need to inspect the live WeatherManager fields. The dump is written to _appdata_\\dumps\\lua_data.json.

Changing Weather from Scripts

Script effects can force weather through xr_effects.set_weather, which calls level.set_weather:

on_info = %+some_info =set_weather(default_clear:true)%

The first argument is the weather section. The optional second argument controls whether the change is forced.

From Lua/TypeScript runtime code, the underlying engine call is:

level.set_weather(weatherName, isForced);

For weather effects, the engine exposes:

level.set_weather_fx("fx_surge_day_3");
level.start_weather_fx_from_time("fx_surge_day_3", time);

Weather Console Settings

WeatherManager applies commands from the weather_console_settings section in environment\\dynamic_weather_graphs.ltx during initialization. Use that section for console settings that must be applied with the dynamic weather system.

Debugging Weather Editor Issues

OpenXRay includes a weather editor project and editor documentation. Use it for visual tuning of weather sections and effects, then confirm the resulting section names and graph entries in XRF configs.

If a weather change does not appear:

• verify the level weathers field resolves to the expected section or condlist branch;
• verify the weather graph exists in dynamic_weather_graphs.ltx;
• check whether a weather FX is currently playing;
• check whether the level is treated as underground;
• dump Lua state and inspect currentWeatherSection, nextWeatherSection, weatherFx, and weatherState.

References

• OpenXRay weather editor article

XRF Debug Panel

The XRF debug panel is an in-game CUI dialog for development-only actions. It is available when forge.ltx has debug.enabled = true, which is the default project config.

Open the main menu and press F11. The panel hides the main menu while it is open. Press Esc or the cancel button to return to the main menu.

General

The general section shows Lua version, LuaJIT state, command-line arguments, and Lua memory usage.

It can also:

• refresh memory usage;
• force Lua garbage collection;
• start or stop Lua profiling;
• print profiling hook stats;
• print manual profiling portion stats;
• toggle simulation debug map overlays;
• dump merged system.ini to _appdata_\\dumps\\system.ltx;
• dump Lua manager state to _appdata_\\dumps\\lua_data.json.

Lua data dumping emits DUMP_LUA_DATA, so managers that registered a debug dump callback add their own state to the JSON payload.

Commands

The commands section exposes checkbox shortcuts for known console toggles.

Boolean commands are written as:

<command> on
<command> off

Numeric commands are written as:

<command> 1
<command> 0

The list includes AI debug toggles, HUD toggles, g_god, g_unlimitedammo, g_autopickup, and wpn_aim_toggle.

Object

The object section works with either the current target object or the nearest game object, depending on the section checkbox.

It can log:

• scheme state and active section;
• action planner and state planner details;
• state manager details;
• inventory contents;
• relation data.

It can also set the actor relation to the object, kill the object, or set the object wounded. Use these actions on a throwaway save.

Items

The items section spawns inventory items for the actor. Categories are built from game config sections:

• ammo;
• artefacts;
• consumables;
• detectors;
• helmets;
• outfits;
• weapons.

Ammo spawns as a stack of 30; other item categories spawn one item.

Spawn

The spawn section spawns creatures and simulation groups.

• stalkers_list spawns the selected stalker section near the actor.
• simulation_group_list spawns the selected squad section into the nearest smart terrain.

If there is no active game or no suitable smart terrain, the action is skipped and logged.

Teleport

The teleport section lists smart terrains. Selecting one moves the actor to that smart terrain.

If the target game vertex belongs to the current level, the panel sets the actor position directly. If it belongs to a different level, it calls game.jump_to_level. Double-click teleport also closes the main menu after moving the actor.

Registry and Tasks

The registry section lists ALife objects from the simulator, can filter online objects, and can print a registry summary with manager, scheme, object, smart terrain, event handler, and other collection counts.

The task section lists task config sections, can filter active tasks, and can give the selected task through TaskManager.

Treasures

The treasures section shows total, given, and found treasure counts. It can:

• give all treasure coordinates;
• give random treasure coordinates;
• give one selected treasure coordinate;
• teleport to the selected treasure restrictor when it exists.

The section also shows debug details for the selected treasure, including given/checked state, refresh flags, remaining items, and treasure type.

Current Shell Sections

player, position, and sound are present as panel sections, but their current TypeScript runtime classes only parse their form XML and do not bind interactive actions.

Game engine

XRF runs on top of the X-Ray engine used by S.T.A.L.K.E.R. Call of Pripyat style games. The engine owns the executable, renderer, file system, console, configuration loading, Lua VM, luabind exports, server objects, client objects, ALife simulation, and the low-level update loop.

XRF replaces the game script layer. TypeScript sources are compiled to Lua scripts, then loaded by the engine through the same script entry points that vanilla game logic uses.

What the engine owns

The engine starts from the executable. During startup it initializes core services, resolves the file system layout, loads configuration files, creates the console, initializes the Lua script engine, and opens engine bindings for Lua.

At runtime it also owns:

• server-side ALife objects and the object factory;
• client-side game objects and their object_binder instances;
• save and load packets;
• console command execution;
• render, sound, input, and UI infrastructure;
• frame updates and scheduled object processing.

The source references for these behaviors are the local xray-16 engine tree and the XRF X-Ray 16 SDK declarations.

What XRF adds

XRF provides the Lua scripts that the engine calls into:

• _g.script preloads register, bind, and start, then registers global script externals.
• register.script registers game classes, UI classes, server object classes, and callback functions.
• start.script initializes managers, schemes, simulation helpers, extensions, and emits the XRF GAME_STARTED event.
• bind.script maps engine object sections and script class names to XRF binder classes.

After that point, most game behavior goes through XRF managers, schemes, binders, and event callbacks.

Where to go next

• Use Command line arguments when changing engine startup behavior.
• Use Console commands for commands available after the console is initialized.
• Use Execution flow to understand the order from executable startup to active gameplay.
• Use Lifecycle when editing binders, managers, save/load code, or online/offline logic.
• Use Luabind when a TypeScript class needs to be visible to the Lua engine runtime.

Command line arguments

Command line arguments are read by the engine before scripts are loaded. Use them for engine startup choices such as filesystem layout, renderer, logs, game mode, Lua JIT, and initial level loading.

npm run cli -- start_game starts the configured game executable. It does not inject arbitrary engine arguments for you. To pass arguments, run the executable directly, configure a launcher shortcut, or extend the local start command.

Common flags

Renderer flags such as -r1, -r2, -r2a, -r2.5, -r3, -r4, and -rgl are engine-build dependent. Verify the selected executable before documenting a renderer as supported for a pack.

Game mode flags

OpenXRay-style builds can select a compatibility mode from the command line:

• -cop for Call of Pripyat mode;
• -cs for Clear Sky mode;
• -shoc or -soc for Shadow of Chernobyl mode;
• -unlock_game_mode to allow explicit game mode selection.

If no mode is selected, the engine can fall back to openxray.ltx compatibility settings.

Examples

Start with an explicit filesystem config and user config:

xrEngine.exe -fsltx fsgame.ltx -ltx user.ltx -nointro

Start a new local game through the engine console startup command:

xrEngine.exe -start "server(all/single/alife/new) client(localhost)"

Load a save after initialization:

xrEngine.exe -load quicksave

Quote values that contain spaces. Treat command line support as executable-specific: forks can add, remove, or rename flags.

Console commands

Console commands are available after the engine console is initialized. They can be typed in the in-game console, executed from config files, or triggered from scripts when the engine exposes command execution.

Most boolean commands use on/off. Some use 0/1, numeric ranges, enum values, or custom command strings.

Basic commands

Script commands

run_script <name> reloads script paths and executes a script file through the engine script processor.

run_string <lua> executes a Lua string. In the inspected engine, the command preserves the original casing of the string payload instead of lowercasing it with the command name.

Use these commands for focused debugging. For repeatable development workflows, prefer tracked scripts and XRF externals instead of long console strings.

AI debug commands

The inspected OpenXRay-style engine registers these AI and ALife debugging commands:

• ai_debug
• ai_dbg_brain
• ai_dbg_motion
• ai_dbg_frustum
• ai_dbg_funcs
• ai_dbg_alife
• ai_dbg_goap
• ai_dbg_goap_script
• ai_dbg_goap_object
• ai_dbg_cover
• ai_dbg_anim
• ai_dbg_vision
• ai_dbg_monster
• ai_dbg_stalker
• ai_stats
• ai_dbg_destroy
• ai_dbg_serialize
• ai_dbg_dialogs
• ai_dbg_infoportion
• ai_dbg_node
• ai_dbg_sight
• ai_dbg_inactive_time
• ai_draw_game_graph
• ai_draw_game_graph_stalkers
• ai_draw_visibility_rays
• ai_animation_stats

Render, UI, sound, and gameplay commands

Useful command families include:

• render toggles: rs_stats, rs_fps, rs_fps_graph, rs_vis_distance, rs_cam_pos, rs_wireframe;
• video settings: vid_mode, vid_window_mode, vid_restart, renderer;
• sound settings: snd_volume_eff, snd_volume_music, snd_restart, snd_device;
• HUD settings: hud_draw, hud_info, hud_weapon, hud_crosshair, hud_crosshair_dist, hud_fov;
• gameplay settings: g_game_difficulty, g_language, g_sleep_time, wpn_aim_toggle;
• Lua debugging: lua_debug, lua_dump_depth;
• ALife tuning: al_time_factor, al_switch_distance, al_process_time, al_objects_per_update, al_switch_factor.

Some commands are available only in debug builds or specific forks. Check the selected engine source before relying on a command in documentation or tooling.

XRF debug panel

XRF keeps a typed subset of console commands for the debug UI. If a command should be exposed from the panel, add it to the engine constants first and verify the selected engine accepts the same name and value type.

Execution flow

This page describes the normal flow from executable startup to active XRF gameplay. It is intentionally high-level: forks can move engine internals around, but XRF depends on the same script entry points.

1. Executable startup

The engine initializes core services, resolves filesystem paths, loads configuration files, initializes logging, creates the console, and applies startup command line arguments.

Important early choices include:

• filesystem config from -fsltx;
• console/user config from -ltx;
• compatibility mode from -cop, -cs, -shoc, or -soc;
• Lua JIT state from -nojit;
• post-init start or load commands from -start and -load.

2. Lua script engine initialization

The script engine initializes Lua, opens luabind exports, opens the standard Lua libraries used by the selected build, adds game script paths to package.path, and loads script modules.

In XRF builds, _g.script is the root script entry point. It preloads:

• register;
• bind;
• start.

It also registers global externals for conditions, effects, dialogs, tasks, and callbacks.

3. Class and callback registration

The engine calls into register.script to register script-visible game classes and resolve class identifiers.

XRF registers:

• server object classes such as actors, stalkers, monsters, smart terrains, squads, items, weapons, anomalies, and physics objects;
• UI classes such as the main menu;
• engine callback functions exposed through global script paths.

The class registration step is what lets spawned engine objects construct the matching TypeScript-to-Lua classes.

4. XRF startup callback

The engine then calls start.callback(isNewGame).

XRF uses this callback to:

• refresh class identifiers;
• register the ALife simulator and ranks;
• unlock system ini overriding;
• initialize managers;
• register scheme implementations;
• register extensions;
• emit GAME_STARTED.

Managers and schemes are available after this step.

5. Object creation and binding

The engine reads spawn data and creates server objects. When an object goes online on the client side, the engine asks bind.script for the binder class.

XRF binds engine objects to classes such as:

• ActorBinder;
• StalkerBinder;
• MonsterBinder;
• SmartTerrainBinder;
• RestrictorBinder;
• AnomalyZoneBinder;
• WeaponBinder;
• PhysicObjectBinder.

The binder receives lifecycle calls from the engine and becomes the bridge between low-level object state and XRF managers, schemes, and events.

6. Active gameplay loop

During gameplay, online binders receive updates, engine callbacks emit XRF events, managers react to those events, and save/load packets serialize state. Offline ALife objects continue to exist on the server side even when no client-side game object is active.

Known xray engine forks

XRF targets the Call of Pripyat style X-Ray/OpenXRay API used by the local engine and type declarations. Forks are useful reference points, but they are not a compatibility guarantee. Verify bindings, console commands, save/load behavior, and script callbacks against the exact executable you ship.

Common references

Compatibility checklist

Before moving XRF scripts to a fork, check:

• luabind class names and exported functions;
• object_binder method behavior;
• game class identifiers and section-to-class mappings;
• console command names and accepted value types;
• command line flags used by your launcher;
• save/load packet order and marker expectations;
• availability of Lua libraries such as jit, ffi, marshal, and lfs;
• callback names and callback argument order;
• ALife online/offline switching behavior.

When a fork disagrees with vanilla resources and OpenXRay source, document the fork behavior as fork-specific instead of treating it as the default.

Lifecycle

The engine lifecycle is split between global startup, server-side ALife objects, client-side game objects, XRF binders, and XRF managers. Most script bugs come from mixing those scopes.

Global startup

Global startup happens once per game process and again at specific script reload points depending on the engine. In XRF, the important global scripts are:

• _g.script, which preloads core entry points and registers externals;
• register.script, which registers classes and callback globals;
• start.script, which initializes managers, schemes, extensions, and emits GAME_STARTED;
• bind.script, which returns binder classes for online objects.

Do not put per-save or per-object state in module globals unless it is intentionally reset during the relevant lifecycle step.

Binder lifecycle

Client-side game objects use engine object_binder lifecycle methods. XRF binders override the methods they need:

Actor, stalker, monster, restrictor, smart terrain, physic object, and item binders all follow this pattern.

Manager lifecycle

Managers extend AbstractManager. A manager can implement:

• initialize() to register callbacks or allocate state;
• destroy() to unregister callbacks and mark state as disposed;
• update(delta) when it is driven by an update event;
• save(packet) and load(reader) when it owns serialized state.

Managers should subscribe through EventsManager rather than being called from unrelated binders. This keeps object lifecycle code small and makes save/load ownership clearer.

Event lifecycle

EventsManager owns typed event subscriptions. Binders and game objects emit events such as:

• ACTOR_GO_ONLINE, ACTOR_GO_OFFLINE, ACTOR_REINIT;
• ACTOR_UPDATE, ACTOR_UPDATE_100, ACTOR_UPDATE_500, ACTOR_UPDATE_1000, ACTOR_UPDATE_5000, ACTOR_UPDATE_10000;
• STALKER_DEATH, MONSTER_DEATH, HIT;
• GAME_SAVE, GAME_SAVED, GAME_LOAD, GAME_LOADED;
• BEFORE_LEVEL_CHANGE and GAME_STARTED.

Actor update drives the global timer manager tick and the throttled actor update events. Prefer those throttled events for recurring manager work that does not need every frame.

Save and load lifecycle

Save/load code must preserve packet order. XRF commonly wraps sections with save/load markers, calls the superclass method, then writes or reads owned state.

If a manager or binder adds state to a save packet, update the corresponding load code in the same change. Never insert a new read without matching old saves or version handling.

AI and logics

XRF AI logic is built on the engine GOAP planners, engine callbacks, XRF schemes, and the XRF stalker state manager. The engine still owns navigation, combat primitives, visibility, danger evaluation, animation execution, and the base planner runtime. XRF adds script-side actions, evaluators, scheme state, and event routing.

Use this page to understand the structure. Use the debugging AI page when you need runtime overlays, planner dumps, or log output.

Motivation planner

Each stalker has an engine motivation action planner. XRF modifies that planner when the stalker binder is reinitialized. The setup adds script evaluators and actions that coordinate engine behavior with XRF-controlled animation and logic state.

The motivation planner includes engine action ids for broad behaviors such as ALife, combat, anomaly, danger, gathering items, smart terrain tasks, and death. XRF adds custom action ids for script activities such as animpoint, walker, remark, sleeper, companion, smart cover, wounded, abuse, and state-to-idle transitions.

State planner

StalkerStateManager owns a separate Lua-side action planner for stalker state control. It manages the target state and drives sub-planners for:

• weapon state;
• movement;
• look direction;
• mental state;
• body state;
• animstate;
• animation;
• smart cover;
• locked states.

The state planner goal is to reach its END state after the required weapon, movement, mental, body, direction, animstate, animation, and smart cover evaluators are satisfied.

Evaluators

Evaluators answer yes/no questions for the planner. Examples include whether the stalker is already standing, walking, in danger mental state, using a target weapon state, playing an animation, locked by animation, or inside a smart cover.

Evaluator ids are stable planner contracts. Changing ids can break planner graphs and debug output, even if TypeScript still compiles.

Actions

Actions change world state. XRF actions can strap or unstrap weapons, set movement, turn the stalker, switch mental and body state, start or stop animations, and enter or leave smart cover.

Actions and evaluators used by engine planners must be luabind-visible classes. Keep @LuabindClass() on planner classes that the engine action planner constructs or stores.

Schemes

Schemes are the script logic layer loaded from LTX logic sections. A scheme activates state for a specific object and section, subscribes handlers, and reacts to scheme events such as switching online/offline, death, hit, use, or extrapolation.

The stalker binder wires schemes into object lifecycle:

• creates StalkerStateManager during reinit;
• sets up the state planner and motivation planner;
• initializes object logic on spawn;
• updates the state manager while the object is online;
• emits scheme events when the object switches offline, dies, is hit, or is used.

Keep scheme state in the object registry and clean it through the scheme lifecycle. Avoid storing per-object scheme state only in module globals.

Luabind

Luabind is the bridge between C++ engine code and Lua scripts. The engine exports C++ classes, functions, enums, and helpers into Lua, then game scripts create Lua-side classes that inherit from those bindings.

XRF TypeScript compiles to that Lua layer. A class that must be constructed or called by the engine needs to follow the same luabind-visible shape after compilation.

@LuabindClass()

Use @LuabindClass() on TypeScript classes that must be visible as Lua classes. Common examples include:

• binders that extend object_binder;
• action and evaluator classes used by GOAP planners;
• UI classes that extend engine CUI classes;
• server object classes registered through the factory.

The decorator preserves the class metadata expected by the TypeScript-to-Lua and luabind runtime path.

Class names

Many registrations use the class __name field. XRF passes those names to engine registration code for game classes, UI classes, and binder construction.

Changing a class name can therefore change runtime behavior even when TypeScript imports still compile. Treat class renames as compatibility changes.

Externals are separate from luabind

XRF also has an extern(...) helper. It writes values into _G or nested global tables so the engine and configs can find script callbacks such as conditions, effects, task functions, dialog functions, and startup callbacks.

That is not the same as binding a C++ class. Use luabind classes when the engine constructs or calls class instances. Use externals when a named global function or table entry must exist in Lua.

class, property, and super

OpenXRay luabind exposes helper globals such as class, property, and super. They come from the luabind runtime, not from XRF.

Modern XRF code usually does not call these helpers directly. TypeScript classes and @LuabindClass() generate the Lua shape that the engine expects.

Verification

Use the XRF X-Ray 16 SDK to check TypeScript-visible API shape. For ambiguous behavior, check the engine binding code in the selected xray-16 fork, because some binding setters and object methods have engine-specific semantics.

Lua extensions

The engine Lua environment is not plain standalone Lua. OpenXRay-style builds initialize LuaJIT, luabind, engine exports, standard libraries, and a few engine-specific libraries before game scripts run.

The inspected script engine opens the usual Lua libraries such as base, package, table, io, os, math, string, bit, and ffi. Debug builds can also expose the Lua debug library. LuaJIT is opened unless the executable starts with -nojit.

Runtime availability

XRF can have TypeScript declarations for a library even when a specific engine executable does not load that library. Always separate:

• compile-time declarations in src/typedefs;
• runtime modules actually opened by the engine;
• modules shipped in the selected gamedata or Lua environment.

This matters for marshal and lfs: XRF has typings for them, but availability depends on the chosen engine/runtime package.

Script path

The engine appends gamedata script paths to package.path, allowing scripts to be required from the game script directory. Keep runtime require(...) names aligned with the emitted Lua script layout.

Practical checks

When adding a dependency on a Lua module:

1. check the TypeScript declaration under src/typedefs;
2. check whether the target executable opens or ships the module;
3. run the game with the same executable that will ship to users;
4. keep fallback behavior for optional modules.

For engine-bound code, prefer X-Ray APIs and XRF helpers over standalone Lua assumptions. The engine can change module availability, package paths, and debug library access depending on build flags.

Custom Lua

OpenXRay-style builds use a custom LuaJIT runtime rather than a stock standalone Lua executable. The engine initializes Lua, opens luabind, registers engine exports, configures script paths, and then loads game scripts.

This matters for XRF code because TypeScriptToLua output runs inside the game script engine, not inside a generic Lua CLI. Available globals, module search paths, JIT behavior, and engine bindings come from the selected executable.

Libraries opened by the engine

The inspected script engine opens standard Lua libraries and LuaJIT-related libraries used by game scripts:

• package, table, io, os, math, and string;
• bit and ffi;
• LuaJIT support unless -nojit is passed;
• debug in non-master/debug-capable builds;
• engine-specific helpers such as xrluafix;
• Tracy Lua integration when compiled into the engine.

Do not assume every fork opens the same set. Check the selected executable if a script depends on a non-standard module.

Useful flags

-nojit disables LuaJIT JIT compilation. This can make some debugging sessions easier, but it also changes profiler behavior.

-dump_bindings asks the script engine to dump binding information. Use it when comparing what the engine exported with what the TypeScript declarations say exists.

Notes for XRF scripts

• Treat src/typedefs and the XRF X-Ray 16 SDK as declarations for what TypeScript can see, then verify ambiguous behavior against the engine build.
• Do not assume optional Lua modules such as LFS or marshal are loaded unless the runtime package opens or provides them.
• Use engine APIs for game objects, packets, configs, and path resolution. Standalone Lua behavior is a weak reference when engine bindings are involved.

Marshal

marshal is a Lua serialization library. XRF has TypeScript declarations for the functions used by the runtime:

• marshal.encode(value) converts a Lua value to an encoded representation;
• marshal.decode(value) reads an encoded representation back;
• marshal.clone(value) creates a cloned value through marshal semantics.

The declarations reference the upstream Lua marshal project: https://github.com/richardhundt/lua-marshal.

Availability

The inspected engine script initialization does not open marshal as one of the default Lua libraries. Treat it as an optional runtime dependency unless the selected executable or gamedata package explicitly provides it.

Guard code that depends on marshal, or keep usage in paths where the runtime package is known.

When to use it

Use marshal only when the runtime really needs Lua-level serialization or cloning. For game save data, prefer the engine save packet APIs and XRF save/load helpers so the data remains compatible with the engine lifecycle.

Good candidates are short-lived Lua tables in tooling, debug-only data capture, or controlled runtime features where the package is bundled with the executable. Avoid using it as an implicit dependency for core gameplay scripts.

Validation notes

• Check that require("marshal") succeeds in the selected executable before using these declarations.
• Keep encoded data versioned if it can persist outside the current process.
• Prefer explicit table copies when the shape is small and known; marshal.clone is useful only when marshal semantics are the intended behavior.

LFS

LFS is LuaFileSystem. It provides filesystem operations such as directory iteration, attribute inspection, directory creation, links, locks, and current-directory changes.

XRF has TypeScript declarations for common LFS functions:

• lfs.attributes(path);
• lfs.dir(path);
• lfs.currentdir();
• lfs.chdir(path);
• lfs.mkdir(path);
• lfs.rmdir(path);
• lfs.link(oldPath, newPath);
• lfs.touch(path, atime, mtime);
• lfs.lock(file, mode, start, length);
• lfs.unlock(file, start, length);
• lfs.symlinkattributes(path);
• lfs.setmode(file, mode);
• lfs.lock_dir(path, seconds).

The upstream library documentation is available at https://lunarmodules.github.io/luafilesystem/.

Availability

The inspected engine script initialization does not open LFS as one of the default Lua libraries. Treat it as optional unless your selected runtime package ships it.

For game paths, prefer engine filesystem helpers and configured path aliases. Use LFS for plain filesystem work only when the runtime dependency is verified.

Practical use

Use LFS for tools or controlled runtime packages where filesystem access is part of the environment contract. Avoid it inside portable gameplay code unless the target executable is known to expose the module.

For game data lookup, prefer engine path aliases and file-system helpers because they follow mounted game paths and mod layout rules. LFS works on process-visible filesystem paths; it does not know about engine virtual paths by itself.

Verification checklist

• Check that require("lfs") succeeds in the exact runtime package you ship.
• Check path separators and working directory assumptions on the target platform.
• Keep save-game and game-state persistence on engine packet APIs instead of plain files unless the feature explicitly owns external files.

Online and offline

X-Ray keeps two related views of many objects:

• a server-side ALife object, which can exist while the object is offline;
• a client-side game object, which exists when the object is online and active on the current level.

Online/offline state is not the same as alive/dead. An offline object can still exist in simulation. An online object has a live game_object, a binder, callbacks, and client-side updates.

Offline objects

Offline objects live in the ALife simulation. They are represented by server objects and can be queried through simulator APIs. Smart terrains, squads, NPCs, monsters, items, and level changers all have server-side behavior in different ways.

Use server objects for simulation state, spawn data, story ids, smart terrain membership, and logic that must survive outside the active client bubble.

Online objects

When an object switches online, the engine creates or activates a client-side game_object and attaches an object_binder. XRF uses binders to register object state, set callbacks, emit events, and update active schemes.

Use online objects for:

• direct game object methods;
• visible object state;
• callbacks such as hit, death, use, inventory, or task updates;
• per-frame or throttled client-side updates.

Do not assume level.object_by_id(id) succeeds for an offline object. Use the simulator/server object path when the object may be offline.

Switching

The engine decides when objects switch online or offline based on ALife rules, level state, distance, and object type. Console variables such as al_switch_distance, al_objects_per_update, and related ALife settings affect this process.

XRF binders receive net_spawn(...) when an object goes online and net_destroy() when it goes offline or is destroyed. Put registration and callback setup in the online path, and cleanup in the offline path.

Updates and scheduling

The engine drives updates for online binders. XRF turns those updates into higher-level events and timers so managers do not need to poll unrelated objects directly.

Binder updates

An online binder can receive update(delta) from the engine. Use it for object-local behavior:

• actor update orchestration;
• stalker and monster state managers;
• active restrictor, anomaly, smart terrain, and physic object logic;
• sound manager updates tied to a specific object id.

Call super.update(delta) when overriding an engine binder method unless nearby code shows a deliberate reason not to.

Actor update events

ActorBinder.update(delta) is the central XRF update pump. It emits:

• ACTOR_FIRST_UPDATE once after start or load;
• ACTOR_UPDATE every actor update;
• ACTOR_UPDATE_100;
• ACTOR_UPDATE_500;
• ACTOR_UPDATE_1000;
• ACTOR_UPDATE_5000;
• ACTOR_UPDATE_10000.

It also ticks the XRF timer manager and refreshes actor-related simulation object availability.

Use the throttled actor events for recurring manager work. For example, weather, input, psy, debug, and UI-related systems can subscribe to the event cadence they actually need.

Timers

EventsManager extends the timer manager and supports delayed and interval callbacks. Timers tick from the actor update path, so they require an active actor update loop.

Use timers for short delayed script work. Do not use them as durable save/load state unless the owning manager explicitly serializes enough data to restore the behavior.

ALife scheduling

Offline simulation is controlled by the engine and ALife settings. XRF can temporarily adjust object processing during startup; for example, actor reinit allows a broader ALife update window and then schedules a return to the stable configured value.

Keep online binder updates, manager event updates, and offline ALife scheduling separate. They run at different layers and have different save/load assumptions.

Script engine

The script engine chapter documents the XRF gameplay layer: TypeScript scripts, generated Lua, LTX/XML configs, forms, translations, schemes, managers, binders, and gameplay data.

The engine starts Lua and calls XRF entry points. XRF then owns most gameplay behavior above the native X-Ray runtime.

Source layout

Generated Lua, generated configs, copied resources, coverage, and packed outputs are written under target/. Do not edit target/ by hand.

Runtime entry points

The script layer starts from _g.script, then loads register, bind, and start.

• register exposes game classes, UI classes, tasks, dialogs, conditions, effects, and callbacks.
• bind selects object binder classes for online engine objects.
• start initializes managers, schemes, extensions, simulation state, and emits GAME_STARTED.

Most gameplay work is then handled by managers, schemes, object binders, and event callbacks.

Config-driven behavior

XRF keeps vanilla-style config behavior where possible. LTX logic sections still drive object logic, condlists still call conditions and effects, and XML files still define dialogs, tasks, character descriptions, UI forms, and gameplay data.

When changing behavior, trace the full path:

1. config field or XML entry;
2. parser or build helper;
3. runtime manager, scheme, binder, or extern;
4. test or validation command.

For config changes, compare against original gamedata when baseline behavior matters.

Validation

Use focused validation first:

npm test -- <path-or-pattern>
npm run typecheck
npm run cli verify ltx
npm run cli build -- --filter configs

Use broader npm run verify or npm run build when a change touches shared config, generated output, or multiple runtime systems.

Assets

Assets are static gamedata resources copied into the build output. They are separate from TypeScript source, generated Lua scripts, generated configs, and generated UI XML.

The main source directory is src/resources. Project asset override roots can also be included by the build when asset overrides are enabled for a language.

What gets copied

The resources build step copies files and folders into target/gamedata. It skips repository metadata and unpacked working folders such as textures_unpacked and particles_unpacked.

It also rejects resource folders that overlap with generated source areas such as core, configs, lib, and scripts. Those names are reserved for generated or source-owned content.

Filtering

Build filters are applied to resource paths. Use a filter when you only need to rebuild a focused asset group:

npm run cli build -- --filter textures
npm run cli build -- --filter sounds

The filter behavior is path based. Check the source path when a filtered build appears to skip an expected file.

Editing assets

Treat src/resources as base resource data. Avoid casual edits there unless the work is explicitly about resources. For new generated game data, prefer the appropriate source folder:

• configs in src/engine/configs;
• UI forms in src/engine/forms;
• translations in src/engine/translations;
• scripts in src/engine/scripts and src/engine/core.

Do not patch packed output or files under target/.

Validation workflow

After asset changes, run the narrowest build filter that covers the path you touched. Then inspect target/gamedata to confirm the copied path matches the engine-facing layout.

Use format-specific tools for packed or structured assets:

• icon texture workflows through icons commands;
• particles.xr workflows through particles commands;
• spawn workflows through spawn commands;
• archive inspection through the Tools CLI archive commands.

If an asset change depends on config references, validate the LTX/XML source that points at the asset as well.

Configs

XRF stores game configuration source under src/engine/configs. The build copies static .ltx and .xml files and generates additional .ltx or .xml files from TypeScript sources.

Config files are runtime behavior. Script configs can switch schemes, call effects, check conditions, spawn objects, define smart terrain jobs, describe tasks, load dialogs, configure weapons, and drive weather.

Domain pages

The config chapter is split by the kind of runtime data being edited.

Source types

Dynamic .ts LTX sources must export create() or config. Dynamic .tsx XML sources must export create().

Includes and inheritance

LTX files use normal X-Ray include and inheritance syntax:

#include "items\weapons\base.ltx"

[wpn_example]:identity_immunities
class = WP_AK74

Generated LTX sources can express includes and section inheritance through the helper symbols used by renderJsonToLtx.

Validation

Run LTX validation after changing config shape, includes, inheritance, or $scheme coverage:

npm run cli verify ltx

Use strict validation when the change is specifically about schema coverage:

npm run cli verify ltx -- --strict

For generated configs, also run a focused build:

npm run cli build -- --filter configs

Do not edit generated files under target/. Fix the source config or generator instead.

LTX scheme

src/engine/configs/$scheme contains validation schemas for LTX configs. The verify-ltx tool uses these files to check includes, inheritance, field names, and field types.

The root file is scheme.ltx. It includes category schemas such as base.scheme.ltx, script.scheme.ltx, environment.scheme.ltx, items.scheme.ltx, weapons.scheme.ltx, and zone.scheme.ltx.

Defining a schema section

A schema section starts with a section name. Use inheritance when several config sections share fields:

[$item_weapon]:$item,$item_weapon_sounds,$item_weapon_params
strict = true
ammo_class = ?string[]
ammo_mag_size = ?u32
weapon_class = ?enum:assault_rifle,shotgun,sniper_rifle,heavy_weapon,pistol,grenade,misc

Schema section names commonly start with $ to separate schemas from game config sections.

Field syntax

Optional marker ? can be combined with arrays, enums, tuples, and section references.

Available types

Common schema types:

• string
• section
• tuple
• condlist
• f32
• u32
• i32
• u16
• i16
• u8
• i8
• bool
• vector
• enum
• unknown
• any

Prefer the narrowest type that matches the engine behavior. Use unknown or any only when the field is intentionally untyped or still being investigated.

Arrays, enums, and tuples

Arrays use []:

levels = ?string[]
installed_upgrades = ?section[]

Enums list allowed values:

scope_status = ?enum:0,1,2
flares = enum:on,off

Tuples define ordered values:

fire_point = ?tuple:f32,f32,f32
hit_power = ?tuple:f32,f32,f32,f32

Strict sections

strict = true means fields not described by the schema are validation errors unless a wildcard rule covers them. Use strict schemas for stable config formats such as weapons, weather, and script definitions.

Leave strict mode off only when the config format is intentionally open-ended or not fully modeled yet.

Verification

Run:

npm run cli verify ltx

When a valid config fails validation, update the matching schema section instead of weakening unrelated schemas. When a schema accepts invalid data, add a narrower field type or enable strict mode for that schema if the format is stable.

Condlists

Condlists are conditional config expressions used throughout script configs, task configs, dialogs, and scheme switches. A condlist can check info portions, call conditions, apply side effects, and return a value.

Basic shape:

{conditions} value %effects%

Multiple entries are separated by commas and checked in order. The first matching entry wins:

on_info = {+quest_started} walker@active %=play_sound(quest_start)%, sr_idle

Conditions

Function parameters use colon separators:

{=actor_has_item(af_oasis_heart)}
{!npc_in_actor_frustum =dist_to_actor_le(30)}

Effects

Effects live inside %...%:

%=give_inited_task(jup_b1_task) +jup_b1_started -jup_b1_waiting%

Inside effects:

• =effect_name calls xr_effects.effect_name;
• +info_name gives an info portion;
• -info_name disables an info portion.

This means reading a config value can change game state. Check the caller before assuming a condlist is pure.

Generated condlists

Generated LTX sources should use helpers from cli/utils/ltx/condlist.ts:

• checkCondition(...)
• checkNoCondition(...)
• checkChance(...)
• checkHasInfo(...)
• checkNoInfo(...)
• callEffect(...)
• addInfo(...)
• removeInfo(...)
• createCondlist(...)
• joinCondlists(...)

These helpers keep generated syntax consistent with the runtime parser.

Parser limits

The parser is pattern-based. Avoid nested commas, nested parentheses, and quoted strings that require custom escaping. If new syntax is needed, update parser tests before relying on it in configs.

Debugging workflow

When a condlist does not behave as expected:

1. identify the caller, such as a scheme switch, task field, dialog phrase, or smart terrain job;
2. check whether the caller expects a returned section/value or only side effects;
3. search for the condition under src/engine/scripts/declarations/conditions;
4. search for the effect under src/engine/scripts/declarations/effects;
5. add or update tests for parser helpers when generated syntax changes.

Keep side effects guarded with info portions when the same condlist can be evaluated repeatedly.

Dialog configs

Dialog configs define conversation XML and script predicates/actions used by dialog phrases. XRF keeps dialog data under src/engine/configs/gameplay and dialog script externs under src/engine/scripts/declarations/dialogs.

Use this page when you need to add a phrase, wire a phrase to script, or check why a dialog option is not visible.

Source files

Core dialog XML files:

• src/engine/configs/gameplay/dialogs.xml
• src/engine/configs/gameplay/dialogs_zaton.xml
• src/engine/configs/gameplay/dialogs_jupiter.xml
• src/engine/configs/gameplay/dialogs_pripyat.xml

Dialog text lives in translation files such as:

• src/engine/translations/st_dialogs.json
• src/engine/translations/st_dialogs_zaton.json
• src/engine/translations/st_dialogs_jupiter.json
• src/engine/translations/st_dialogs_pripyat.json

Script callbacks live in:

• src/engine/scripts/declarations/dialogs/dialogs.ts
• src/engine/scripts/declarations/dialogs/dialogs_zaton.ts
• src/engine/scripts/declarations/dialogs/dialogs_jupiter.ts
• src/engine/scripts/declarations/dialogs/dialogs_pripyat.ts
• src/engine/scripts/declarations/dialogs/dialog_manager.ts

Generic dialog state is handled by src/engine/core/managers/dialogs/DialogManager.ts. The manager tracks phrase priority tables, disabled phrases, and generic phrase categories such as hello, job, anomalies, and information.

Runtime hooks

Dialog XML can call script functions through registered dialog externs. XRF registers these from src/engine/scripts/declarations/dialogs. The global script entry point loads externals_registrator, and the registrator exposes dialogs, dialogs_zaton, dialogs_jupiter, dialogs_pripyat, and dialog_manager.

dialog_manager.ts also exports callbacks used by generated generic dialogs. Examples include:

• dialog_manager.init_new_dialog;
• dialog_manager.fill_priority_hello_table;
• dialog_manager.precondition_job_dialogs;
• dialog_manager.action_information_dialogs;
• dialog_manager.action_disable_phrase.

Keep XML callback names in sync with the extern name. A typo in XML does not create a TypeScript error at the call site.

When changing a dialog:

1. update the XML phrase flow;
2. update translation ids used by the phrases;
3. update or add dialog predicate/action externs when XML calls script;
4. test the dialog declaration code when behavior changes.

Editing workflow

Start from the dialog id and search across gameplay XML, translation JSON, and dialog declarations. Most quest dialogs touch at least two of those areas: XML controls phrase flow, translations hold the text, and declarations decide whether a phrase is visible or what action runs after selection.

For a script-backed phrase:

1. add the XML phrase node and translation id;
2. reference an existing callback or add a new extern(...) in the matching declaration file;
3. update tests beside the declaration when the callback has logic;
4. run a focused test for the declaration file, then run config verification if XML changed.

Use location-specific declaration files when the condition belongs to a level quest. Use dialog_manager.ts for generic dialog category behavior only.

Generated XML

Some gameplay XML is generated from .tsx sources. Dynamic XML sources export create() and are rendered with renderJsxToXmlText.

Do not edit generated XML under target/. Change the XML source or TSX generator.

Validation notes

• externals_registrator.test.ts confirms the dialog extern namespaces are registered.
• Dialog declaration tests check individual callback bindings and branch behavior.
• Translation ids must exist in the matching st_dialogs*.json file, otherwise the game can show raw ids or missing text.
• If a dialog changes quest state, check the related task, info portion, and effect declarations in the same pass.

Script configs

Script configs are LTX files that drive object logic. They live under src/engine/configs/scripts and are copied to target/gamedata/configs/scripts.

These files are active gameplay data. They select schemes, configure object binders, define section switching, call conditions and effects, and describe smart terrain jobs.

Common structure

Most logic files start from [logic]:

[logic]
active = sr_idle

[sr_idle]
on_info = {+some_info} sr_idle@done %=some_effect%

[sr_idle@done]

The active section name selects the scheme. Suffixes such as @done let one scheme have multiple named states.

Common fields

Common script logic fields include:

• active in [logic], selecting the first section;
• on_info, on_signal, on_timer, and related switch fields;
• on_actor_inside, on_actor_outside, and zone-related switch fields;
• on_death and on_hit for event-driven switches;
• suitable and prior for smart terrain job selection;
• spawn for item sections spawned on activation;
• scheme-specific fields such as paths, animations, sounds, dialogs, and combat flags.

Field support depends on the active scheme. Check the scheme implementation before adding a field.

Extern calls

Condlists call short names, but the registered functions live under global namespaces:

• {=actor_has_item(wpn_pm)} calls xr_conditions.actor_has_item;
• %=give_inited_task(task_id)% calls xr_effects.give_inited_task.

Search both the short config name and the full extern name before renaming a condition or effect.

Validation

Use LTX validation after editing script configs:

npm run cli verify ltx

For behavior changes, test the scheme, condition, effect, or manager that reads the field.

Editing workflow

Start from the object, smart terrain job, or restrictor that owns the logic file. Follow [logic] active to the active section, then identify the scheme from the section prefix before @.

When a switch does not fire, check the pieces in this order:

1. the active section name;
2. the switch field supported by that scheme;
3. the condlist conditions and effects;
4. the target section existence;
5. any runtime event needed to trigger the manager, such as hit, death, use, signal, or actor-zone update.

Creatures

Creature configs describe the actor, stalkers, monsters, crows, and online/offline squads. They live under src/engine/configs/creatures and are included through src/engine/configs/creatures/index.ltx.

These files are not only stats tables. A creature section also selects the engine class, script binder, physical settings, perception values, sounds, movement tuning, immunities, and condition sections used by runtime logic.

Source files

Runtime binding

Creature sections attach TypeScript runtime code through script_binding.

The engine class still matters. For example, actor sections use an actor class, stalker sections use stalker classes, and monster sections use species-specific monster classes. The script binder extends that engine object with XRF runtime logic.

Actor sections

The actor config starts at [actor] and uses $scheme = $actor. It links the runtime binder through script_binding = bind.actor.

Actor-related sections cover:

• movement and inventory limits, such as sprint, crouch, jump, and carried mass values;
• physical settings, collision damage, bones, and corpse handling;
• hit probabilities, immunities, condition sections, and hit sounds;
• actor HUD linkage through player_hud_section;
• default quick item slots.

Use the actor schema when adding new actor fields. If validation rejects a real engine field, update the schema instead of bypassing validation in the config.

Stalker sections

Stalker configs use $scheme = $stalker and describe NPC-level behavior visible to both the X-Ray engine and XRF runtime.

Common stalker fields include:

• script_binding, usually bind.stalker;
• community, rank, terrain, and movement sections;
• visual and sound configuration;
• perception settings such as view distance, visibility, and sound perception;
• condition, damage, immunities, and material sections;
• spawn metadata and editor fields.

Scenario logic is usually not placed directly in the creature section. Stalker behavior for a specific story object is normally driven by script configs, smart terrain jobs, and schemes.

Monster sections

Monster configs inherit from shared monster bases and then specialize by species. The base sections provide common movement, perception, damage, sound, and physical behavior. Species files tune attacks, locomotion, particles, sounds, protections, and spawn sections for each monster family.

Monster runtime behavior is attached through bind.monster. During spawn, the binder registers the object, initializes scheme logic with the monster scheme type, and later handles section switching, online/offline transitions, sound cleanup, and smart terrain participation.

When editing monster configs, compare the closest existing species file first. Many fields are species-specific engine parameters, and nearby sections are usually the best source for valid value shape.

Online/offline groups

$scheme/creatures.misc.scheme.ltx validates online_offline_group sections. These sections describe squad-style spawn groups and can include fields such as faction, NPC section lists, random NPC pools, target smart terrain, behavior, death conditions, and invulnerability.

Use these sections when the config needs to describe a squad or group that moves through simulation, rather than a single creature section.

Editing checklist

When changing creature configs:

• keep the $scheme marker on sections that validation should check;
• keep script_binding aligned with the engine class and intended runtime binder;
• update referenced condition, immunities, sound, terrain, movement, and damage sections together;
• check script configs and smart terrain jobs before assuming behavior belongs in the creature base section;
• run LTX validation after schema or config changes:

npm run cli verify ltx

Zones and anomalies

Zone configs describe anomaly fields, anomaly mines, campfires, teleport and no-gravity zones, space restrictors, level changers, and composite anomaly zones that can spawn artifacts. Static zone sections live under src/engine/configs/zones; script-level zone objects live in src/engine/configs/objects/zone_objects.ltx.

Use this page when you need to decide whether a behavior belongs in a base zone section, a script object section, or a scenario-specific anomaly config.

Source files

Runtime binding

Zone-related sections attach runtime behavior through script_binding.

The binding tells XRF which TypeScript binder should manage the object. The engine class still controls the underlying X-Ray object type, collision behavior, and native zone behavior.

Base zone sections

Most static anomaly sections inherit from [zone_base] or a specialized zone parent and use $scheme = $zone.

Common zone fields include:

• particle and sound names for idle, entrance, hit, and blowout states;
• hit settings such as hit type, hit impulse, and power values;
• light, wind, postprocess, and visual shape settings;
• artifact handling flags such as ignore_artefacts;
• spawn metadata and editor fields.

Use inheritance for variants such as weak, average, and strong anomaly sections. Keep the shared behavior on the parent section and override only the values that differ.

Script zone objects

objects/zone_objects.ltx defines script-level objects that are not ordinary anomaly damage sections.

Important sections include:

• [space_restrictor], managed by bind.restrictor;
• [anomal_zone], managed by bind.anomaly_zone;
• [camp_zone], managed by bind.camp;
• [level_changer], managed by bind.level_changer;
• [script_zone], used for arena-style script zones.

Choose these sections when the object is meant to drive script logic, travel, restrictions, camps, or composite anomaly behavior rather than a standalone damage field.

Composite anomaly zones

Composite anomaly zones are managed by AnomalyZoneBinder. The binder reads the spawned object’s anomal_zone section and may also read an additional config file from the cfg field.

The binder reads fields such as:

• layers_count;
• respawn_tries;
• max_artefacts;
• applying_force_xz and applying_force_y;
• artefacts;
• start_artefact;
• artefact_ways;
• field_name;
• coeff;
• coeffs_section.

Each layer_N section can override artifact counts, respawn tries, maximum artifacts, forces, artifact lists, starting artifacts, and waypoint lists for that layer.

Use composite anomaly configs when the gameplay object needs to coordinate several anomaly fields and artifact spawning rules. Use a normal zone section when you only need an individual field, mine, or damage source.

Editing checklist

When changing zones or anomalies:

• keep script_binding aligned with the section’s runtime role;
• do not mix regular field sections with anomal_zone composite configs;
• keep $scheme = $zone on sections validated by zone.scheme.ltx;
• verify referenced particles, sounds, postprocess names, artifact sections, and waypoint names;
• check story links and map placement when changing level changers or restrictors;
• run LTX validation after config or schema changes:

npm run cli verify ltx

Smart terrains and jobs

Smart terrain configs describe places where squads and individual objects can work. Job configs decide which object can take which logic section and with what priority.

The source files live mostly under src/engine/configs/scripts/**/smart plus shared smart terrain configs such as sim_smart_base.ltx and sim_smart_resource.ltx.

Smart terrain role

A smart terrain is a server-side simulation object. It owns jobs, tracks assigned objects, and participates in offline ALife simulation. When an assigned object goes online, its binder and scheme logic run on the client side.

Use smart terrain configs for simulation placement and job selection. Use scheme sections for the actual object behavior once the job is active.

Job fields

Common job fields include:

• logic, pointing to the script config and section used by the object;
• prior, defining selection priority;
• suitable, checking whether the object can take the job;
• active, selecting the active logic section;
• path_walk and path_look, used by walker-style schemes;
• on_info and other condlists for switching job state.

The exact fields depend on the scheme used by the job.

Editing workflow

When changing a smart terrain job:

1. find the smart terrain section and job section;
2. follow logic or active to the scheme section;
3. check suitable and prior if the NPC does not select the job;
4. check scheme implementation and parser support for any new field;
5. validate LTX includes and schema.

Run:

npm run cli verify ltx

Treasures

Treasure configs describe hidden stashes and the rewards assigned to them. XRF reads treasure data through TreasureManager and related treasure utilities.

Use this page when you need to add a stash, grant stash coordinates from a quest, or check why a marked stash does not produce the expected reward.

Source files

Treasure manager source files live under:

• src/engine/configs/managers/treasure_manager.ltx
• src/engine/configs/managers/treasures/treasures_zaton.ltx
• src/engine/configs/managers/treasures/treasures_jupiter.ltx
• src/engine/configs/managers/treasures/treasures_pripyat.ltx

Script configs can also reference treasure inventory boxes, for example src/engine/configs/scripts/treasure_inventory_box.ltx.

Quest and restrictor scripts grant stash coordinates with the give_treasure effect. Examples exist in task configs and script logic, including:

• src/engine/configs/managers/tasks/tasks_zaton.ltx;
• src/engine/configs/managers/tasks/tasks_jupiter.ltx;
• src/engine/configs/scripts/jupiter/jup_b43_task_giver_restrictor.ltx;
• src/engine/configs/scripts/pripyat/pri_b36_sr_ahi_place_pda.ltx.

Runtime behavior

Treasure data is loaded by the treasure manager. It tracks which treasures are available, found, or already looted, and coordinates map spot display through map utilities.

The script effect xr_effects.give_treasure calls TreasureManager.giveActorTreasureCoordinates(...) for each passed treasure id. This grants coordinates; the treasure definition still controls the stash metadata and reward contents.

Physical treasure containers enter the manager through object binders. ObjectPhysic and ObjectHangingLamp call TreasureManager.registerItem(this) when they are constructed, so the manager can connect spawned world objects to treasure data.

When changing treasure behavior, check both:

• the manager config that defines treasure metadata and rewards;
• the script config or object section that represents the stash in the world.

Example grant

This pattern appears in Jupiter quest logic. It grants one treasure once and then records that the reward was already given:

[sr_idle@reward]
on_info = {+jup_b43_contract_brought_first_artefact -jup_b43_once_treasure_give_1} %=give_treasure(jup_hiding_place_5) +jup_b43_once_treasure_give_1%

Use an info portion guard when the same logic section can be evaluated more than once.

Editing checklist

• Keep treasure ids stable once saves can reference them.
• Keep reward sections valid and included.
• Check map spot behavior when a treasure should appear on the PDA.
• Check the world object or inventory box section that represents the stash.
• Check quest scripts that grant the treasure with give_treasure.
• Test TreasureManager or treasure utility code when changing runtime behavior.
• Run npm run cli verify ltx after config edits.

Weapons

Weapon configs live under src/engine/configs/items/weapons. They define base weapon sections, HUD sections, sounds, ballistics, upgrade links, add-ons, ammo classes, and mounted weapons.

Source layout

Important files and folders:

• base.ltx for shared weapon definitions;
• index.ltx for includes;
• w_*.ltx for individual weapon sections;
• upgrades/*.ltx for weapon upgrade trees;
• weapon_upgrades.ltx and upgrades_properties.ltx for shared upgrade data;
• $scheme/weapons.scheme.ltx for validation coverage.

Validation schema

Weapon schemas are mostly strict. They model common sections such as:

• $item_weapon;
• $item_weapon_hud;
• $item_weapon_sounds;
• $item_weapon_attachable;
• $item_weapon_params;
• $item_weapon_grenade;
• $item_weapon_knife;
• $weapon_mounted.

If a valid weapon field fails validation, update the narrow matching schema instead of disabling strict validation for the whole weapon category.

Runtime links

Weapon configs reference assets and other config sections:

• visual, item_visual, HUD positions, and bones;
• sound aliases such as snd_shoot and snd_reload;
• particle aliases such as flame_particles and shell_particles;
• ammo sections through ammo_class;
• upgrade sections through upgrades, installed_upgrades, and upgrade_scheme;
• add-on sections for scopes, silencers, and grenade launchers.

Check all referenced sections and assets when adding a weapon variant.

Editing checklist

• Compare against a nearby weapon with the same weapon class.
• Keep HUD and world model sections separate.
• Validate upgrade section names and include order.
• Run npm run cli verify ltx.
• Test script-side weapon utilities only when changing runtime TypeScript behavior.

Common failure points

• Missing include order can make a weapon section valid in isolation but unavailable from the final item index.
• HUD section names must stay aligned with the weapon section fields that reference them.
• Ammo, scope, silencer, and grenade-launcher section names must exist before the weapon can use them.
• Texture, model, sound, and particle references are not fixed by LTX formatting; verify the referenced resource files separately.

Weather

Weather configs define environment cycles, ambient sounds, fog, suns, thunderbolts, weather effects, and manager-level weather selection. Runtime weather behavior is handled by WeatherManager.

Source layout

Important source areas:

• src/engine/configs/environment/environment.ltx;
• src/engine/configs/environment/weathers/*.ltx;
• src/engine/configs/environment/weather_effects/*.ltx;
• src/engine/configs/environment/ambients/*.ltx;
• src/engine/configs/environment/ambient_channels/*.ltx;
• src/engine/configs/environment/fog/*.ltx;
• src/engine/configs/environment/dynamic_weather_graphs.ltx;
• src/engine/configs/managers/weather_manager.ltx;
• src/engine/configs/managers/weather/weather_manager_levels.ltx.

Weather sections

The $weather schema is strict and includes fields for sky, fog, rain, sun, clouds, wind, water, ambient, thunderbolt, and sun shafts. A weather cycle is built from time sections that point the engine at these values.

Weather effect sections describe temporary events such as surge, blowout, and psi storm effects. They reference particles, sound, wind, and lifetime fields.

Runtime manager

WeatherManager subscribes to actor update events and actor online events. It applies configured weather and exposes debug information through the XRF debug panel.

On actor network spawn, the manager reads the current level’s weathers value from game.ltx. If no level-specific value is configured, it uses the AtmosFear-style dynamic weather section. The selected value is parsed as a condition list and becomes the source for later weather section selection.

During actor updates, the manager:

• checks hourly changes and advances weather graph state;
• changes good/bad weather periods when the configured period boundary is reached;
• marks pre-blowout weather when a surge or weather FX is close;
• updates DOF every five game seconds for active AtmosFear weather;
• saves and loads weather section, period, graph state, and active weather FX data.

When changing weather selection logic, update manager tests. When changing only LTX values, validate the configs and check the result in game.

Validation

Run:

npm run cli verify ltx

Use the debugging weather page for in-game inspection and debug panel workflow.

Editing notes

• Edit weather cycle values under environment/weathers when changing sky, fog, rain, sun, or ambient output.
• Edit dynamic_weather_graphs.ltx when changing transitions between clear, cloudy, rainy, or related graph states.
• Edit weather_manager_levels.ltx and game.ltx links when changing which weather set a level uses.
• Use a save/load check after manager logic changes because weather state is serialized.

Effects and conditions

Effects and conditions are Lua externals called from config condlists. They are the bridge between LTX logic and XRF TypeScript behavior.

Effects are registered under xr_effects. Conditions are registered under xr_conditions.

Source layout

Config names

Configs call short names:

on_info = {=actor_has_item(af_oasis_heart)} %=give_inited_task(jup_b16_task)%

The registered globals include the namespace:

• actor_has_item resolves to xr_conditions.actor_has_item;
• give_inited_task resolves to xr_effects.give_inited_task.

Search both names before changing an effect or condition.

Function shape

Effect and condition declarations commonly receive the actor object, the current object, and a parameter array parsed from the condlist:

%=play_sound(story_sound_id)%
{=dist_to_actor_le(30)}

Parameters in configs are colon-separated. Keep parsing simple and update parser tests before adding syntax that needs nested values or escaping.

Side effects

Conditions should answer a question. Effects may mutate game state: give or remove info portions, start tasks, play sounds, set weather, spawn objects, save the game, or switch object state.

pickSectionFromCondList can run effects while choosing a section. A field that looks like a value read may still change state if its matching condlist entry contains %...%.

Testing

Effect and condition files have focused Jest tests beside the declarations. When changing behavior, update the matching test:

npm test -- src/engine/scripts/declarations/effects
npm test -- src/engine/scripts/declarations/conditions

For config changes that call the function, also run:

npm run cli verify ltx

Forms

Forms are UI XML sources used by engine CUI classes. XRF keeps most form source in TSX under src/engine/forms and builds it into XML.

Runtime UI classes live under src/engine/core/ui. They load XML, initialize controls, register callbacks, and update the UI at runtime.

Source types

Dynamic forms must export create(). The UI build calls it and writes the result through renderJsxToXmlText.

Components

Shared JSX components live under src/engine/forms/components. Common base components include:

• XrRoot;
• XrElement;
• XrStatic;
• XrText;
• Xr3tButton;
• XrCheckBox;
• XrEditBox;
• XrScrollView;
• XrTab;
• XrTexture.

Prefer these helpers over manually assembling repeated XML structures.

Runtime loading

Runtime classes use engine UI helpers such as CScriptXmlInit, CUIScriptWnd, CUIStatic, CUI3tButton, CUIListBox, and related CUI bindings.

When changing a form:

1. find the runtime class that loads it;
2. keep XML node names stable unless the runtime lookup is updated;
3. check paired 16:9 variants such as name.tsx and name_16.tsx;
4. update tests for runtime UI classes when element names or callbacks change.

Validation

Run a focused UI build after form changes:

npm run cli build -- --filter ui

Do not edit generated XML under target/.

Debugging workflow

If a control does not appear or a callback does not fire, check the runtime class before changing the form. Most UI classes look up controls by XML node name, so a renamed node can break runtime initialization even when the XML builds.

For layout issues, compare the generated XML with the TSX source and any paired widescreen variant. For behavior issues, inspect the src/engine/core/ui class that loads the form and binds callbacks.

Patrols

Patrol paths are level-authored waypoint paths used by stalker schemes, monster movement, smart cover targets, travel, spawn helpers, and simulation utilities.

For stalker logic, XRF routes most waypoint behavior through StalkerPatrolManager. Schemes such as walker, sleeper, patrol, and reach_task configure the manager with path_walk, optional path_look, team synchronization, suggested states, and waypoint callbacks.

Related schemes

• walker
• remark
• sleeper
• camper
• patrol
• reach_task
• smartcover

path_walk

path_walk is the movement path. The scheme reads it from config, verifies the patrol path exists, parses waypoint metadata, and sends the object along the path.

Supported waypoint flags include:

If no sig is provided on the last walk waypoint, the manager emits path_end.

path_look

path_look is an optional look/idle path paired with path_walk. The engine uses waypoint flags to choose a matching look point for a reached walk point.

Supported look flags include:

syn is intended for terminal coordination. XRF asserts when it is used on a non-terminal waypoint.

Example

Button-style interaction that plays a press state, then switches when the timed animation signal is emitted:

path_look waypoint flags: a=press|t=0|sigtm=pressed
logic field: on_signal = pressed | next_scheme@section

The exact waypoint flag syntax is stored in level patrol data, not in the LTX file. LTX sections reference the patrol path names through fields such as path_walk and path_look.

Debugging

If a patrol does not work:

• verify level.patrol_path_exists(path_name) would pass for path_walk and path_look;
• check that path_look is not the same path as path_walk;
• check waypoint flags when look points are not selected;
• check on_signal when the movement reaches a point but the scheme does not switch;
• use AI debug overlays and object dumps from the debug panel when the active state is unclear.

UI elements

UI elements are engine CUI bindings exposed to Lua. XRF uses them from runtime UI classes and initializes most controls from XML generated by src/engine/forms.

Use the XRF X-Ray 16 SDK as the API reference for exact methods. This page gives the practical map of common classes.

XML initialization

CScriptXmlInit loads XML and creates controls from node selectors.

Common methods include:

• ParseFile(path);
• ParseShTexInfo(path);
• InitWindow(selector, index, window);
• InitStatic(selector, parent);
• InitTextWnd(selector, parent);
• Init3tButton(selector, parent);
• InitCheck(selector, parent);
• InitComboBox(selector, parent);
• InitEditBox(selector, parent);
• InitListBox(selector, parent);
• InitScrollView(selector, parent);
• InitTab(selector, parent);
• InitTrackBar(selector, parent).

Call ParseFile() before using Init* helpers. Controls created with a parent are attached to that parent by the engine binding.

Window base classes

Use CUIScriptWnd for custom script windows that need callbacks or registered child controls.

Static and text controls

Use SetTextST(...) when the text should come from translations.

Buttons and inputs

For settings screens, prefer the existing option window patterns under src/engine/core/ui/menu/options.

Lists and tabs

Ids and visual indices are not the same for combo boxes, tabs, and lists. Use ids for stable logic and indices for visual order.

Frames, maps, and message windows

Lifetime and callbacks

Parent-owned controls are adopted by the engine UI tree. After attaching a child or adding an item to a list, treat the parent/list as owning its lifetime.

For CUIScriptWnd, register child controls before adding callbacks or using typed lookup helpers. Callback names depend on the registered window name, so keep XML node names and registration names aligned.

Runtime Lifecycle

The runtime lifecycle is the path from xray loading Lua scripts to XRF managers, binders, schemes, and server objects owning live gameplay state.

Read this section before changing object registration, manager startup, save/load, online/offline transitions, or event emission order.

Startup Flow

The main game-start callback is start.callback(isNewGame) in src/engine/scripts/start.ts. It runs for both new games and loaded games.

Startup order:

1. update cached class ids from classIds;
2. register the ALife simulator;
3. register rank descriptors;
4. unlock system ini overriding;
5. register managers;
6. register schemes;
7. register extensions;
8. emit GAME_STARTED.

Managers, schemes, and extensions should not depend on object binders already being online during this callback. Online objects arrive later through binder calls from the engine.

Object Flow

The usual runtime path is:

1. xray loads script entry modules such as register, bind, and start.
2. start.callback initializes shared runtime systems.
3. xray creates an online game object and calls a function from the bind extern module.
4. The binder attaches a TypeScript object_binder subclass to the game object.
5. net_spawn registers the object in the runtime registry and sets up callbacks.
6. update runs per-frame or throttled behavior.
7. net_destroy unregisters callbacks and registry state when the object goes offline.
8. save and load persist binder and scheme state when the object is save-relevant.

Server-side objects use related ALife callbacks such as on_register, on_unregister, STATE_Write, and STATE_Read.

Runtime Owners

Keep state near the owner that controls its lifecycle. A binder should not become the permanent owner of a cross-object system. A manager should not store short-lived object state that belongs in registry.objects.

First Places To Check

• For startup order, read src/engine/scripts/start.ts.
• For binder factories, read src/engine/scripts/bind.ts.
• For manager startup, read src/engine/scripts/register/managers_registrator.ts.
• For manager registry helpers, read src/engine/core/database/managers.ts.
• For shared state, read src/engine/core/database/registry.ts.
• For save/load coordination, read src/engine/core/managers/save/SaveManager.ts.

Editing Checklist

• Identify whether the change belongs to a binder, manager, registry helper, scheme, or server object.
• Check both online and offline paths.
• Check save and load paths if state must survive reload.
• Preserve event order unless the task is specifically about event behavior.
• Add focused tests near the lifecycle owner.

Runtime Binders

Binders attach TypeScript lifecycle code to online xray game objects. They are registered through the bind extern module in src/engine/scripts/bind.ts.

Use binders for client-side lifecycle glue: registering an object, installing engine callbacks, initializing logic, and cleaning up when the object goes offline.

Binder Families

Some binder factories are conditional:

• arena_zone binds only when the spawn ini contains arena_zone;
• helicopter binds only when the spawn ini contains logic;
• physic_object binds only when the object has logic or is an inventory box;
• smart_terrain binds only when the spawn ini contains smart_terrain.

Common Lifecycle Methods

Most binders implement some subset of:

• reinit: reset local and registry state;
• net_spawn: object came online;
• update: object update tick;
• net_destroy: object went offline;
• net_save_relevant: whether binder state should be saved;
• save: write binder and object logic state;
• load: read binder and object logic state.

Use the same read/write order in save and load. When a binder persists object logic, it usually wraps the operation in save markers and calls saveObjectLogic / loadObjectLogic.

Actor Binder

ActorBinder is the global update driver for many runtime systems.

On online switch it:

• shows indicators;
• registers actor references;
• initializes actor portable store;
• emits ACTOR_GO_ONLINE.

On reinit it registers the actor again, resets portable store, installs actor callbacks, enables unlimited ALife update for the initial spawn buffer, schedules stable ALife updates, and emits ACTOR_REINIT.

On update it emits ACTOR_UPDATE, throttled actor update events, processes EventsManager timers, and updates actor simulation availability.

Stalker Binder

StalkerBinder owns online stalker setup. It creates the stalker state manager and patrol manager, sets up planners, registers the stalker in the registry, installs callbacks, initializes sound themes, initializes object logic, and sets up post-combat idle behavior.

On offline switch it stops sounds, emits scheme offline events, applies on_offline overrides, stores offline state, and unregisters the stalker.

Restrictor Binder

RestrictorBinder is a compact example for zone lifecycle:

• reinit resets object registry state;
• net_spawn registers the zone and starts looped sounds;
• first update initializes restrictor scheme logic;
• later update tracks visited state, emits scheme updates, and updates sounds;
• net_destroy emits scheme offline behavior, stops sounds, and unregisters the zone;
• save and load persist object logic and visited state.

Guidelines

• Keep binders focused on object lifecycle.
• Use managers for cross-object systems.
• Use registry helpers instead of mutating registry tables directly.
• Reset engine callbacks when an object goes offline.
• Check net_save_relevant before assuming a binder’s save/load methods are used.

Runtime Managers

Managers are singleton runtime services stored in the registry. They own cross-object systems such as events, save/load, sound, simulation, trade, tasks, weather, upgrades, UI state, and debugging.

Managers extend AbstractManager from src/engine/core/managers/abstract/AbstractManager.ts.

Manager Access

Use the registry helper that matches the lifecycle you need:

getManager(SoundManager);
getWeakManager(SoundManager);
getManagerByName("SoundManager");

getManager(ManagerClass) is the normal path. It returns the existing singleton or initializes one.

getWeakManager(ManagerClass) returns null if the manager is not initialized.

getManagerByName(name) is mainly for circular-reference cases where the class reference is not available. It cannot initialize a missing manager.

Startup Managers

registerManagers() initializes the startup manager list during start.callback.

The current startup list is:

• ActorInputManager;
• ActorInventoryMenuManager;
• DatabaseManager;
• DebugManager;
• DialogManager;
• EventsManager;
• GameSettingsManager;
• LoadScreenManager;
• LoadoutManager;
• MapDisplayManager;
• MusicManager;
• NotificationManager;
• PdaManager;
• PhantomManager;
• ProfilingManager;
• ReleaseBodyManager;
• SaveManager;
• SimulationManager;
• SleepManager;
• SoundManager;
• StatisticsManager;
• TaskManager;
• TradeManager;
• TravelManager;
• TreasureManager;
• UpgradesManager;
• WeatherManager.

Other managers can still be initialized lazily with getManager. For example, SaveManager initializes SurgeManager after ACTOR_REINIT.

Lifecycle Methods

AbstractManager defines:

• initialize();
• destroy();
• update(delta);
• save(packet);
• load(reader).

The base update, save, and load methods abort. Implement only the methods the manager actually supports.

disposeManager calls destroy(), marks the manager as destroyed, and removes it from both registry maps.

Common Patterns

Managers that listen to events usually subscribe in initialize() and unsubscribe in destroy().

Managers with persistent state write to net packets through SaveManager or to dynamic save data through helpers. Keep save and load order synchronized.

Managers with delayed work should check isDestroyed before doing work after disposal.

Where To Add Behavior

• Use a manager for shared behavior across many objects.
• Use a binder when the behavior belongs to one online object.
• Use a scheme manager when the behavior belongs to one config scheme.
• Use a database helper when the behavior is narrow registry access.

Do not construct managers directly in runtime code. Use getManager unless a test is intentionally isolating a manager class.

Runtime Events and Timers

EventsManager is the internal publish-subscribe layer for runtime lifecycle changes. It also owns game-time intervals and timeouts through AbstractTimersManager.

Use events when a binder, manager, scheme, or server object needs to announce a lifecycle change without directly depending on every listener.

Event Dispatch

Events are declared in EGameEvent under src/engine/core/managers/events/events_types.ts.

Register callbacks through the manager:

getManager(EventsManager).registerCallback(EGameEvent.ACTOR_UPDATE, this.onActorUpdate, this);

Emit events through the manager or the static helper:

EventsManager.emitEvent(EGameEvent.GAME_STARTED, isNewGame);

Callbacks can be registered with a context. When context is provided, the callback is called with that context.

Event Groups

EGameEvent covers:

• actor registration, online/offline, reinit, death, item, trade, sleep, and update ticks;
• stalker and monster registration, hit, death, and interaction;
• helicopter, squad, smart terrain, smart cover, zone, and item lifecycle;
• task, treasure, surge, notification, hit, and UI menu events;
• save/load and level-change events;
• debug dump requests.

Prefer adding a specific event over overloading an unrelated existing one. Listeners should be able to infer why they were called from the event name.

Timers

EventsManager extends AbstractTimersManager.

Use:

const [cancel] = EventsManager.registerGameTimeout(callback, 1000);
const [stop] = EventsManager.registerGameInterval(callback, 500);

Intervals assert that the period is at least 50 milliseconds. Both intervals and timeouts receive the actual elapsed offset when they run.

Timers are processed by ActorBinder.update() through eventsManager.tick(). They advance on actor updates, not as independent operating-system timers.

Cleanup

Unregister callbacks in the lifecycle owner that registered them:

• managers should unregister in destroy();
• binders should reset object callbacks in offline cleanup;
• one-shot timers remove themselves after running;
• long-lived intervals should keep and call the cancel function when the owner is destroyed.

High-frequency events such as ACTOR_UPDATE should stay light. Use throttled actor update events or an interval when work does not need to run every actor tick.

Runtime Save and Load

XRF has two save paths:

• engine net-packet save/load for binders, server objects, and selected managers;
• dynamic save data stored beside the game save through marshal-backed files.

Use net-packet save/load for compact state that is part of the engine lifecycle. Use dynamic save data for flexible extension or event state that should not be constrained by packet layout.

Save Manager

SaveManager coordinates core manager save/load and engine save callbacks.

Client manager state is saved and loaded through:

• WeatherManager;
• ReleaseBodyManager;
• SurgeManager;
• PsyAntennaManager;
• SoundManager;
• StatisticsManager;
• TreasureManager;
• TaskManager;
• ActorInputManager;
• GameSettingsManager.

Server manager state currently goes through SimulationManager.

SaveManager also handles alife_storage_manager callbacks exposed from src/engine/scripts/declarations/callbacks/game.ts.

Dynamic Save Data

Before a game save, SaveManager.onBeforeGameSave(saveName):

1. emits GAME_SAVE;
2. saves extension state;
3. writes registry.dynamicData with saveDynamicGameSave.

When loading starts, SaveManager.onGameLoad(saveName):

1. loads registry.dynamicData with loadDynamicGameSave;
2. loads extension state;
3. emits GAME_LOAD.

After the engine reports successful load, SaveManager.onAfterGameLoad(saveName) emits GAME_LOADED.

Binder Save and Load

Save-relevant binders write their own state from save(packet) and read it in load(reader).

Common binder pattern:

openSaveMarker(packet, BinderClass.__name);
super.save(packet);
saveObjectLogic(this.object, packet);
closeSaveMarker(packet, BinderClass.__name);

The load path must read fields in the same order:

openLoadMarker(reader, BinderClass.__name);
super.load(reader);
loadObjectLogic(this.object, reader);
closeLoadMarker(reader, BinderClass.__name);

saveObjectLogic persists logic file names, active section, smart terrain name, activation time, active scheme save event, and portable store data. loadObjectLogic restores the matching loaded fields and portable store.

Save Markers

Save markers protect net-packet layout.

• openSaveMarker records the current packet offset.
• closeSaveMarker writes the saved block size.
• openLoadMarker records the current reader offset.
• closeLoadMarker checks that the loaded block size matches the saved block size.

The marker helpers assert when the read/write sizes drift. If a save format changes, update save and load together and adjust tests for the saved data list.

Guidelines

• Keep net-packet data compact.
• Never reorder saved fields without updating the load path.
• Save manager state through SaveManager when it is part of global runtime state.
• Save object logic through binder save/load when it belongs to one online object.
• Use dynamic save data for extension data or flexible event state.

Schemes

Schemes are script-engine behavior blocks attached to an object through its logic config. A logic section chooses the first active scheme, and each scheme section describes what the object does until a switch condition moves it to another section.

[logic]
active = walker@guard

[walker@guard]
path_walk = guard_walk
path_look = guard_look
on_info = {+alarm_started} walker@alarm

[walker@alarm]
path_walk = alarm_walk
def_state_moving = run

The scheme name is the part before the suffix. For example, walker@guard uses the walker implementation, and sr_idle@wait_for_actor uses the sr_idle implementation.

Section switching

Many active scheme sections support the same switching fields. The engine parses them from the active section and checks them in the order used by the scheme switch parser. Numbered variants such as on_info1 and on_info2 let one section define several checks of the same kind.

on_info, on_info1, …

Value shape: condlist.

When the condlist picks a target section.

on_signal, on_signal1, …

Value shape: signal | condlist.

When a waypoint or manager sets the named signal.

on_timer, on_timer1, …

Value shape: milliseconds | condlist.

After the section has been active for the given real-time duration.

on_game_timer, on_game_timer1, …

Value shape: seconds | condlist.

After the section has been active for the given game-time duration.

on_actor_inside

Value shape: condlist.

When the actor is inside the current restrictor object.

on_actor_outside

Value shape: condlist.

When the actor is outside the current restrictor object.

on_actor_in_zone

Value shape: zone | condlist.

When the actor is inside the named zone.

on_actor_not_in_zone

Value shape: zone | condlist.

When the actor is outside the named zone.

on_npc_in_zone

Value shape: story_id | zone | condlist.

When the NPC resolved by story id is inside the named zone.

on_npc_not_in_zone

Value shape: story_id | zone | condlist.

When the NPC resolved by story id is outside the named zone.

on_actor_dist_le

Value shape: distance | condlist.

When the object sees the actor and actor distance is less than or equal to the value.

on_actor_dist_le_nvis

Value shape: distance | condlist.

Same distance check, without requiring actor visibility.

on_actor_dist_ge

Value shape: distance | condlist.

When the object sees the actor and actor distance is greater than the value.

on_actor_dist_ge_nvis

Value shape: distance | condlist.

Same distance check, without requiring actor visibility.

A condlist can also set info portions or run effects while selecting the next section:

on_info = {+actor_has_key} ph_door@open %=play_sound(door_unlock)%

If the condlist returns an empty section, nil, or the current section, the switch is skipped.

nil is a special inactive target, not a registered scheme implementation. Switching helpers use it to clear active scheme state or skip activation in places where a real section would normally be expected.

Scheme families

Stalker schemes

Examples: walker, patrol, remark, animpoint, smartcover.

Human NPC movement, idle states, combat support, meetings, and scripted actions.

Monster schemes

Examples: mob_walker, mob_home, mob_remark, mob_combat.

Monster movement, territory, scripted animations, and combat hooks.

Restrictor schemes

Examples: sr_idle, sr_timer, sr_teleport, sr_particle, sr_cutscene.

Trigger volumes, timers, effects, postprocess, and actor-facing scripted events.

Physical schemes

Examples: ph_idle, ph_button, ph_door, ph_code, ph_on_hit.

Scripted behavior for physical objects and usable scene objects.

Helicopter schemes

Examples: heli_move.

Helicopter patrol, movement, targeting, and attack behavior.

Generic schemes

Examples: combat, danger, death, hit, meet, post_combat_idle, wounded.

Shared behavior that can be enabled alongside active stalker or monster logic.

Patrol names

Several schemes read patrol path fields such as path_walk and path_look. When an object is running under a smart terrain, relative path names are resolved against the smart terrain name. For example, path_walk = guard_walk in smart terrain zat_b40_smart_terrain resolves to zat_b40_smart_terrain_guard_walk.

Use full path names when the path does not belong to the active smart terrain.

Common checks

• path_walk is usually required for movement schemes.
• path_look must not be the same path as path_walk.
• Scheme sections can have suffixes, such as walker@start, walker@alarm, or sr_timer@lab_countdown.
• For timed transitions, section activation time is reset when switching to a different section.
• For switch-heavy logic, prefer sr_idle when the object should do nothing except wait for conditions.

abuse

abuse is a generic stalker scheme that makes an NPC react when the actor abuses it repeatedly. The current action reaction is a punch animation aimed at the actor.

Parameters

abuse has no scheme-specific LTX fields in the current TypeScript implementation.

Runtime values are stored in AbuseManager:

isEnabled

Default: true.

Enables or disables abuse accumulation.

abuseRate

Default: 2.

Multiplier used when abuse is added.

abuseThreshold

Default: 5.

Threshold at which the evaluator reports abuse.

abuseValue

Default: 0.

Current accumulated abuse value. It decays over time.

Runtime behavior

The scheme adds an IS_ABUSED evaluator and an abuse action to the stalker planner. The action can run only while the NPC is alive, not in danger, and not wounded. When selected, it clears desired position and direction and sets the NPC state to punch, looking at the actor.

AbuseManager.update() decays accumulated abuse over time, clamps it near the threshold, and returns whether the value is currently above the threshold.

Example

[logic]
active = walker@idle

[walker@idle]
path_walk = guard_walk
path_look = guard_look

abuse is installed as a generic stalker scheme. It is not normally selected as the active section in [logic].

Notes

• The public manager API exposes addAbuse, clearAbuse, enableAbuse, disableAbuse, and setAbuseRate.
• The page documents the current engine behavior. It does not define a separate config field for changing the abuse threshold or rate from LTX.

animpoint

animpoint moves a stalker to a registered smart cover point and plays an idle animation there. Use it for traders, quest NPCs, camp idles, and fixed scene poses where the NPC should stand, sit, or perform an ambient animation at a known point.

The scheme uses a smart cover record as its anchor. The cover position gives the animation position, and the cover angle gives the look direction.

Parameters

cover_name

Type: string. Optional. Default: $script_id$_cover.

Registered smart cover name used as the animation anchor.

use_camp

Type: boolean. Optional. Default: true.

Allows camp manager integration when the animpoint position is inside a camp zone.

reach_movement

Type: stalker state. Optional. Default: walk.

Movement state used while walking to the animpoint.

reach_distance

Type: number. Optional. Default: 0.75.

Distance threshold for reaching the animpoint. The engine stores it as squared distance.

avail_animations

Type: comma-separated strings. Optional. Default: null.

Explicit animation states to choose from. When absent, animations are selected from predicates for the smart cover description.

The section also supports common switch fields such as on_info, on_timer, and on_signal.

Usage

Use animpoint when the map has a smart cover that represents the desired pose location. The smart cover must be registered before the scheme starts, otherwise activation aborts when the manager calculates the position.

If avail_animations is not set, the engine uses the smart cover description to find compatible animation predicates. If the description has no registered predicate list, avail_animations is required.

With use_camp = true, the animpoint can register with a camp manager. Camp roles can choose director or listener animations from the approved action list.

Example

[logic]
active = animpoint@trader

[animpoint@trader]
cover_name = zat_trader_cover
use_camp = false
reach_movement = walk
reach_distance = 1.0
avail_animations = wait, wait_trade
on_info = {+zat_trader_alarm} walker@alarm

Notes

• The smart cover named by cover_name must exist in the smart cover registry.
• avail_animations is parsed as a comma-separated list.
• The planner uses one action to reach the point and another action to play the selected animation.
• The scheme is interrupted by enemy, anomaly, wounded, abuse, corpse, item, and meet states through common planner preconditions.

camper

camper makes a stalker hold a combat position, scan look points, and fire from cover. Use it for ambushes, snipers, defensive posts, and scripted combat positions.

The scheme owns a combat-camping planner action. It can block regular ALife, item gathering, corpse search, and wounded helping until close-combat camping is finished.

Parameters

path_walk

Type: string. Required. Default: none.

Patrol path used for movement between camp points. Relative names are resolved against the active smart terrain.

path_look

Type: string. Required. Default: none.

Patrol path used for look and scan points. It must not equal path_walk.

sniper

Type: boolean. Optional. Default: false.

Enables sniper scan behavior and sniper update rate.

no_retreat

Type: boolean. Optional. Default: false.

Stored in scheme state. Invalid together with sniper = true.

shoot

Type: always, none, or terminal. Optional. Default: always.

Controls when the NPC may fire at the visible enemy.

sniper_anim

Type: stalker state. Optional. Default: hide_na.

Sniper animation state stored by the scheme.

radius

Type: number. Optional. Default: 20.

Close-combat radius used by the close-combat evaluator.

def_state_moving

Type: stalker state. Optional. Default: null.

Suggested movement state.

def_state_moving_fire

Type: stalker state. Optional. Default: null.

Suggested movement-with-fire state.

def_state_campering

Type: stalker state. Optional. Default: null.

Suggested cover/scanning state.

def_state_standing

Type: stalker state. Optional. Default: def_state_campering.

Suggested standing state.

def_state_campering_fire

Type: stalker state. Optional. Default: null.

Suggested cover firing state.

scantime_free

Type: number. Optional. Default: 60000.

Time to keep scanning without enemy contact before resuming patrol movement.

attack_sound

Type: string or false. Optional. Default: fight_attack.

Sound played when firing. false disables it.

enemy_idle

Type: number. Optional. Default: 60000.

Enemy memory timeout before the action stops treating the remembered enemy as active.

The section also supports common switch fields such as on_info, on_timer, and on_signal.

Shooting modes

always

Fire whenever the enemy is visible and the action can shoot.

none

Never fire from this camper action.

terminal

Fire only from the terminal waypoint of path_walk.

Any other value aborts with a config error.

Sniper mode

With sniper = true, the action builds a scan table from flags on path_look, enables the object’s sniper update rate, and scans look points while the NPC is on a camp patrol walk point.

sniper = true cannot be combined with no_retreat = true.

Example

[logic]
active = camper@ambush

[camper@ambush]
path_walk = ambush_walk
path_look = ambush_look
sniper = true
shoot = terminal
def_state_campering = hide_na
def_state_campering_fire = hide_sniper_fire
attack_sound = fight_attack
on_info = {+ambush_done} walker@after_ambush

Notes

• path_walk and path_look are both required.
• path_look cannot be the same as path_walk.
• Danger handling can temporarily override scanning with danger-facing states.
• The implementation uses fixed internal scan constants for enemy dispersion, scan delta, and scan time delta.

combat

combat configures scripted combat style for stalker NPCs. It selects a combat type through a condlist and installs the planner hooks used by camper and zombied combat helpers.

Parameters

combat_type

Type: condlist. Optional. Default: null.

Resolves to a scripted combat type. Supported enum values in the TypeScript source are camper, zombied, and monolith.

The section also supports common switch fields. They are parsed into state.logic, although the main combat behavior is driven through planner evaluators and actions.

Runtime behavior

On activation, the scheme:

1. marks combat overrides as enabled;
2. reads combat_type;
3. defaults zombied-community NPCs to combat_type = zombied when no field is provided;
4. resolves the selected combat type with pickSectionFromCondList;
5. stores it on the object registry state as scriptCombatType.

The add method registers IS_SCRIPTED_COMBAT, changes the base combat action precondition, and installs helper actions for combat_camper and combat_zombied.

Runtime sequence

1. Activation checks whether the section exists or whether the NPC community is zombied.
2. The scheme reads common switch fields and combat_type.
3. Zombied-community NPCs get combat_type = zombied when no field is configured.
4. setCombatType resolves the condlist and stores scriptCombatType on the object registry state.
5. add registers IS_SCRIPTED_COMBAT and blocks the base COMBAT action while scripted combat is active.
6. Camper and zombied helper actions are installed into the planner.

Example

[logic]
active = walker@guard

[walker@guard]
path_walk = guard_walk
path_look = guard_look
combat_type = {+ambush_started} camper, nil

Notes

• combat is usually combined with another active movement or state scheme. It changes combat planner behavior rather than replacing movement by itself.
• The monolith value exists in the enum, but the inspected implementation only wires specific helper actions for camper and zombied combat.
• Use the combat_camper and combat_zombied pages when debugging the helper actions installed by this scheme.

combat_camper

combat_camper is an internal helper installed by the combat scheme. It makes an NPC hide, remember the last seen enemy position, and shoot only when the scripted combat type is camper.

Parameters

combat_camper has no standalone LTX fields in the current TypeScript implementation.

Enable it through combat_type on a section handled by combat:

[walker@ambush]
path_walk = ambush_walk
path_look = ambush_look
combat_type = camper

Runtime behavior

The helper adds two evaluators:

IS_COMBAT_CAMPING_ENABLED

Returns true when the object registry scriptCombatType is camper.

SEE_BEST_ENEMY

Returns true when the NPC sees its best enemy and stores the enemy position.

It also adds two actions:

SHOOT

Sets stalker state to hide_fire and looks at the best enemy.

LOOK_AROUND

Sets stalker state to hide, looks near the last seen enemy position, and periodically changes search direction.

Where it is installed

combat_camper is installed by SchemeCombat. It relies on registry.objects[object.id()].scriptCombatType being camper, which is set from combat_type = camper on the active combat-capable section.

Use it for ambush NPCs that should hold a position, hide, and shoot when they see the best enemy. Do not use it as a movement scheme; path and base activity still come from the section that activates combat behavior.

Notes

• LOOK_AROUND forgets the last seen position after 30_000 ms.
• The search direction changes after 10_000 ms initially, then every random 2_000 to 4_000 ms.
• Hit callbacks while looking around can refresh the last seen enemy position if the hit came from the best enemy.
• If an NPC never enters camper combat, check the active section’s combat_type and whether normal combat activation ran for the object.

combat_ignore

combat_ignore controls whether a stalker should accept a potential enemy while scripted logic is active. It is used for base behavior and quest scenes where combat can be ignored until conditions change.

Parameters

combat_ignore has no scheme-specific section fields in SchemeCombatIgnore.

The runtime state can receive logic overrides from the object registry. In particular, combatIgnoreKeepWhenAttacked keeps combat ignore enabled when the actor hits the NPC.

Runtime behavior

On reset, the scheme:

1. installs an enemy callback on the object;
2. subscribes CombatProcessEnemyManager;
3. enables the scheme state;
4. copies current logic overrides into the scheme state.

The enemy callback asks canObjectSelectAsEnemy. If an enemy can be selected and the NPC is assigned to a smart terrain, the manager starts the smart terrain alarm. If the actor attacked a controlled smart terrain, the terrain control is notified.

When the NPC is hit by the actor, the manager disables combat ignore unless overrides keep it active.

Runtime sequence

1. Activation creates state without reading a dedicated section.
2. add creates CombatProcessEnemyManager and stores it on the state.
3. Reset installs object.set_enemy_callback(...), subscribes the manager, enables the state, and copies overrides.
4. The enemy callback records actor combat state when the potential enemy is the actor.
5. If the enemy can be selected and the NPC belongs to a smart terrain, the terrain alarm starts.
6. Actor hits disable the state unless combatIgnoreKeepWhenAttacked is set.

Example

[logic]
active = walker@base
combat_ignore = true

[walker@base]
path_walk = base_walk
path_look = base_look

Notes

• The exact combat_ignore override syntax is parsed outside SchemeCombatIgnore; this page documents the scheme implementation that consumes the resolved override state.
• Enemy selection is rejected when the source and enemy are farther apart than the configured attack distance.
• disable clears the enemy callback and unsubscribes the stored manager action.

combat_zombied

combat_zombied is an internal helper installed by the combat scheme. It provides simplified combat actions for zombied-community stalkers: advance toward the enemy, shoot, and move toward danger sources.

Parameters

combat_zombied has no standalone LTX fields in the current TypeScript implementation.

Zombied-community NPCs receive combat_type = zombied by default when combat is activated without an explicit combat_type.

Runtime behavior

The helper adds IS_COMBAT_ZOMBIED_ENABLED. The current evaluator returns true when the object’s community is zombied.

It also adds two actions:

ZOMBIED_SHOOT

Moves toward the current enemy’s last seen position and uses raid/threat fire states depending on distance and visibility.

ZOMBIED_GO_TO_DANGER

Moves toward the best danger source, ignoring grenade movement targets and reacting to hits.

Where it is installed

combat_zombied is added by the broader combat scheme; it is not normally used as an active section in LTX. Use combat_type = zombied for intent, but also keep the NPC community as zombied because the evaluator checks community.

This helper is useful for simple zombie-style combat where the NPC should keep pressure on the enemy and react to danger without cover or camper behavior.

Example

[logic]
active = walker@zombie

[walker@zombie]
path_walk = zombie_walk
path_look = zombie_look
combat_type = zombied

Notes

• SchemeCombat parses the zombied combat type, but the inspected combat_zombied evaluator itself checks the NPC community. Use zombied community data when relying on this behavior.
• ZOMBIED_SHOOT may play fight_attack on activation with a 25 percent chance.
• Use combat_camper or the normal combat flow when the NPC should use cover-like hide/look behavior instead.

companion

companion makes a stalker follow and assist the actor. The current implementation uses a simple walking behavior and planner action rather than a large LTX parameter set.

Parameters

companion has no scheme-specific LTX fields.

The section supports common switch fields. They are parsed into state.logic.

Runtime behavior

On activation, the scheme sets behavior = 0, which corresponds to the simple walk behavior in ActionCompanionActivity.

The scheme adds EActionId.COMPANION_ACTIVITY to the state planner. It is a stalker scheme, so it expects a stalker object with a planner and normal movement access.

The action runs when the NPC is alive, has no enemy, and the companion section is active. It:

• clears desired position and direction;
• enables talk;
• picks an accessible assist point near the actor;
• moves to that point using level path movement;
• chooses raid, rush, or assault state based on distance;
• switches to threat while standing near the assist point and looking at the actor.

Example

[logic]
active = companion@follow

[companion@follow]
on_info = {+companion_stop} walker@wait

Notes

• The source defines additional behavior constants for near/ignore/wait modes, but the current activation code always sets simple walking behavior.
• The assist position is chosen to the side of the actor and must be accessible to the NPC.
• Combat or death interrupts the action because the evaluator requires the NPC to be alive and without an enemy.
• Use common switch fields on the companion section to exit follow behavior when quest state changes.

corpse_detection

corpse_detection is a generic stalker scheme for finding nearby lootable corpses. It adds planner logic that sends an NPC to a corpse within the configured search radius and plays the corpse-search state.

Parameters

corpse_detection_enabled

Type: boolean. Optional. Default: true.

Enables or disables corpse detection for the current reset section.

Runtime behavior

The scheme adds IS_CORPSE_EXISTING and a SEARCH_CORPSE action. The evaluator returns true only when the NPC is alive, has no enemy, is not in danger, is not zombied, is not wounded, is not the cinematic actor visual, and a nearby lootable corpse exists within 20 meters.

When a corpse is selected, the evaluator stores the selected corpse id, vertex id, and position in scheme state and marks the corpse in portable storage so another NPC does not select the same corpse. The action sends the NPC to the corpse, switches to search_corpse near the target, and plays corpse_loot_begin once.

The finishCorpseLooting helper transfers items from the selected corpse to the looting NPC when the corpse object is online. It then plays either corpse_loot_good or corpse_loot_bad; empty transfers use the bad-loot sound.

Example

[logic]
active = walker@camp

[walker@camp]
path_walk = camp_walk
path_look = camp_look
corpse_detection_enabled = false

Notes

• corpse_detection is generic stalker behavior. It is usually controlled from the active logic section, not selected as [logic] active.
• Finalizing the search action frees the selected corpse marker.

cover