X-Ray Forge

X-Ray Forge (XRF) is a collection of development projects for X-Ray 16 engine. It provides a TypeScript scripting layer and the tooling around it for building, testing, and maintaining mods.

What XRF includes

• A TypeScript rewrite of the OpenXRay scripting layer, compiled to Lua.
• Build-time tools for scripts, configs, UI forms, translations, and resources.
• A TypeScript SDK for the OpenXRay engine API.
• The XRF CLI for building projects and working with a local game installation.
• XRF Tools: a command-line toolset and a desktop development application.
• This book and the SDK API reference.

Start here

• Setting up or building an XRF project? Read Installation, then Building.
• Writing or changing scripts? Start with the Game scripting and Schemes.
• Looking for a command? See the XRF CLI or XRF Tools CLI.
• Working with game-data files? See XRF Tools.
• Investigating runtime behavior? Read X-Ray engine and Debugging.

Repositories

Core development

• XRF engine — TypeScript scripting layer, build pipeline, and CLI.
• X-Ray 16 TypeScript SDK — TypeScript API for OpenXRay.
• XRF tools — command-line tools and desktop application.
• XRF tools end-to-end tests — end-to-end tests for the XRF Tools CLI.
• XRF book — this documentation.

Distribution

• XRF binaries — packaged engine and tool binaries.

Resource packs

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

Installation

This guide prepares a local xrf-engine checkout, connects it to an installed game, and starts XRF.

Requirements

• Windows.
• Node.js and npm.
• Git with submodule support.
• An installed copy of S.T.A.L.K.E.R.: Call of Pripyat.

The CLI looks for Steam app 41700. For a non-Steam installation, set targets.stalker_game_fallback_path in cli/config.json.

Set up the project

Clone the engine repository and install dependencies:

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

npm run setup initializes the src/resources and cli/bin submodules used for assets, engines, and tools.

Verify and link the game

Run the project verification before linking:

npm run verify

Create development links for the game folder, target/gamedata, and logs:

npm run cli -- link

List the bundled engines and select one:

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

engine rollback restores the original game executable.

Build and start

Build the gamedata output:

npm run build

Start the configured game executable:

npm run cli -- start_game

For faster testing, the start command can create or load a session directly:

npm run cli -- start_game --new --no-intro
npm run cli -- start_game --load quicksave

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

Update submodules

Update submodules when resource or binary repositories change:

git submodule update --init --recursive

Use a local OpenXRay build

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 implementation of the Call of Pripyat script layer. The build compiles it to Lua and assembles configs, UI XML, translations, and static resources into target/gamedata.

The engine repository also includes a local Node 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

Edit source files, then build. target/ is generated output; do not edit it by hand.

Building

Build XRF into target/gamedata before testing, linking, or packaging.

npm run build
npm run cli -- build

Targets

build runs every target by default:

• scripts
• externs
• 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 --include externs
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 <patterns...>: regular-expression filters for source paths.
• -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.

--filter requires an explicit --include; it cannot be used with the default all-target build.

What a full build does

When all targets run, the build performs these steps:

1. optionally clean target/gamedata;
2. compile TypeScript scripts to Lua;
3. generate the extern manifest and copy it to target/gamedata/extern.json;
4. render dynamic UI forms and copy static UI XML;
5. render dynamic configs and copy static LTX/XML configs;
6. build translations;
7. copy static resources;
8. write metadata.json;
9. 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 externs
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 target/gamedata, target/gamedata/metadata.json, target/gamedata/extern.json, and target/xrf_build.log. Change source files and rebuild rather than editing generated output.

Build Clean

build --clean removes the previous target/gamedata tree, then runs the selected targets.

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

It never changes src/engine, src/resources, or configured 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 the selected step deterministically overwrites the file you changed.

Building Scripts

The scripts target compiles entry points in src/engine/scripts and their imports 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 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 and supporting Lua typedefs come from the xray16 package. Supporting typedefs are installed under node_modules/xray16/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 the extern manifest

Build externs after changing an extern(...) declaration or its JSDoc.

npm run cli -- build --include externs

Output

• src/engine/declarations/extern.json — tracked contract.
• target/gamedata/extern.json — packaged sidecar for gamedata tools.

The game does not load either file. Do not edit them by hand. Manifest source paths are relative to the declarations root.

Check the tracked manifest

npm run cli -- verify externs

This compares declarations with the tracked manifest without writing. Regenerate when it reports drift.

Requirements

Missing or unrenderable callable types are emitted as unknown. Values need value as Type. The build fails for duplicates, dynamic names, and unsupported declaration shapes.

Building UI

The UI target writes game UI XML to target/gamedata/configs/ui 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 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

Build configs into target/gamedata/configs from src/engine/configs.

The target processes:

• 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 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.

Source types

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 configs use JSX and renderJsxToXmlText. UI XML is separate: it is built from src/engine/forms.

Validation

Use the LTX verifier after config changes:

npm run cli -- verify ltx

Building Translations

The translations target writes game string tables to target/gamedata/configs/text from src/engine/translations through the bundled XRF tools binary.

Build 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.

Sources

XRF uses JSON translation sources for generated multilingual output. Check them with npm run cli -- verify translations; see Translations.

Building Resources

The resources 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 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.

Incremental builds

Directory resources are compared before copy. Non-clean builds skip unchanged files.

Additional Assets

Clone configured resource repositories with:

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

The relevant configuration keys 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 engine repository includes a local Node CLI. Run it 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

Package scripts

Run package scripts from the repository root with npm run <script>:

• 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 with the full repository rule set.
• test: run Jest.
• test:coverage: run Jest coverage.
• format: rewrite Markdown, TypeScript, and LTX files using the configured formatters.
• help: print CLI help.

Commands

The CLI builds and packages the project, manages resources and engine binaries, links a local game, and handles common format, spawn, particle, and verification tasks. Each command has its own page:

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

Paths 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.

Installed command

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, the equivalent 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. See CLI Configuration.

CLI Configuration

The engine CLI reads project 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.

Game path

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

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

target/gamedata/extern.json is metadata for gamedata tools; the game runtime does not load it. The build also writes target/gamedata/metadata.json and stores the build log in target/xrf_build.log.

Options

• -i, --include <targets...>: build only selected targets. Choices are scripts, externs, 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 externs
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 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 xrf-cli pack-archive. 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 packing 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.

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 checks. The default command applies the full repository rule set, including unused import and local variable checks.

npm run lint

Commands

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

Examples

npm run lint
npm run lint -- --fix

Inputs and output

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

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

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 xrf-cli externs export when checking the script declaration surface exposed by conditions, effects, and dialogs.

Failure notes

dir_as_json requires a path argument.

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 spawn unpack.

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.

Sprites

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

npm run cli -- sprites <command>

Commands

Options

All sprite 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 -- sprites unpack-equipment
npm run cli -- sprites pack-equipment --strict
npm run cli -- sprites unpack-description --description ui_actor.xml
npm run cli -- sprites pack-description --description ui_actor.xml

Workflow

Unpack before editing a sprite’s icons 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 sprite. 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.

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.

Verify

verify validates project setup and generated data.

npm run cli -- verify <command>

npm run verify runs verify project.

Commands

Options

• verify gamedata -c, --checks <checks...>: run only the listed checks instead of all of them.
• verify gamedata -r, --report <report>: write the structured verification report as JSON.
• verify gamedata -v, --verbose: print verbose external-tool logs.
• verify gamedata -s, --strict: fully validate expensive asset payloads, including complete sound decoding.
• verify ltx -v, --verbose: print verbose external-tool logs.
• Particle verification commands support -v, --verbose.
• verify translations -l, --language <locale>: check one locale instead of all of them.
• verify translations -s, --strict: fail on missing entries instead of only listing them.
• verify translations -v, --verbose: print verbose external-tool logs.

Selecting checks

A full run validates everything and is slow. When iterating on one kind of asset, narrow it:

npm run cli -- verify gamedata --checks meshes weapons animations

Available checks: animations, levels, ltx, meshes, particles, particles-usage, scripts, shaders, sounds, spawns, textures, weapons, weathers. Unknown names are rejected before the tool runs.

Structured report

--report writes the findings as JSON instead of leaving them only in the log. Because the format is stable, a report from a known-good build can be kept as a baseline and later runs compared against it, which is more reliable than reading console output when a change is expected to alter some findings but not others.

npm run cli -- verify gamedata --checks weapons --report target/verify-weapons.json

Examples

npm run cli -- verify externs
npm run cli -- verify gamedata --verbose
npm run cli -- verify translations --language ukr --strict

Build gamedata before verify gamedata. verify externs does not write files. Regenerate a stale manifest with npm run cli -- build --include externs.

Failure notes

verify project reports setup problems without failing. Other checks fail on invalid data or tool errors. verify translations reads src/engine/translations, not built gamedata, and only fails with --strict.

Extensions

Extensions are optional modules discovered in gamedata/extensions. They keep gameplay changes separate from the core script layer.

At game startup, XRF scans folders containing main.script, restores their saved order and enabled state, and registers enabled modules.

Extension Entry Point

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

An extension module can export:

• register(isNewGame, extension): called when the extension is enabled; this is required for a usable module.
• 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.

State and ordering

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 can reorder extensions and toggle those that opt in with canToggle.

Built-In Extensions

The current engine source includes these extension folders:

The built-in modules are useful references when adding an 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.

Scope

XRF supports discovery, ordering, enablement, registry registration, and save/load hooks. It does not currently define extension dependencies, packaging metadata, or extension-specific build steps.

Achievement Rewards

Achievement rewards periodically fills two actor reward boxes after the relevant achievements are earned.

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.

Behavior

On registration, the extension subscribes to EGameEvent.ACTOR_UPDATE.

Each actor update checks 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.

Saved 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.

Tuning

• 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) can add random upgrades to weapons, outfits, and helmets when they first go online.

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.

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.

Saved 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 a smart terrain to be visited before it appears on the map or can be selected as a same-level travel target.

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.

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.

Saved 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 uses a treasure’s type to choose its map icon.

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.

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.

Saved 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 initial vertex and position for a new game.

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.

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.

Saved 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

xrf-tools is the XRF companion workspace. It contains reusable Rust format 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.

Choose 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 application itself is the authority on what each tool currently supports.

Implementation source

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

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

Tools Application

The XRF tools application is a Tauri desktop app with a Rust backend and a React UI. Use it for interactive inspection and one-off data operations; use the Tools CLI when the task must be repeatable, scripted, or run in CI.

It groups its work into editors for archives, configs, dialogs, script exports, equipment icons, spawns, and translations. Which screens and actions each one currently offers changes with the application, so the application is the authority on that, not this book. Some routes are read-only or prototype workflows, and several write files — packing, unpacking, formatting, and saving spawn data all overwrite their targets.

Keep a backup before writing over game data.

Source

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

Tools CLI

The Rust xrf-cli binary inspects, converts, packs, and verifies X-Ray assets. Use it directly for asset workflows and automation; the engine repository’s npm run cli -- ... wrapper exposes selected operations.

Commands have a group and an operation. To inspect a command’s accepted arguments:

xrf-cli archive pack --help

Examples in this chapter assume xrf-cli is on PATH. Relative paths resolve from the current directory; each workflow identifies its input layout. Output blocks show demo runs; paths, counts, and timings depend on the input and machine.

Command groups

Reporting

--silent conflicts with --verbose; --json conflicts with --report. Rust logging also honors RUST_LOG.

Prefer a report file for large verification runs. Capture the exit code immediately after the command, then read the fields needed for the decision. From a project containing target/gamedata:

xrf-cli gamedata verify ./target/gamedata --report ./verification-report.json 2>$null
$verificationExit = $LASTEXITCODE
$report = Get-Content ./verification-report.json -Raw | ConvertFrom-Json
$report.result.status
$verificationExit

Use --json when a consumer needs a stdout pipe. Neither report mode limits the number of findings.

The report is an envelope around a command-specific result:

A failed check still reports its findings. Argument parsing failures occur before command execution and do not produce an envelope. If writing the report fails, the process exits 1; an existing report at that path may belong to an earlier run. Check the process result and report freshness before using a saved answer.

Keep build and execution when comparing reports: different binaries or worker counts can explain different results and timings.

Execution

Commands that support parallel work accept -j, --jobs:

xrf-cli gamedata verify ./target/gamedata -j 50%

Commands without parallel work do not accept --jobs.

Exit codes

A command’s --strict behavior is specific to that command. Consult its guide before treating every strict failure as exit 3; refused writes and execution errors still use exit 1.

Command reference

Each group page combines authored workflow guidance with reference generated from the command definitions. Correct option descriptions in the source command, then follow the reference-generation workflow.

Archive CLI

Archive commands package gamedata into X-Ray .db or .xdb volumes, inspect their contents, and extract or verify stored files. Use pack for a full distribution and pack-patch for added or modified files relative to an installation.

Packing examples run from a project containing target/gamedata. Inspection and unpacking examples use a db directory in the current working directory. Source paths and output destinations are separate.

Pack an archive

Pack the assembled tree, then verify the written volumes:

xrf-cli archive pack target\gamedata --dest target\db --name gamedata
xrf-cli archive verify --path target\db

Example output excerpt — pack an archive:

Packed 29 file(s) into 1 volume(s) in 23 ms
Phases: 10 ms collecting, 13 ms writing, 0 ms finalizing
Summary: 14 compressed, 15 stored, 0 aliased, 0 skipped
Size: 2.37 MB source, 2.37 MB written
Speed: 103 MB/s

Exit code: 0.

The command compresses file types the engine normally compresses and stores the rest. It writes one volume as gamedata.db; when the archive needs more than one volume, it writes gamedata.db0, gamedata.db1, and so on.

By default, a volume can be up to 1900 MB and receives a header that mounts its contents at $fs_root$\gamedata\. That is the usual setting for a gamedata archive. To add or change one entry, name it:

xrf-cli archive pack target\gamedata --dest target\db --name gamedata `
  --header 'creator="Modder"' --header 'link="www.moddb.com/mods/my-mod"'

Each --header value is key=value, merged over the default header, so naming creator keeps auto_load and entry_point. level_name, level_ver, creator, and link are the entries mod templates conventionally carry; they are yours to set and the engine ignores them.

The engine requires auto_load and entry_point; a volume missing either can stop the game on load. Packing validates the effective header before writing, including values supplied through a configuration file.

Choose what to pack

Without selection options, the command packs the whole source directory. Use a configuration file when the selection is shared or checked in; use command-line options for a one-off build. They cannot be combined.

An .ltx configuration uses the xrCompress dialect:

[options]
exclude_exts = *.txt,*.json

[include_folders]
configs = true
scripts = true

[include_files]
gamemtl.xr

[header]
auto_load = true
entry_point = $fs_root$\gamedata\

xrf-cli archive pack target\gamedata --dest target\db --name gamedata --config pack.ltx

In [include_folders] and [exclude_folders], true applies to the directory and everything below it; false applies only to the named directory. Use .\ for the packed root. An .ltx or .json configuration may contain selection rules and a header only. Source path, destination, volume name, and run options remain on the command line.

A JSON configuration for the same selection looks like this:

{
  "excludeExtensions": ["*.txt", "*.json"],
  "includeFiles": ["gamemtl.xr"],
  "includeDirectories": [
    { "path": "configs", "isRecursive": true },
    { "path": "scripts", "isRecursive": true }
  ],
  "header": [
    { "key": "auto_load", "value": "true" },
    { "key": "entry_point", "value": "$fs_root$\\gamedata\\" }
  ]
}

xrf-cli archive pack target\gamedata --dest target\db --name gamedata --config pack.json

For a direct selection, repeat the relevant option:

xrf-cli archive pack target\gamedata --dest target\db --name configs `
  --include-directory configs --include-directory spawns --include-file gamemtl.xr `
  --exclude-extension '*.txt'

--include-directory-shallow includes a directory’s files but not the files in its child directories. --exclude-directory-shallow excludes the named directory only; its contents can still be packed. All paths are relative to the source.

Common packing options

• Use --store to store every file without compression.
• Use --max-size <MB> to choose a volume cap from 1 through 1900 MB. --oversized-volumes permits a larger cap only for an engine fork that supports it.
• Use --xdb to create .xdb volumes.
• Use --no-skip-list to retain editor and source leftovers that the normal engine-build skip list excludes.
• Use --verbose to see every selected, skipped, stored, compressed, and deduplicated file while packing.

Performance compared with xrCompress

These are median results from interleaved runs of both tools on the same machine and source tree. xrCompress -fast uses the compression mode that matches archive pack; the xrCompress default trades time for a smaller archive. Each time/RAM value is wall-clock seconds and peak resident memory in megabytes.

For inputs that contain compressible files, these are the resulting archive sizes:

In these comparisons, archives packed from the same source by either tool unpacked to byte-identical files.

Replace an existing archive

Packing refuses to overwrite volumes with the same name. Add --force only when replacing that set is intended:

xrf-cli archive pack target\gamedata --dest target\db --name gamedata --force

--force replaces volumes as it writes and cannot restore the previous set after a partial failure. It also does not prune higher-numbered volumes left by a larger previous build. Prefer a fresh output directory, verify its complete set, then replace the old distribution. A non-forced failed run removes the volumes it created.

Build a patch

archive pack-patch creates .db volumes containing added and modified files. To package edits from a game’s loose gamedata\, point at the installation:

xrf-cli archive pack-patch 'C:\Games\Anomaly' --dest target\patch --name mypatch

Without --target, the command compares the installation’s archives with its loose files. Unchanged copies are omitted, and archived files absent from gamedata\ remain untouched. The installation must contain archives and loose files to compare.

Write outside the input and target trees; destinations inside either are refused. Copy the resulting volumes to a directory mounted after the base archives in fsgame.ltx, usually db\patches\.

Loose files in the player’s gamedata\ take priority over patch archives. Distribute loose replacements when those files need updating.

A patch cannot remove a base file: archive registration can replace an entry but has no deletion marker. Removing content requires replacing or removing it from the installed base distribution.

Deliver a tree of your own

Use --target to deliver files from a separate folder:

xrf-cli archive pack-patch 'C:\Games\Anomaly' --target C:\work\mymod\gamedata `
  --dest target\patch --name mypatch

For a loose target, name the gamedata directory itself, with paths such as configs\ and textures\ directly inside it. Naming its parent adds an unwanted gamedata\ prefix to archive entries.

Preview before writing

Use --dry-run to compare without writing volumes. Add --report to save every changed entry:

xrf-cli archive pack-patch 'C:\Games\Anomaly' --dry-run --report patch-preview.json

The size shown is the total unpacked payload; the final archive size is known only after writing.

• --include configs limits both sides to a logical prefix.
• --ignore configs\debug excludes a prefix, even when included.
• --exclude-extension '*.txt' excludes matching file extensions.
• --verify-payload reads and compares both payloads when their sizes and checksums match.

The three filter options are repeatable.

Inspect or extract files

For info, list, find, extract, and verify, --path may name one volume or a directory. A volume reads only that file; a directory reads all .db and .xdb volumes below it as one merged archive set.

# Check the number of volumes, entries, and their sizes.
xrf-cli archive info --path .\db

# List file paths, or search their names without unpacking.
xrf-cli archive list --path .\db --files
xrf-cli archive find --path .\db --query wpn_ak74 --files

# Extract one logical file, or an entire logical directory.
xrf-cli archive extract --path .\db --file textures\wpn\wpn_ak74.dds --dest .\ak74.dds
xrf-cli archive extract --path .\db --directory configs --dest .\extracted-configs

list --verbose and find --verbose show a file’s sizes and source volume. If identical files share one stored payload, they also name the other paths that read those bytes.

Unpack an archive

Unpack a complete volume set by giving its containing directory:

xrf-cli archive unpack --path .\db --dest .\unpacked

The archive’s mount prefix is retained beneath the destination. An archive packed with the default gamedata header therefore writes files under unpacked/gamedata, rather than directly under unpacked.

To unpack one volume by itself, pass the volume path instead. --dry opens the archive and prints its summary without writing files. Use -j to control the worker count, for example -j 8 or -j 50%.

xrf-cli archive unpack --path .\db\configs.db --dest .\unpacked\configs --dry

Use a new or empty destination directory. Existing files can otherwise be replaced while the archive is unpacked.

Unpacking speed and memory

These results use the same measurement method. The default run uses the available worker count; -j 1 is the single-worker comparison.

Verify an archive

Verify every file after packing or copying an archive:

xrf-cli archive verify --path .\db

Example output — verify an archive:

Verified 29 file(s) in 29 ms

Exit code: 0.

The command reads every payload, checks decompression, and validates its CRC. It reports damaged files as failures; use --report archive-verify.json to save the findings. Successful archive verification establishes payload integrity; run gamedata verification to check the files’ formats and references in their installed context.

Command reference

xrf-cli archive extract

Extract one archive file or directory without unpacking the complete set

xrf-cli archive extract [OPTIONS] --path <path> --dest <dest>

xrf-cli archive find

Find archive entries whose logical path contains text

xrf-cli archive find [OPTIONS] --path <path> --query <query>

xrf-cli archive info

Describe an X-Ray archive volume or volume set

xrf-cli archive info [OPTIONS] --path <path>

xrf-cli archive list

List the merged entries in an X-Ray archive volume or volume set

xrf-cli archive list [OPTIONS] --path <path>

xrf-cli archive pack

Command to pack provided directory into *.db archive volumes

xrf-cli archive pack [OPTIONS] <SOURCE>

xrf-cli archive pack-patch

Command to pack what a gamedata tree changes about an installation into overriding *.db archive volumes

xrf-cli archive pack-patch [OPTIONS] <SOURCE>

xrf-cli archive unpack

Command to unpack provided *.db into separate files

xrf-cli archive unpack [OPTIONS] --path <path>

xrf-cli archive verify

Read every archive payload and verify decompression and CRC checks

xrf-cli archive verify [OPTIONS] --path <path>

DDS CLI

DDS commands inspect textures, crop regions, convert image formats, and generate X-Ray bump maps. Use sprite commands when a config or XML description defines a whole sheet, and THM commands to change a texture’s bump declaration.

Examples use paths relative to a gamedata or texture-working directory. Output commands write the named files; choose separate output paths when keeping the originals.

DDS inspection

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

Example output — inspect a DDS sheet:

Read dds file ./gamedata/textures/ui/ui_test_sheet.dds
File size: 16512 (16.1 KB)
Metadata size: 128
Data size: 16384 (16 KB)
Size: 256 x 64
Mipmap: 1 - 16
Linear size: 16384
Block size: 16
D3D format: DXT5

Exit code: 0.

The report includes dimensions, mipmaps, file and pixel-data sizes, compression, block size, bits per pixel, and known FourCC or D3D/DXGI formats. Pitch or linear size is included when present. Inspect these fields before selecting an output format or diagnosing a texture that the renderer cannot load.

Region cropping

Crop a single icon when its source sheet has no compatible inventory config:

xrf-cli dds crop --source ./textures/ui/ui_icon_equipment.dds --output ./wpn_ak74.png `
  --x 1000 --y 0 --width 250 --height 100

Example output — crop a region:

Wrote 16x16 region from 0:0 of ./gamedata/textures/ui/ui_test_sheet.dds to ./height.png

Exit code: 0.

Coordinates and dimensions are pixels, measured from the top left. The source must contain the entire rectangle; out-of-bounds regions are rejected.

A .png output preserves the decoded pixels without another lossy encode. Any other output extension selects BC3 DDS. Prefer PNG for subsequent packing; sprite pack-equipment selects <section>.png before <section>.dds.

Fitting into different bounds

Supply both fit dimensions to resize the crop into a fixed output rectangle:

xrf-cli dds crop --source ./ui_actor_weapons.dds --output ./upgrade_ak74.png --x 0 --y 400 `
  --width 300 --height 100 --fit-width 295 --fit-height 110

Fitting preserves aspect ratio and centers the image on a transparent canvas. A crop already matching the requested bounds is unchanged. Equipment packing uses the same fitting behavior; description packing instead requires exact dimensions, so fit those icons before packing.

Convert a texture

Re-encode an existing DDS texture in an explicit format:

xrf-cli dds convert ./source.dds ./texture.dds --format bc3
xrf-cli dds info --path ./texture.dds

Example output — convert a DDS texture:

Converted ./gamedata/textures/ui/ui_test_sheet.dds to ./converted.dds as BC3 (DXT5), 9 levels, 22032 bytes

Exit code: 0.

Accepted formats are bc1, bc2, bc3, bc7, and rgba8. Choose a format supported by the target renderer and appropriate for the texture’s alpha and quality requirements.

Conversion decodes the base image and rebuilds its mip chain. Use --no-mipmaps to write only the base level. --mip-filter selects the reduction filter, defaulting to kaiser; --quality trades encoding time for fidelity, defaulting to slow.

Add --compare to encode the other formats in memory and report their size and distortion alongside the selected format. Only the selected format is written. Review the resulting texture visually as well as inspecting its metadata; numerical error alone does not establish acceptable appearance.

Generate a bump pair

From a working directory containing a height image, generate the two DDS files used by an X-Ray bumped surface:

xrf-cli dds make-bump ./height.png ./textures/tile/wall --gloss-constant 0.5

Example output — generate a bump pair:

Generated .\wall_bump.dds and .\wall_bump#.dds from ./height.png

Exit code: 0.

The destination is a base path without an extension or _bump suffix. This example writes textures/tile/wall_bump.dds and textures/tile/wall_bump#.dds.

Height is averaged across the input’s color channels. Supply --gloss for a gloss-mask image instead of a constant between 0 and 1. An optional --normal-map supplies normals instead of deriving them from height; its dimensions must match the height image. --virtual-height controls relief depth, defaulting to 0.05.

Bump generation uses the box mip filter by default. A warning about very dark gloss indicates little specular response; the files are still written because a matte surface may be intentional.

Bump declarations

Generating or moving a bump texture does not update its descriptor. Follow the THM bump-declaration workflow to connect an existing descriptor to the new path, then verify the assembled texture set.

Command reference

xrf-cli dds convert

Command to re-encode a dds file into another format, with its mip chain rebuilt

xrf-cli dds convert [OPTIONS] --format <format> <SOURCE> <DESTINATION>

xrf-cli dds crop

Command to crop a rectangular region out of a dds file into a new dds file

xrf-cli dds crop [OPTIONS] --source <source> --output <output> --x <x> --y <y> --width <width> --height <height>

xrf-cli dds info

Command to print information about provided dds file

xrf-cli dds info [OPTIONS] --path <path>

xrf-cli dds make-bump

Command to generate the _bump and _bump# pair a bumped surface binds, from a height map

xrf-cli dds make-bump [OPTIONS] <HEIGHT> <DESTINATION>

Dialog CLI

dialog info checks dialog XML structure and summarizes the dialog graph. Use it after changing phrases or links, or to inspect an imported dialog set. See dialog configuration for authoring rules.

Inspect a dialog set

From a project containing an assembled gamedata directory:

xrf-cli dialog info --path ./gamedata --source directory --strict --report ./dialog-report.json

Example output excerpt — inspect dialogs:

Reading dialogs in ./gamedata (Directory)
Swept 2 files in 7 ms, 0 unreadable, 0 archived
Dialogs: 4 total, 1 with no phrases, 1 with a priority
Phrases: 8 total, 5 links, 3 final, 2 without text, 0 outside a phrase list
Largest dialog: zat_test_trader_start with 4 phrases
Encodings: UTF-8: 1, windows-1251: 1
Dialog elements: dont_has_info: 1, has_info: 1, init_func: 1, precondition: 1

Exit code: 0. The summary ends with “Read 2 files, status: failed”. Exit 0 records a completed inspection; add –strict to fail on its finding.

--source directory selects the loose tree explicitly. The default, containing-installation, can discover the game installation around the supplied path. Repeat --path for layered roots, with the highest-priority root first; --prefix narrows the virtual path scope.

The summary covers files, dialogs, phrases, and links, including empty dialogs, final phrases, missing text, and phrases outside a phrase list. Use --verbose for individual findings or inspect result in the saved report.

Interpret the result

Without --strict, completed inspection can return exit 0 even when it finds invalid dialogs. With --strict, those findings produce exit 3. An error, incomplete inspection, or skipped input produces exit 1, including when no dialog files were selected.

These checks establish structural consistency. Review the conversation in game to verify its conditions, scripting, and intended flow.

Command reference

xrf-cli dialog info

Command to read dialog xml and report what it holds

xrf-cli dialog info [OPTIONS] --path <path>...

Docs CLI

docs generate creates Markdown reference pages from the CLI’s command definitions. Use it to publish command names, arguments, defaults, and help text without maintaining a second option catalog.

Generate standalone reference

Run from a directory where ./cli-reference can hold generated files exclusively. Generation replaces expected pages and removes unexpected top-level .md files in that directory.

xrf-cli docs generate --output ./cli-reference
xrf-cli docs generate --output ./cli-reference --check

Example output — generate command reference:

Generated 16 documentation pages in ./cli-reference

Exit code: 0.

The first command writes an index and group pages. The second performs a read-only comparison against what the current binary would generate: exit 0 means they match, and exit 3 means a page is missing, outdated, or unexpected. Comparison normalizes CRLF to LF.

Use the same binary for generation and checking. A previously built binary may describe older commands than the source checkout beside it.

Update the book reference

Run from the xrf-book repository with xrf-tools checked out beside it:

npm run cli:reference
npm run format

The first command regenerates src/tools/cli/reference/ from the sibling tools repository; the second applies book formatting. Authored group pages include generated command sections from that directory.

Edit command definitions to correct reference text. Keep workflow explanations in the authored pages outside reference/. Do not use docs generate --check against the book’s formatted output: formatting changes the generated text beyond the line-ending normalization that the check accepts.

Command reference

xrf-cli docs generate

Command to generate markdown reference for all CLI commands

xrf-cli docs generate [OPTIONS] --output <output>

Gamedata CLI

Gamedata commands verify assembled assets and show which files a game installation resolves. Run verification after a build or asset import, before launching or packaging the result.

gamedata verify

From a project containing target/gamedata:

xrf-cli gamedata verify ./target/gamedata --report ./verification-report.json

Example output excerpt — verify textures:

Verify textures:
Verified gamedata textures in 6 ms, 3/3 textures valid; 0/0 declared bumps resolved

Project gamedata is valid
Gamedata project verified in 9 ms

Exit code: 0.

The positional root must be an existing gamedata directory or an installation declaring its mounted sources. The resolved tree must contain configs/system.ltx; it may come from a loose file or an archive.

All asset checks run unless --checks selects a subset. Add --strict to fully validate expensive payloads and apply the checks’ stricter content requirements:

xrf-cli gamedata verify ./target/gamedata --checks scripts,ltx
xrf-cli gamedata verify ./target/gamedata --checks sounds --strict

--jobs controls parallel work; -j 1 makes execution sequential. Worker count should not change the findings for unchanged input, but durations, cache statistics, and execution metadata can differ.

By default the run ignores .git, .idea, particles_unpacked, textures_unpacked, .gitignore, .gitattributes, README.md, and LICENSE. Supplying --ignore replaces this list; include every exclusion the run still needs.

Patched installations

For Anomaly and Monolith-based installations, enable the DLTX dialect:

xrf-cli gamedata verify "C:/Games/Anomaly" --dltx --report ./anomaly-report.json

Checks then resolve patched config values. Leave --dltx off for standard vanilla or OpenXRay LTX trees.

Inspect resolved assets

Use gamedata list to locate a winning file and inspect files hidden by higher-priority mounts:

xrf-cli gamedata list --path "C:/Games/Anomaly" --prefix textures --shadowed `
  --report ./asset-list.json

Example output — list textures:

Listing ./gamedata
  Directory ./gamedata (gamedata)
  textures\act_cat_bump.thm [./gamedata]
  textures\prop_lampa_g.dds [./gamedata]
  textures\ui\ui_test_sheet.dds [./gamedata]
  textures\ui_empty.dds [./gamedata]
4 asset(s) across 1 mount(s) in 1 ms

Exit code: 0.

The default source mode searches for a containing installation. Use --source directory to inspect only a loose tree, or --loose to omit archived entries. Repeat --path to layer roots, highest priority first.

Console output shows at most 40 entries per section; the report retains the full list. Review skipped-source warnings as well as the winning paths: a successfully produced listing may still be incomplete.

Checks and rules

Select checks by their group names: animations, levels, ltx, meshes, particles, particles-usage, scripts, shaders, sounds, spawns, textures, weapons, and weathers.

Findings carry a stable rule identifier. These groups expose the following rules:

• Animations: animations.hud-item, animations.motion-collision, animations.player-hud.
• Levels: levels.ai-guid, levels.ai-node-count, levels.ai-version, levels.cform-version, levels.details-pair, levels.file-empty, levels.file-truncated, levels.graph-duplicate, levels.graph-guid, levels.header-version, levels.level-guid, levels.ltx-read, levels.map-texture, levels.missing-bundle, levels.missing-file, levels.orphan-bundle, levels.roster-conflict, levels.shader-reference, levels.shaders-chunk, levels.texture-reference, levels.undeclared-map.
• LTX: ltx.formatting, ltx.schema, ltx.verification.
• Meshes: meshes.chunk-residue, meshes.motion-label, meshes.motion-read, meshes.motion-validation, meshes.path, meshes.read, meshes.shader-library, meshes.validation.
• Particles: particles.library, particles.texture.
• Particle usage: particles-usage.reference, particles-usage.spawn, particles-usage.spawn-custom-data.
• Scripts: scripts.path, scripts.read, scripts.syntax. Syntax checks use the LuaJIT dialect.
• Shaders: shaders.include-cycle, shaders.include-missing, shaders.include-syntax, shaders.lua-syntax, shaders.renderer-root, shaders.source-invalid, shaders.source-read.
• Sounds: sounds.files, sounds.references.
• Spawns: spawns.path, spawns.read.
• Textures: textures.bump, textures.bump-companion, textures.bump-declaration, textures.path, textures.read, textures.dds.
• Weapons: weapons.validation.
• Weathers: weathers.definitions, weathers.files, weathers.validation.

Two checks always run and cannot be selected or suppressed with --checks: collisions.unreachable reports logical path collisions, and coverage.skipped-mount reports declared sources that could not be opened. checks.execution identifies a check that failed to execute.

Interpret common findings

Animation validation allows missing item motions where the engine falls back to idle. Duplicate motion names across banks in one HUD namespace are reported because lookup is ambiguous.

For meshes.chunk-residue, inspect the model and use ogf fix for recognized unread tails.

For textures, distinguish three repairs:

Companion and unused-declaration findings are reported in normal mode but fail verification only under --strict. See THM bump declarations for descriptor edits and DDS bump generation for missing texture pairs.

JSON report

The saved file uses the shared report envelope. Its result contains checks, overall status, duration, cache, and skippedMounts. reads is included only with --trace-reads.

Each check has its own status, duration, summary, verification type, and findings.

Example report finding — inspect a missing mesh dependency:

{
  "assetPath": "meshes/ogf/dev_bolt_hud.ogf",
  "message": "Mesh references missing motion 'dynamics\\devices\\dev_bolt\\dev_bolt_hud_animation'",
  "ruleId": "meshes.motion-validation"
}

Exit code: 3. The referenced animation bank is missing.

assetPath is root-relative when available and null when the finding has no asset subject. message is human-readable; use ruleId for automated classification. Findings are ordered by asset path, rule, and message.

Statuses are passed, failed, error, incomplete, or skipped; the overall status reflects the most severe check result. A check’s duration is null when it did not run; measured durations are whole milliseconds. skippedMounts identifies declared sources omitted because they could not be opened.

Inspect cache and read costs

cache reports retained entries and bytes, hits, misses, and refusals. Hits plus misses count parsed-asset requests, including misses for asset kinds the cache does not retain. A non-zero refused count means the byte ceiling prevented retention.

Add read tracing when investigating repeated I/O:

xrf-cli gamedata verify ./target/gamedata --trace-reads --report ./read-report.json

reads reports paths, reads, bytes, uniqueBytes, and the 25 hottest paths. The difference between total and unique bytes exposes repeated reads. The path count covers the whole run even though the hottest-path list is capped. Tracing adds synchronization on the read path; compare timings with the same tracing setting.

Result

A fully passed result exits 0. Invalid content exits 3; error, incomplete, and skipped results exit 1. In particular, missing mounted sources cannot produce a clean verification verdict merely because the remaining assets passed.

Verification covers the resolved assets in the selected scope, including generated scripts and configs. It does not validate source files omitted from the build or replace testing the resulting game behavior.

Command reference

xrf-cli gamedata list

List assets resolved by an installation or gamedata tree

xrf-cli gamedata list [OPTIONS] --path <path>...

xrf-cli gamedata verify

Command to verify gamedata

xrf-cli gamedata verify [OPTIONS] <ROOT>

LTX CLI

LTX commands inspect, 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.

Formatting

ltx format formats selected loose config files. --check writes nothing and exits 3 when any selected file needs formatting, including when the input is a single file. From a project containing gamedata/configs:

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

Example output — check an unformatted LTX file:

Checking 1 ltx file(s) from 1 provided path(s)
Checking 1 file(s)
Not formatted: ./ltx-unformatted/spacing.ltx

Stderr:

Format issues with 1/1 files in 2 ms
Check failed: 1 finding(s)

Exit code: 3.

When the input resolves through an installation, archived configs are listed as declined because they cannot be rewritten in place. Review that list before treating a formatting run as coverage of the whole config set.

Verifying

ltx verify checks an LTX project folder, including schemes and case-sensitive include paths. Supply a directory; include, inheritance, section-field, and scheme errors fail verification.

xrf-cli ltx verify --path ./gamedata/configs

Only sections that declare $scheme are checked against a scheme. Other sections, including array-style sections, are valid without one. A scheme can use $strict = true when its own section shape is fully known.

Scheme definitions are documented in Script config schemes.

Inspecting configs

Use ltx list to list config files and their includers. Use ltx inspect to see a resolved section’s values and where each value was written:

xrf-cli ltx list --path ./gamedata/configs
xrf-cli ltx inspect wpn_ak74 --path ./gamedata/configs

Example output — inspect a DLTX override:

Inspect path: ./gamedata-dltx/configs
[wpn_ak74] resolved from system.ltx (dltx)
  declared in items\w_ak74.ltx
  inherits wpn_base
  $scheme    = $wpn_patched          set by w_ak74.ltx (depth 1)
  ammo_class = ammo_a,ammo_b,ammo_c  set by mod_system_aaa.ltx ('>', depth -200)
  cost       = 9000                  set by mod_system_xxx.ltx (depth -400)
  patched_by = mod_system_xxx.ltx    set by mod_system_xxx.ltx (depth -400)
4 field(s), 0 diagnostic(s)

Exit code: 0. The later patch supplies cost = 9000; the output names the file that supplied each value.

Use the resolved values and their source locations to distinguish a wrong declaration from a later override. If several entry points declare the section, select one with --entry system.ltx. Both commands accept --dltx for patched installations.

The DLTX patch dialect

Anomaly and its Monolith-based descendants let an addon patch a config without editing it, by dropping a mod_<base>_*.ltx beside it. --dltx reads configs under those rules; without it, a patch file is refused and the error names the flag.

xrf-cli ltx verify --path "C:/games/anomaly" --dltx
xrf-cli gamedata verify "C:/games/anomaly" --dltx

DLTX is not vanilla LTX with patches applied on top. It changes how base data resolves even when no patch file exists:

Patch operations, all Monolith-specific:

When several patch files touch the same field, the alphabetically last one wins, and a patch file always outranks the base tree.

Command reference

xrf-cli ltx format

Command to format ltx and ini files

xrf-cli ltx format [OPTIONS] --path <path>...

xrf-cli ltx inspect

Explain one resolved section: its fields, and where each value is written

xrf-cli ltx inspect [OPTIONS] --path <path> <section>

xrf-cli ltx list

List the LTX configs a project holds, and the role each one plays

xrf-cli ltx list [OPTIONS] --path <path>

xrf-cli ltx verify

Command for verification of ltx and ini files

xrf-cli ltx verify [OPTIONS] --path <path>

OGF CLI

OGF commands inspect X-Ray models, check their dependencies, replace stored motion or texture references, and remove recognized unread bytes. Use reference patching when relocating assets without re-exporting model geometry.

Examples run from a working directory containing the named meshes tree or model files. Patch commands rewrite the source by default; --dest selects a separate output and --dry-run previews the change.

ogf info

Inspect a model before changing its references:

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

Example output excerpt — inspect model texture references:

Bones: 1
[0] name: lod
[0] parent:
OGF children (1):
[0] texture name: wpn\wpn_pm
[0] shader name: models\model

Exit code: 0.

The output includes available header and bounds data, textures and shaders, description metadata, bones and parents, motion references, and progressive levels of detail. It also reports unparsed chunk ids and nested child visuals.

Progressive detail usually belongs to child visuals. Add --verbose to see each level’s index-buffer offset, triangle count, and vertex count.

Inspection is read-only. If parsing fails, confirm the file’s source and game version, then compare the error with neighboring models from the same archive.

ogf verify

Check a model or directory before importing it:

xrf-cli ogf verify --path ./meshes --root ./gamedata --report ./ogf-report.json

The command checks model data and resolves texture dependencies. Repeat --root for additional lookup roots, searched after the visual’s own tree. Missing dependencies can make verification incomplete; inspect the report before treating a readable model as ready to use.

A passed check exits 0, invalid content exits 3, and error, incomplete, or skipped results exit 1. This is a data check; inspect the model in the target renderer to verify its appearance.

ogf patch-motion-refs

An animated model stores references to OMF animation banks. Replace the list when moving those banks:

xrf-cli ogf patch-motion-refs --path ./meshes/wpn_ak74_hud.ogf `
  --refs "dynamics\weapons\wpn_ak74\wpn_ak74_hud_animation" --dry-run
xrf-cli ogf patch-motion-refs --path ./meshes/wpn_ak74_hud.ogf `
  --refs "dynamics\weapons\wpn_ak74\wpn_ak74_hud_animation"

Use backslashes and omit .omf for an individual bank. A reference ending in \*.omf loads every OMF in that directory. Multiple values replace the list in the supplied order:

xrf-cli ogf patch-motion-refs --path ./hands.ogf --dest ./hands.patched.ogf `
  --refs "first\animation" "second\animation"
xrf-cli ogf patch-motion-refs --path ./hands.ogf --dest ./hands.wildcard.ogf `
  --refs "dynamics\weapons\wpn_hand\hud_animation\*.omf"

Only the references chunk is rebuilt. The command preserves its existing form—an older comma-separated string or a newer counted list—and copies geometry, bones, IK data, and other chunks byte for byte. A model without a references chunk is refused.

Confirm the stored list with ogf info, then verify that the referenced banks exist and contain the required motions.

ogf patch-texture-refs

Rename one exact texture reference, including occurrences in nested child visuals:

xrf-cli ogf patch-texture-refs --path ./meshes/wpn_ak74u.ogf --from "wpn\wpn_aksu\wpn_aksu" `
  --to "wpn\wpn_ak74u\wpn_ak74u"

Names use backslashes and omit extensions. All matching texture chunks are rebuilt; paired shader names and unrelated chunks are preserved. If --from matches nothing, the error lists the model’s actual references.

Move the texture files, patch every model using the old name, then inspect the changed references with ogf info and run gamedata verification. A model missed during the rename still points to the old path.

Patch checks

Both reference patchers first apply the model’s existing values and require byte-identical output. This guards against losing chunks that cannot be reconstructed from parsed geometry.

After writing, the motion patcher requires the requested list to read back; the texture patcher requires the old name to be absent and the new name present. A failed read-back check triggers restoration of an in-place source or removal of a separate destination. Filesystem write interruptions are not covered by that check; use a separate destination when retaining the original is required.

ogf fix

Use fix for meshes.chunk-residue findings: some Anomaly and Call of Chernobyl models contain trailing bytes that the engine does not consume, such as data beyond the counted motion-reference list.

Preview a directory sweep, then apply it or write a separate output for one model:

xrf-cli ogf fix --path ./meshes --dry-run
xrf-cli ogf fix --path ./meshes/actors/stalker_zombied/stalker_zombied_bandit2a_face1.ogf
xrf-cli ogf fix --path ./meshes/wpn_m1891.ogf --dest ./fixed/wpn_m1891.ogf

Example output excerpt — remove unread model bytes:

Fixing ogf visual ./gamedata/meshes/ogf/residue_split_motion_ref.ogf
Normalize ./gamedata/meshes/ogf/residue_split_motion_ref.ogf: 34 bytes the engine never reads
Ogf visual written into ./fixed.ogf
Normalized 1 of 1 visual(s), 34 bytes discarded, 0 unchanged, 0 failed

Stderr:

Discarding uncounted motion reference 'actors\stalker_scenario_animation' from ./gamedata/meshes/ogf/residue_split_motion_ref.ogf

Exit code: 0. This model contains 34 unread bytes. The source is retained and fixed.ogf receives the repaired model.

Directories are scanned recursively in path order. --dest is supported only for a single file; --jobs controls directory-sweep parallelism.

What changes

The fixer removes recognized unread motion-reference tails, adjusts the chunk’s declared size, and removes accounted trailing bytes after the last well-formed chunk. Other bytes are preserved. An already well-formed source is left untouched; with --dest, a destination is still written.

Before writing, the normalized bytes must parse without residue and produce the same motion references. Unexplained trailing data and chunks extending beyond the file are refused. The result is staged beside the destination and moved into place.

A directory sweep continues after a refusal. Successfully fixed files remain changed; any refused files produce exit 1 and entries in findings. Check those entries, then use ogf info to confirm that repaired models no longer report residue.

Command reference

xrf-cli ogf fix

Command to rewrite ogf visuals into well-formed bytes, changing nothing the engine reads

xrf-cli ogf fix [OPTIONS] --path <path>

xrf-cli ogf info

Command to print information about provided ogf file

xrf-cli ogf info [OPTIONS] --path <path>

xrf-cli ogf patch-motion-refs

Command to rewrite motion refs of provided ogf file

xrf-cli ogf patch-motion-refs [OPTIONS] --path <path> --refs <refs>...

xrf-cli ogf patch-texture-refs

Command to rename a texture reference of provided ogf file

xrf-cli ogf patch-texture-refs [OPTIONS] --path <path> --from <from> --to <to>

xrf-cli ogf verify

Command to verify ogf visuals can be packed for rendering

xrf-cli ogf verify [OPTIONS] --path <path>

OMF CLI

OMF commands inspect animation banks, verify serialization, and filter, rename, or duplicate motions. Use them when adapting an imported bank to the motion names referenced by a weapon or HUD config.

Examples run from a working directory containing the named OMF files and JSON map. Filtering and renaming require an explicit destination; duplication rewrites the source unless --dest is supplied.

How motions are stored

An OMF holds parallel lists of motion definitions and keyframe payloads, paired by position. Definitions contain names and playback parameters. The engine looks up a definition name, then reads its corresponding payload.

The editing commands maintain this pairing and update motion indices when necessary. LTX anm_* values refer to the definition names.

omf info

xrf-cli omf info --path ./meshes/example.omf --verbose

Example output — inspect a motion bank:

Read omf file ./gamedata/meshes/omf/wpn_mp5_hud_animation.omf
Omf file information
Version: 4
Motions: 3 mp5_shoot,idle,mp5_reload
Bones total: 7
Parts: default
Part 'default' bones: wpn_body,body,trigger,zatvor,lock,wpn_silencer,magazin

Exit code: 0.

Inspection is read-only. It reports the version, motions, bone count, animation parts, and bones assigned to each part. Verbose output adds per-motion keyframe counts, flags, speed, power, accrue, and falloff.

Keyframes and playback speed determine duration. Flag bit 0b10 means play once and stop; without that bit, a motion loops. Vanilla idle motions commonly use 0b00, while draw, shoot, and bore motions use 0b10.

If a motion is missing, check the bank’s names before changing the model or config that references it.

omf repack

Select the mode by the input and output arguments:

xrf-cli omf repack --path ./meshes/example.omf --dest ./meshes/example.repacked.omf
xrf-cli omf repack --path ./meshes/example.omf --verify
xrf-cli omf repack --path ./meshes

Example output — verify byte-identical serialization:

Byte identical: ./gamedata/meshes/omf/wpn_mp5_hud_animation.omf

Exit code: 0. Verbose mode makes the successful comparison visible.

The writer preserves chunk order and nested motion chunk ids. Verification requires byte-identical output, making it useful after changing OMF parsing or serialization. A mismatch or processing error produces a non-zero exit code; directory mode reports both counts.

Without verbose logging, a passing single-file verification is silent and a directory run prints failures and its summary. Add --verbose to list files that matched.

omf filter-motions

Extract the motions needed from a shared bank:

xrf-cli omf filter-motions --path ./shared_bank.omf --dest ./wpn_ak74_hud_animation.omf `
  --keep-prefix ak_74_
xrf-cli omf filter-motions --path ./bank.omf --dest ./trimmed.omf --keep idle `
  --keep-prefix ak_74_ pist_

At least one exact --keep name or literal --keep-prefix is required. A motion survives if it matches any selector; ak_74_ and ak74_ select different names. Matching nothing fails before writing.

Surviving definitions and payloads retain their pairing, with motion indices renumbered to their new positions. Use a separate destination to retain the shared bank for other weapons. Add --dry-run to inspect the selection without writing, or --verbose to list the resulting motions.

omf rename-motions

Create ak74.json as a flat map from current names to replacement names:

{
  "ak_74_draw": "ak74_draw",
  "ak_74_idle_move": "ak74_idle_moving",
  "ak_74_grenade_off": "ak74_switch_off"
}

Apply it to the bank:

xrf-cli omf rename-motions --path ./trimmed.omf --dest ./renamed.omf --map ./ak74.json

Unmapped motions keep their names. Add --strict to require a map entry for every motion; the error identifies missing entries. A map matching nothing or producing duplicate motion names is refused before writing.

Renaming updates definition and payload names together. Use --dry-run to preview the change and --verbose to list the result, then update configs that refer to the old names.

omf duplicate-motion

Copy an existing motion under a new name:

xrf-cli omf duplicate-motion --path ./wpn_hand_pm_hud_animation.omf --from pm_idle `
  --to pm_idle_bore --play-once

This example edits the bank in place. Supply --dest to keep the original. Both definition and keyframe payload are copied into a new paired slot, increasing the file by one motion’s payload. An unknown source name or an existing destination name is refused.

--play-once sets the stop-at-end flag on the copy while preserving other flags.

Why --play-once exists

The weapon bore state returns to idle through its animation-end callback. Pointing anm_bore at a looping motion can leave the weapon in that state until another action forces a transition.

When an imported bank has no bore motion, a play-once copy of its idle can hold the pose and then deliver the end callback. Confirm with omf info --verbose that the copy exists and its 0b10 flag bit is set, then check the state transition in game.

Failure notes

A parse failure stops editing before writing. For a truncated chunk, re-extract the file from its original packed archive and retry inspection; repacking cannot reconstruct missing bytes.

The writer rejects data that the selected OMF version cannot represent. Motion marks require version 4, so version 3 data carrying marks fails. A mismatch between definition and payload counts also fails.

After editing, inspect the bank with omf info, confirm its model’s references with ogf info, and verify the assembled gamedata. A valid bank alone does not prove that every caller uses its new names.

Command reference

xrf-cli omf duplicate-motion

Command to copy a motion of provided omf file under a new name

xrf-cli omf duplicate-motion [OPTIONS] --path <path> --from <from> --to <to>

xrf-cli omf filter-motions

Command to keep only selected motions of provided omf file

xrf-cli omf filter-motions [OPTIONS] --path <path> --dest <dest>

xrf-cli omf info

Command to print information about provided omf file

xrf-cli omf info [OPTIONS] --path <path>

xrf-cli omf rename-motions

Command to rename motions of provided omf file

xrf-cli omf rename-motions [OPTIONS] --path <path> --dest <dest> --map <map>

xrf-cli omf repack

Command to repack provided omf file or directory of omf files

xrf-cli omf repack [OPTIONS] --path <path>

Particle CLI

Particle commands inspect and convert particles.xr libraries. Use the unpacked representation to edit a library, then verify the packed result before adding it to gamedata.

Examples

Run from a working directory containing the source particles.xr. Use new destinations for the unpacked library and rebuilt file:

xrf-cli particle info --path ./particles.xr
xrf-cli particle unpack --path ./particles.xr --dest ./particles_unpacked

Example output — inspect particles:

Read particle file ./gamedata/particles.xr
Particles file information:
Version: 1
Effects count: 921
Groups count: 350

Exit code: 0.

Edit the exported files, then validate and pack them:

xrf-cli particle verify --path ./particles_unpacked --unpacked
xrf-cli particle pack --path ./particles_unpacked --dest ./particles.rebuilt.xr
xrf-cli particle verify --path ./particles.rebuilt.xr

verify checks that the selected representation can be read. It does not resolve the library’s texture dependencies. After installing the rebuilt file, use gamedata verification to check the library in its asset context, and inspect the affected effects in game.

Re-serialize a library

xrf-cli particle repack --path ./particles.xr --dest ./particles.repacked.xr
xrf-cli particle re-unpack --path ./particles_unpacked --dest ./particles_unpacked_roundtrip

repack reads a packed library and writes another packed file. re-unpack imports an unpacked library and exports it to another directory. Neither command automatically compares the result with its source. Serialization can change bytes, so a hash difference alone does not demonstrate a change to the particle definitions.

Failure notes

Packing rejects an existing output file, and unpacking rejects an existing destination directory, unless --force is supplied. Use that flag only when replacing the selected output is intended.

A successful read or conversion establishes that the tool accepts the data. It does not establish visual equivalence or correct behavior of every effect.

Command reference

xrf-cli particle info

Command to print information about provided particle file

xrf-cli particle info [OPTIONS] --path <path>

xrf-cli particle pack

Command to pack unpacked particle files into single particle.xr

xrf-cli particle pack [OPTIONS] --path <path>

xrf-cli particle repack

Command to repack provided particle.xr into another file

xrf-cli particle repack [OPTIONS] --path <path> --dest <dest>

xrf-cli particle re-unpack

Command to re-unpack provided particle directory into another directory

xrf-cli particle re-unpack [OPTIONS] --path <path> --dest <dest>

xrf-cli particle unpack

Command to unpack provided particle.xr into separate files

xrf-cli particle unpack [OPTIONS] --path <path>

xrf-cli particle verify

Command to verify provided particle file

xrf-cli particle verify [OPTIONS] --path <path>

Profile

profile run measures repeated executions of a command and compares builds within the same session. It reports wall-clock duration and sampled memory use.

Measure a command

From an xrf-tools checkout with a release binary and an assembled target/gamedata tree:

xrf-cli profile run -b ./target/release/xrf-cli.exe --report ./profile-report.json `
  -- gamedata verify ./target/gamedata

Example output — profile a command:

Profiling dds info --path ./gamedata/textures/ui/ui_test_sheet.dds
1 binaries, 3 rounds after 1 warmup, interleaved
round 1/3 xrf-cli: 10 ms
round 2/3 xrf-cli: 9 ms
round 3/3 xrf-cli: 11 ms
xrf-cli: median 10 ms, peak 11.8 MB / mean 11.8 MB

Exit code: 0. Timings vary between runs.

Everything after -- is passed unchanged to the measured binary. Relative paths use the current directory. The child’s stdout and stderr are discarded; measurements are returned in the profiling command’s report.

The default is one warmup round followed by five measured rounds. Every invocation performs the command’s normal side effects, including warmups. Use a read-only command for a repeatable comparison, or restore its inputs between sessions.

Comparing builds

Repeat --binary to compare builds. In this example, old/xrf-cli.exe is a previously saved build and target/release/xrf-cli.exe is the candidate:

xrf-cli profile run -b ./old/xrf-cli.exe -b ./target/release/xrf-cli.exe --rounds 5 `
  --report ./comparison.json -- gamedata verify ./target/gamedata

The first binary is the baseline. Other binaries report deltaPercent against its median duration; negative values mean faster execution. Each binary is identified by its own --version output, independently of the adjacent checkout.

Use the same corpus, arguments, worker settings, and machine for all builds. Compare old and new binaries in one session: this command does not load a historical baseline.

Why it is not a stopwatch

Rounds are interleaved: each binary runs once, in the supplied order, before the next round starts. This limits the effect of changing file caches, background load, and thermal conditions, but does not eliminate measurement noise.

--warmup controls how many initial rounds are discarded. Increase it when the workload needs more time to stabilize; one warmup does not guarantee a warm or steady system.

The summary uses medians. With an even number of rounds, it selects the lower middle value. Individual measurements remain in runs in execution order, so inspect their spread before attributing a small difference to a code change.

Memory

Memory is sampled about every 20 ms for the measured child process, excluding its descendants:

• peakBytes is the largest observed resident set in a round.
• meanBytes is the average resident set across that round’s samples.
• Summary values are independent medians of the per-round measurements.

Short-lived allocations can fall between samples. A missing measurement means no usable sample was collected, not zero memory use. These are resident-memory figures, not total allocations or CPU utilization.

A high peak with a lower mean suggests transient memory use; similar values suggest sustained residency. Neither alone proves whether the program released a particular allocation.

Exit codes

Profiling succeeds when measurement succeeds, even if a measured command returns a failure code. Inspect each build’s exitCodes before comparing its timing: a fast failure may have done less work. Multiple observed codes mean the command’s outcome varied during the session.

Command reference

xrf-cli profile run

Command to measure one invocation across builds, interleaved

xrf-cli profile run [OPTIONS] --binary <binary> -- <arguments>...

Spawn CLI

Spawn commands inspect and convert ALife .spawn files. Unpack a file for editing, then rebuild and verify a separate output before replacing the game’s spawn file.

Examples

Run from a working directory containing all.spawn, with new output paths:

xrf-cli spawn info --path ./all.spawn
xrf-cli spawn unpack --path ./all.spawn --dest ./all_spawn

Example output excerpt — inspect spawn data:

Spawn file information:
Version: 10
GUID: a117405b-0a2e-a781-4ab5-f7aa88ae759c
Levels count: 5
Objects count: 262
Artefact spawn points: 256
Patrols: 4636
Level version: 10
Level graph vertices: 934
Level graph points: 512
Level graph edges: 2568

Exit code: 0.

info reports the header and counts of objects, artifact spawns, patrols, and graph entries. After editing the exported representation:

xrf-cli spawn pack --path ./all_spawn --dest ./all.rebuilt.spawn
xrf-cli spawn verify --path ./all.rebuilt.spawn

Verification reads the packed file and checks that its structure can be parsed. Use gamedata verification for checks involving the surrounding assets; test the affected spawning behavior in game.

Re-serialize a spawn file

xrf-cli spawn repack --path ./all.spawn --dest ./all.repacked.spawn

repack reads a packed file and writes another packed file. It does not automatically compare the output with the source or prove that an editing workflow preserved behavior.

Failure notes

Packing and unpacking reject existing destinations unless --force is supplied. Choose a new destination while reviewing edits; use --force when replacing that output is intended.

If the source cannot be parsed, inspect the reported chunk or format error before editing. Repacking requires a readable source and does not repair truncated data.

Command reference

xrf-cli spawn info

Command to print information about provided spawn file

xrf-cli spawn info [OPTIONS] --path <path>

xrf-cli spawn pack

Command to pack unpacked spawn files into single *.spawn

xrf-cli spawn pack [OPTIONS] --path <path>

xrf-cli spawn repack

Command to repack provided *.spawn into another file

xrf-cli spawn repack [OPTIONS] --path <path> --dest <dest>

xrf-cli spawn unpack

Command to unpack provided *.spawn into separate files

xrf-cli spawn unpack [OPTIONS] --path <path>

xrf-cli spawn verify

Command to verify provided spawn file

xrf-cli spawn verify [OPTIONS] --path <path>

Sprite CLI

Sprite commands pack and unpack sheets containing multiple icons. Choose the workflow by the file that defines the layout:

Use DDS commands to crop or convert an individual texture. The examples below run from an assembled gamedata root containing configs and textures; packing writes the named output sheets.

Equipment sprite

Unpack the equipment sheet into per-section images:

xrf-cli sprite unpack-equipment --system-ltx ./configs/system.ltx `
  --source ./textures/ui/ui_icon_equipment.dds `
  --output ./textures_unpacked/ui/ui_icon_equipment

Only sections with $inventory_icon = true and all four fields—inv_grid_x, inv_grid_y, inv_grid_width, and inv_grid_height—participate. Grid fields alone do not opt in a section, because abstract base sections commonly pass them to descendants. $inventory_icon = false excludes a section.

Edit the extracted icons, check the grid, then pack the replacement sheet:

xrf-cli sprite verify-equipment --system-ltx ./configs/system.ltx
xrf-cli sprite pack-equipment --system-ltx ./configs/system.ltx `
  --source ./textures_unpacked/ui/ui_icon_equipment `
  --output ./textures/ui/ui_icon_equipment.dds --strict

Packing prefers <section>.png over <section>.dds. Icons that differ from the target dimensions are fitted while preserving aspect ratio and centered on a transparent canvas.

Without --strict, missing icon files are skipped with warnings. Strict packing reports all missing opted-in sections and writes no sheet, allowing the full list to be corrected together. Use --gamedata when packing needs a separate resource-lookup root.

Commands reading system.ltx accept --dltx for the Monolith/Anomaly patch dialect. Select it when the layout depends on those patches.

Checking the grid before moving an icon

Grid coordinates use 50 × 50 pixel cells. verify-equipment reports partial overlaps between sections, including the shared cells and overlap count, and returns a non-zero exit code when it finds them.

Identical rectangles are allowed: variants such as _nimble, _snag, and pri_a15_ quest copies often share their base weapon’s slot. Packing can warn when different art targets the same slot, but it does not replace the overlap check.

A partial overlap is different: widening a 1 × 1 icon to 2 × 1 can cover a neighboring icon. Both may pack, with the later write replacing shared pixels. Run verification before and after changing grid positions or dimensions, then inspect the resulting sheet.

Example output — check the icon grid:

Inventory icon grid is clean, no overlapping rects

Exit code: 0.

Description sprites

Unpack sheets named by an XML texture description:

xrf-cli sprite unpack-description --description ./configs/ui/textures_descr/ui_actor.xml `
  --base ./textures --output ./textures_unpacked

Example output excerpt — unpack a sprite sheet:

Unpacking for 1 files
Unpacked 1 files

Exit code: 0.

After editing the extracted images, pack them back:

xrf-cli sprite pack-description --description ./configs/ui/textures_descr/ui_actor.xml `
  --base ./textures_unpacked --output ./textures --strict

Each image must exactly match its declared rectangle; description packing does not rescale. Use DDS fitting when an imported icon needs different bounds.

The description and base path are required. Output defaults to the base path when omitted, so name a separate output explicitly when keeping source and result apart. Both commands accept --strict; -s means --silent.

Select sheets from a description

Both commands process every declared sheet by default. Repeat --file to narrow the selection:

xrf-cli sprite pack-description `
  --description ./configs/ui/textures_descr/ui_actor_upgrades.xml --base ./textures_unpacked `
  --output ./textures --file ui_actor_weapons --strict

Use a declared path such as ui\ui_actor_weapons, with either separator, or an unambiguous bare name such as ui_actor_weapons. Missing or ambiguous names are errors.

Unpacking distributes sheets across workers and accepts --jobs; packing is sequential. The engine repository wraps common equipment and description workflows through npm run cli -- sprites ....

Command reference

xrf-cli sprite pack-description

Command to pack the sprites a texture description xml declares

xrf-cli sprite pack-description [OPTIONS] --description <description> --base <base>

xrf-cli sprite pack-equipment

Command to pack an equipment sprite from separate icon files

xrf-cli sprite pack-equipment [OPTIONS] --system-ltx <system-ltx> --source <source> --output <output>

xrf-cli sprite unpack-description

Command to unpack the sprites a texture description xml declares

xrf-cli sprite unpack-description [OPTIONS] --description <description> --base <base>

xrf-cli sprite unpack-equipment

Command to unpack separate icon files out of an equipment sprite

xrf-cli sprite unpack-equipment [OPTIONS] --system-ltx <system-ltx> --source <source> --output <output>

xrf-cli sprite verify-equipment

Command to check an equipment sprite’s inventory icon grid rects for overlaps

xrf-cli sprite verify-equipment [OPTIONS] --system-ltx <system-ltx>

THM CLI

thm patch-bump changes or disables the bump declaration in an existing texture descriptor. Use it when moving an imported texture or correcting a missing bump reference. Generate the texture files separately with dds make-bump.

Repoint a bump declaration

Run from a gamedata root containing the descriptor and its replacement bump texture:

xrf-cli thm patch-bump --path ./textures/wpn/wpn_pm/wpn_pm.thm --to "wpn\wpn_pm\wpn_pm_bump" `
  --dry-run
xrf-cli thm patch-bump --path ./textures/wpn/wpn_pm/wpn_pm.thm --to "wpn\wpn_pm\wpn_pm_bump"

Example report result — preview a bump-name change:

{
  "isDryRun": true,
  "originalSize": 138,
  "patchedSize": 154,
  "previousMode": 1,
  "previousName": ""
}

Exit code: 0. This dry run changes no file. The report shows a 16-byte increase for the requested name.

The first command validates and reports the proposed change; the second rewrites the descriptor in place. The stored name is relative to textures, uses backslashes, and omits the extension.

Use --dest to write a separate descriptor. --to changes the name while preserving the existing mode, including use_parallax; it does not enable a descriptor whose mode is disabled.

Disable a missing bump

If the surface should have no bump map, clear the declaration:

xrf-cli thm patch-bump --path ./textures/tile/tile_walls_red_01.thm --off

--off sets the mode to none and clears the name, matching the form written by STextureParams. Choose either --to or --off; they cannot be combined.

How the engine resolves it

CTextureDescrMngr::LoadTHM reads the descriptor beside the texture. An active bump declaration uses the stored name; the engine does not discover a map merely because a neighboring file ends in _bump.dds.

If that name resolves to nothing, the renderer still selects the bump shader path and substitutes ed\ed_dummy_bump, logging ! Fallback to default bump map. The surface appears flat while retaining the bump rendering path. A copied descriptor can cause this when it still points into the source project’s texture layout. In renderer_r4, this lookup happens through CTexture::Preload.

Preservation and verification

The patcher rebuilds only the bump chunk and copies other chunks byte for byte. Before writing, it requires a rewrite of the existing declaration to reproduce the source exactly. After writing, it reads the requested declaration back. A failed read-back check triggers restoration of an in-place source or removal of a separate destination. This does not make an interrupted or failed filesystem write transactional; use a separate destination when the original must remain available.

From the directory containing the assembled gamedata tree, verify the resulting references:

xrf-cli gamedata verify ./gamedata --checks textures --report ./texture-report.json

Resolve remaining bump findings before checking the surface in game. Descriptor validation establishes the reference; it does not establish the visual quality of the map.

Command reference

xrf-cli thm patch-bump

Command to repoint the bump texture reference of provided thm file

xrf-cli thm patch-bump [OPTIONS] --path <path>

Translation CLI

Translation commands import X-Ray XML string tables, maintain XRF JSON translation sources, and compile them back to gamedata. Start with Parse for an existing game or mod; use Format, Verify, and Build for an existing JSON project.

Examples run from a working directory containing a translations source folder. Import examples additionally assume a stalker-anomaly installation beside it.

Initialize

Add missing language keys as null placeholders in the JSON sources:

xrf-cli translation initialize --path ./translations

This updates files in place. Running it again on the same initialized sources makes no further change. A null marks a missing translation; it does not supply fallback text.

Format

Normalize source layout, then use check mode in automation:

xrf-cli translation format --path ./translations
xrf-cli translation format --path ./translations --check

Example output — check unformatted JSON sources:

Checking 2 translation source(s)
Not formatted: ./translations\st_items.json
Not formatted: ./translations\st_ui.json

Stderr:

Format issues with 2/2 translation source(s) in 2 ms
Check failed: 2 finding(s)

Exit code: 3.

The formatter sorts ids and language keys naturally, uses two-space indentation, and adds a trailing newline. Natural order places st_thanks2 before st_thanks10, and ammo-5.45x39-ap before ammo-11.43x23-fmj. Check mode writes nothing and exits 3 when selected files need formatting.

Repeat --path for multiple inputs. Directories select JSON files recursively; an explicitly named file is accepted regardless of its extension.

By default, each file uses its dominant LF or CRLF line ending; a tie or a file without line breaks selects LF. Mixed line endings are normalized to that choice. Check mode ignores line-ending differences unless --line-endings lf or --line-endings crlf explicitly requires one convention.

What it does not touch

Formatting preserves JSON values and their representation as strings or arrays. A one-element ["text"] stays an array. The build joins array elements with the literal \n sequence used by string values, so formatting does not choose between these authoring forms.

It does not add null placeholders; use initialize or parse for that. Files already matching the selected format are not rewritten, preserving their timestamps.

When it refuses

Selecting no sources or encountering an unparseable source exits 1. A parse failure stops the run at that file; files formatted earlier remain changed. Each replacement is staged as a whole file.

Build

Compile JSON sources into one XML string table per source and selected language, using that language’s code page:

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

Example output — build Ukrainian string tables:

Building translations in ./translations (ContainingInstallation), language - ukr, sorted - true
Building 2 translation source(s)
Built translation files in 2 ms

Exit code: 0.

A missing translation compiles to its id. The report summarizes tables written and ids compiled per language.

Build and verify accept a single source file or roots read through the virtual file system. Layered roots resolve winning files by priority, including files from mounted archives. The build output is a plain directory and must be outside every source root.

Verify

Check completeness for a language:

xrf-cli translation verify --path ./translations --language ukr --strict `
  --report ./translation-report.json

Example output — find missing Ukrainian text:

Verifying translations in ./translations (ContainingInstallation), language - ukr
Verifying 2 translation source(s)
Verified translation files in 0 ms, 4 checked, 2 missing

Stderr:

Translation key missing: st_medkit_name ukr in st_items.json
Translation key missing: st_ui_quit ukr in st_ui.json
Check failed: 2 finding(s)

Exit code: 3. Both the absent key and the explicit null are reported as missing.

Both an absent language key and an explicit null count as missing. Without --strict, missing translations are reported while a completed check succeeds. With --strict, those gaps produce exit 3.

The report contains a finding per missing id and a languages array with summary rows per file and language. Use the summary rows to review large imports, then inspect findings for the files being translated. An unreadable source is an execution failure; malformed source content can fail verification independently of --strict.

Parse

Import XML tables once per language into a shared JSON output directory:

xrf-cli translation parse --path ./stalker-anomaly --language eng --output ./translations
xrf-cli translation parse --path ./stalker-anomaly --language ukr --output ./translations

XML tables do not declare their language. --language labels the imported text, so select the language that the input actually contains. Installations with tables in db/configs archives are read through the same virtual file system as loose trees.

What it writes

Each table becomes a JSON source with its subdirectory path preserved. Imports into the same output merge languages. Ids and language keys use the same canonical order as Format, independently of import order. A record missing one of the languages represented in its file receives an explicit null.

Existing text that differs from the import is preserved and counted as a conflict. Add --overwrite to replace it. Reimporting unchanged tables into an unchanged output is idempotent.

Finding the tables

--path names the input root. The importer looks under configs/text when present, then selects the directory named for the requested language. Use --prefix for a different layout. A selected scope that still contains another language’s directory is refused to prevent labeling its strings with the wrong language.

Before writing anything

Add --dry-run to inspect the proposed import without writing. Use --file to select one table. Unreadable tables are reported; --strict makes those findings fail the run.

Notes

In the engine repository, npm run cli -- verify translations wraps verification, and the translations build target wraps compilation. Call xrf-cli directly for formatting, initialization, and imports.

Command reference

xrf-cli translation build

Command to build translation files into gamedata

xrf-cli translation build [OPTIONS] --path <path>... --output <output>

xrf-cli translation format

Command to normalize json translation sources

xrf-cli translation format [OPTIONS] --path <path>...

xrf-cli translation initialize

Command to initialize translation files

xrf-cli translation initialize [OPTIONS] --path <path>

xrf-cli translation parse

Command to parse xml translations into json sources

xrf-cli translation parse [OPTIONS] --path <path>... --language <language> --output <output>

xrf-cli translation verify

Command to verify translation files integrity

xrf-cli translation verify [OPTIONS] --path <path>...

Extern exports

Use xrf-cli externs export to generate or check a manifest of script exports declared through TypeScript extern(...) calls. Choose JSON for the tracked contract, XML for structured export, or HTML for a browsable reference.

Export a manifest

The examples below run from the xrf-engine repository root and require xrf-cli on your executable search path. For another declaration tree, replace src/engine/declarations with its root.

This command creates or replaces target/parsed/externs.html, creating parent directories when needed:

xrf-cli externs export src/engine/declarations `
  --format html `
  --output target/parsed/externs.html

Example output — export declarations:

Exported 3 externs to './extern.json'.

Exit code: 0.

Exit code 0 means the export succeeded. Open the resulting HTML file to browse namespaces and declarations. Manifest source paths are relative to the declarations root.

Formats

Writing with --output requires an explicit --format. Use --line-endings lf or --line-endings crlf to override the format’s default.

Check

Use --check to compare an existing artifact with the declarations without writing either. It cannot be combined with --output.

xrf-cli externs export src/engine/declarations `
  --check src/engine/declarations/extern.json

The check infers the format from the artifact’s extension unless --format is provided. JSON is compared as parsed manifest data; XML and HTML are compared as rendered text with line-ending differences ignored. This check does not enforce a line-ending policy.

Exit code 0 means the artifact matches. Exit code 3 indicates a mismatch or invalid declaration/artifact content; inspect the diagnostic before regenerating. An input that cannot be read is an execution failure, exit code 1. See CLI reporting and exit codes for the shared contract.

The engine wrapper for this check is npm run cli -- verify externs. It is available explicitly and is not a build or CI gate.

Requirements

Export names must be unique string literals. The parser reads supported function and value references from their declared TypeScript contracts; use an explicit value as Type assertion when a value needs its export type stated. Missing or unrenderable callable types are emitted as unknown. Unsupported declarations produce diagnostics rather than inferred runtime contracts.

The command skips *.test.ts, *.spec.ts, and sources under __test__.

Command reference

xrf-cli externs export

Export TypeScript extern declarations as JSON, XML, or HTML

xrf-cli externs export [OPTIONS] <declarations-root>

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

Game scripting

This 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 --include configs --filter <pattern>

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. Keep them separate from TypeScript, generated Lua, 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:

• sprite sheet workflows through sprites 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

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

Configs are runtime behavior. They 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

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 xrf-cli ltx verify command 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 must start with $. A game config section selects its schema with $scheme = $item_weapon.

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
• rgb
• rgba
• const:<value>