X-Ray Forge

X-Ray Forge (XRF) is a TypeScript rewrite of the S.T.A.L.K.E.R.: Call of Pripyat script layer. It compiles gameplay code to Lua and builds the configs, UI forms, translations, and resources used by X-Ray.

This book covers the full development workflow: project setup, builds, CLI and desktop tools, runtime architecture, gameplay schemes, and debugging.

Start here

• New to XRF? Follow Installation, then read Building.
• Working on gameplay? Start with the Script engine and Schemes.
• Looking for a command? See the XRF CLI or Tools CLI.
• Investigating runtime behavior? Read Game engine and Debugging.

Generated files are written under target/. Edit sources in the engine or tools repository and rebuild; do not edit generated gamedata by hand.

Project repositories

• XRF engine — script runtime and project CLI.
• XRF tools — format libraries, CLI, and desktop application.
• XRF binaries — packaged engine and tool binaries.
• XRF X-Ray 16 SDK — TypeScript-facing engine API.
• Book source — this documentation.

XRF uses OpenXRay as its main engine reference. Game assets are split across base, extended, and locale repositories for English, Ukrainian, and Russian.

XRF changelog

This changelog records notable player-, modmaker-, and developer-facing changes in xrf-engine.

Latest check: xrf-engine 5875ddeb9a399ff371bc51151739e39888098a5a.

~1.0.0

August 2026

• Database archives are packed by the XRF tools instead of xrCompress. compress now calls xrf-cli pack-archive, which reads the same configuration dialect and writes archives straight into target/db, so the SDK binary is no longer part of a build. A group that fits one volume is now named <target>.db rather than <target>.db0. Archives holding mostly text pack somewhat larger, because the packer uses one LZO level where xrCompress used its slowest.

• Script declarations are discovered and documented automatically. Runtime callback, condition, effect, dialog, and task modules load from gamedata/declarations; builds emit an extern JSON manifest, and verify externs checks it against the declaration sources.

• Lua modules load from loose files and packed archives. The bundled engine resolves require() through X-Ray’s virtual filesystem, with loose files overriding archived copies. This supports dynamic declarations and extensions in both development and packaged builds. The same rollup adds an inventory-info-removed callback and fixes sound resume, static spatial updates, duplicated HUD release callbacks, and release-build logging.

• Strict payload validation moves to assembled gamedata. verify ltx no longer accepts --strict; expensive payload checks run through verify gamedata --strict, while regular LTX typing, include, and inheritance checks remain available.

• Random upgrades no longer affect trader inventory. The enhanced-items extension now upgrades only weapons held by non-trader human NPCs. It no longer upgrades world items, outfits, helmets, or trader stock.

• The start command can flush engine logs immediately. Pass --flushlog when launching a test session to retain the final log lines after a hard crash; it may incur a performance cost while active.

• Mounted weapons use the correct shell particles. Mounted PKM weapons now reference the bundled shell effect, so their ejected casings render correctly.

• Surge weather uses a bundled sky texture. Surge phases no longer reference the unavailable preblowout\\pre_blowout_0 texture.

• Used particle effects ship with their textures. The resource payload removes unused particle definitions and adds the blood, fire, smoke, spark, explosion, and distortion textures required by the remaining effects.

• The single-player package trims multiplayer data without removing required definitions. Multiplayer gameplay configs, unused UI assets, and server settings are omitted. Engine-required multiplayer screen and map-spot definitions remain because removing them caused crashes.

July 2026

• NPCs keep their animation state while changing smart-terrain jobs. Reassigning an online NPC activates the new job directly instead of briefly clearing its active logic, preventing the ALife planner from resetting the NPC to idle between jobs.

• Wounded NPCs settle their weapon before falling. The wounded action selects the idle item and prevents weapon reselection until it ends, avoiding an interrupt that can restart the wounded animation.

• Danger hearing has explicit reaction ranges. NPCs respond to each danger type using squared-distance limits; enemy sounds are now considered within the configured 40-metre range instead of being disabled by a zero range.

• Animpoint NPCs complete the requested turn before settling. Reaching an animpoint uses a latched facing check. Leaving the point or changing its cover invalidates the completed turn.

• Post-combat idle yields to wounds and active danger. A wounded NPC is not captured by a post-combat animation, and a newly active danger state can take over instead of waiting for the post-combat delay.

• Wounded NPCs do not enter danger from sounds. The hearing handler declines weapon sounds before assigning danger inertia to an NPC already in a wounded state.

• Weapon-sound handling rejects irrelevant work early. The danger listener filters non-weapon sounds, non-creature sources, and out-of-range sounds before evaluating enemy relations.

• The Zaton B52 bandit leader carries the required PDA. The quest character’s generated supplies now include device_pda_port_bandit_leader.

• The CLI can start a targeted test session without navigating menus. It supports a new game or named save, an optional difficulty, and optional intro skipping; this is a developer workflow, not a change to normal in-game start behavior.

• The CLI can build on-demand in-game quest checks. checks list, build, and clean manage flow scripts that observe quest progress, verify reached states, and report through the console, engine log, and a dedicated checks log.

• Graphics presets load their shared settings with engine console syntax. The renderer presets use cfg_load for the common AtmosFear settings instead of treating an LTX #include directive as a console command.

• Quest helpers resolve the requested target and anomaly zone. destroy_object keeps all story-target parameters, and the Zaton B29 artefact check searches the requested anomaly instead of the global artefact registry.

• Psy post-process effects keep unique IDs. Removing one active psy effect no longer lets the next effect reuse an ID that belongs to another active post-process.

• Simulation assignment state is cleaned up safely. Temporary squad-to-terrain assignments are cleared after use. Invalid or missing data follows fail-safe handling instead of leaving stale simulation state.

• Missing music themes fail safely. Music initialization validates unavailable theme data instead of continuing with incomplete state.

• Travel dialogs reject NPCs without a valid squad. Conversation predicates return unavailable for a missing squad instead of dereferencing it while checking routes, prices, or companion movement.

• Squad-travel prices follow the simulated route. Travel charges the server-graph distance between the squad and destination terrain, rather than the NPC’s current world-position distance.

• NPC sound state is independent. XRF keeps playable sound state per NPC instead of sharing a theme instance among all users. Concurrent dialogue and ambient playback no longer overwrite one another.

• Trade resupply state is initialized and refreshed consistently. Traders retain the selected supply condition and refresh on the configured period instead of relying on incomplete descriptor state.

• Mod-only packages can intentionally omit engine binaries. pack mod --skip-engine no longer validates or requires a configured engine when it will not copy one, keeping a script/resource-only package independent of local engine selection.

• Camp performers return to idle after finishing. NPCs no longer remain stuck in guitar or harmonica animations after the corresponding camp story ends.

• Localized interface text retains its accents. French, Italian, Polish, and Spanish text no longer contains broken characters; the French, Italian, and Spanish options screens also label the world- and HUD-FOV controls.

• Boars and flesh recognise each other as friendly. Their relationship now matches vanilla’s monster-relation configuration rather than treating the species as neutral.

• Malformed quest condition lists are repaired. XRF fixes broken vanilla condition-list data in the Zaton B7 and B20, Jupiter B8, and Pripyat underpass B400 quest logic so the conditions parse and evaluate as intended.

• LTX validation covers game-script runtime schemes. Common physical, restrictor, monster, stalker, weather, sound, task, and model sections declare strict $scheme types so malformed fields and condition lists can be caught before runtime.

• Literal NPC-name checks. NPC-name conditions now compare requested text literally while retaining the fast indexed loop. This prevents Lua pattern characters in a requested name from changing the match.

• Dirty smart-terrain work has a global budget. Reselection work is queued, deduplicated, and limited per frame and per second instead of letting every invalidated terrain run at once.

• The Jupiter guide transition uses the intended fade and handoff. First arrival as a visitor starts the missing black post-process, stops it after the welcome delay, and lets the guide enter its first-visit state when the journey condition applies.

• Actor controls use persistent, ordered locks. Overlapping systems such as cutscenes, surge survival, and anabiotic sleep keep their input/UI lock until release, so one cannot restore controls held by another.

• Tracy profiling tools and engine variants are bundled. XRF includes capture, viewer, export, and trace-import utilities together with gold-tracy and release-tracy engines. The older Lua-hook profiler was removed.

• The LR300 sights align correctly. Adjusted HUD offsets remove the rifle’s misaligned aim view in both standard and 16:9 layouts.

• Smart-terrain maintenance adapts to distance. Job maintenance is throttled by actor distance, while arrivals, departures, and state changes still mark the terrain for selection. The introducing change reports about 30% less per-frame job-processing work; it is not a general FPS benchmark.

• Weather updates run on a 2.5-second actor cadence. The weather manager uses the actor binder’s throttled event instead of running on every actor update.

• Unvisited restrictors check the actor at an interval. Map-discovery restrictors accumulate elapsed time and test the actor position only at the configured interval instead of every update.

• Physical-object callbacks follow the online lifecycle. Hit, death, and use callbacks are installed once when an object comes online and cleared when it goes offline instead of being reassigned on every render update.

• Scripted physical buttons no longer fail while logging their use. Logger format arguments now match their placeholders in physical-object and treasure paths.

• Resolved condition and effect functions are cached. Parsed condition-list entries retain their resolved xr_conditions or xr_effects function reference after the first lookup.

• Squad target outrank checks are staggered. Simulation no longer performs every squad’s full target-outrank check at once; it uses staggered rechecks and caches terrain-assignment counts.

• Squads reuse unchanged ALife tasks. A squad retains its simulation task while its graph vertex is unchanged, avoiding repeated task allocation.

• Game-graph lookups and distances have bounded caches. Repeated level-name, vertex-level, and graph-distance queries reuse session-stable values; the distance cache has a fixed size.

• Smart-terrain job selection is incremental. Clean updates retain valid jobs and probe a bounded number of higher-priority candidates instead of reselecting every job.

• NPC sound themes are registered on demand. Sound setup defers theme registration until a sound is actually needed instead of preparing every possible theme for every spawned NPC.

• The save dialog tests real file existence. Existing-save detection uses the engine file object returned by FS.exist, so the overwrite warning follows the binding’s actual result type.

• X-Ray 16 SDK integration is upgraded to v2. The earlier xray16 package adoption expands to shared Lua helpers, mocks, and TypeScript aliases, and the remaining local copies are removed.

• Texture quality exposes the full engine range. The advanced-video slider always offers LOD values 0 through 4 instead of raising its minimum from an address-space probe.

• Scheme condition types are memoized. Scheme switching records the parsed condition type after the first evaluation instead of repeating Lua pattern matching on every update.

• Task updates are spread across time. Task objects randomize the next update interval, avoiding synchronized re-evaluation bursts while keeping periodic checks.

• Treasure statistics see condition-list emptying. A treasure cleared by an empty condition list emits the same TREASURE_FOUND event as other collection paths, so event consumers record it.

• Deimos cleanup removes the matching effectors. The reset path now removes the camera and secondary post-process effectors by their correct IDs.

• Cutscenes disable and restore the game UI. Cutscene setup and cleanup pass the UI-lock state expected by the actor-input manager, including restoration of the remembered weapon slot.

• Psy antennas play both channels. The psy-antenna loop uses both the left and right sound objects, restoring the intended stereo effect.

• Surges do not replay task-side effects when the hide task is disabled. The surge manager records the task stage even when the configured section is empty, preventing duplicate alarms, sounds, and weather effects.

• Task objects obey their update window. A task with a known state skips functor evaluation until the next scheduled update instead of using the inverted time check; title and description changes are then applied together.

• NPC torches turn off when their light is no longer needed. Stalker torch state is applied for both outcomes, so daytime NPCs no longer keep their lamps on after a night-time or danger state.

• Jupiter guide routes use the correct NPCs. Travel from Jupiter now resolves the Zaton guide and Pripyat assistant by their actual story IDs instead of selecting the wrong character.

• Disabled anomaly zones still update field switching. Turning a zone off suppresses artefact respawn but no longer prevents its configured anomaly fields from cycling.

• NPCs can use their configured cover chatter while approaching cover. A sound_idle configured for a cover scheme now plays both while the NPC moves to cover and after it has arrived.

• Close-combat state updates in one evaluation. When enemy memory is already stale, the camper evaluator can enter and clear close-combat state in the same evaluation instead of exposing an incorrect extra planner update.

• Patrols accept their full seven-NPC limit. The patrol manager now permits seven registered NPCs and rejects only an eighth participant.

• Exclusive smart-terrain jobs reserve a fallback slot. When an exclusive job’s suitable condition is false, the terrain retains an unconditional low-priority slot instead of leaving the NPC without a selectable job.

• NPCs can hold smart cover during combat. The missing combat action for use_in_combat is registered again, so the combat planner has an action to run without forcing the NPC out of its scripted cover.

• Helicopters follow the intended patrol movement math. The rewrite now uses vanilla’s square-root velocity formula, ignores repeated waypoint callbacks, and keeps a dying helicopter registered until its normal object teardown.

• Night predators wait until late night to hunt vegetarian monsters. The monster_predatory_night simulation role uses a 21:00-to-day-start window instead of the broader 19:00 night window.

• Zombied NPCs fire at their visible enemy. The standing fire state now passes the selected enemy as its target instead of losing that target while starting the firing animation.

• Critically wounded NPCs can still choose an enemy. Critical wounds take precedence over a combat-ignore override, allowing the NPC to fight back.

• Night vision is toggled from its actual state. XRF checks the device’s current state before changing it.

May 2026

• Bundled screen-space shader add-ons were removed. The interactive-grass and shadow-cascade extensions, color grading presets, shader selectors, and their options-page controls are no longer part of the engine package.

May 2025

• Script builds can inject Tracy zones. build --inject-tracy-zones instruments generated Lua for engine-level profiling with a compatible Tracy-enabled engine.

• The CLI can verify assembled gamedata. verify gamedata checks target/gamedata through the bundled XRF tools, with verbose and strict modes for deeper asset validation.

March 2025

• Generated NPC loadouts can use multiple sections and probabilistic attachments. Modders can generate separate loadout sections and configure scope, silencer, and launcher attachment probabilities.

January 2025

• XRF adopts an expanded particle library with a round-trip editing workflow. The CLI can unpack particles.xr into editable LTX files, repack those files, and verify both representations.

December 2024

• Dead creatures ignore late sound callbacks. Stalker and monster binders decline hearing events after death instead of forwarding them into danger and scripted sound logic.

• Weapon inventory icons match their items. The Protecta and Winchester 1300 use corrected icon-grid positions in inventory and trade interfaces.

• Teleport effects play their intended tinnitus sound. The actor-teleport helper uses the engine’s sound-path separator so its 2D sound resolves.

• The debug panel can dump live Lua state. Managers contribute bounded diagnostic data to _appdata_\\dumps\\lua_data.json, and the existing merged-system.ini dump uses the corrected file-writing path.

• The runtime exposes extended engine callbacks. OpenXRay/CoC hooks cover save/load completion, level changes, server-object removal, input, inventory focus and trade filtering, AI visibility, and weapon selection.

August 2024

• Translation workflows use the native XRF tools. Translation builds moved to the bundled JSON/XML converter in July; initialization and validation followed in August, replacing their separate Node implementations.

May 2024

• Advanced video options expose renderer-specific controls. The menu includes shadow-map quality and tessellation where supported, plus the always-active window setting.

• AF3 weather cycles replace vanilla weather selection. XRF selects af3_* weather sections from a dynamic AtmosFear graph, including moon-phase variants for clear and partly cloudy periods. It ships the matching weather, ambient-channel, and weather-effect configuration.

• Original new-game spawn position. XRF can set the vanilla start vertex and position only while creating a new game, leaving loaded saves untouched.

• Equipment icons have a round-trip editing workflow. The resource sprite is split into per-item source images, and the CLI can unpack or rebuild the combined equipment texture and its descriptors.

• Jupiter scanner spots show the right artefact information. After the scientist scanner reward, map hints update the existing spot with the current artefacts or an empty notice, including the corrected JUP B211 target and hint.

• Map-display maintenance uses a shared five-second actor event. Terrain and sleep markers use the throttled ACTOR_UPDATE_5000 event instead of a per-actor-update callback and timer.

March 2024

• Bundled native XRF tools are available to the project CLI. Their first integration provides reproducible LTX formatting and verification, including a non-writing formatter check mode for local use and CI. Later workflows use the same tools for translations, icons, particles, assembled gamedata, and extern manifests.

• The CLI can unpack ALife spawn data. spawn unpack converts the configured all.spawn into an inspectable output tree with path, destination, force, and verbose controls.

• LTX verification understands typed project schemas. verify ltx checks includes, inheritance, section types, required fields, and the initial $scheme declarations. Runtime game-script coverage expands in July 2026.

February 2024

• Engine switching tolerates broken links. The CLI can replace a corrupted engine symlink instead of failing while trying to inspect its target.

January 2024

• Gameplay XML can be authored as typed TSX. The config builder renders gameplay TSX into XML, allowing character profiles, dialogs, and related generated data to share components and helpers.

• NPC character descriptions and loadouts use typed generators. Reusable faction, profile, weapon, food, drug, and item presets replace hand-maintained XML spawn lists while retaining counts, condition, probability, and attachment flags.

• Optional screen-space shader presets were added. Players could select new or vanilla shader packages, choose color grading, and enable interactive grass and shadow cascades. These bundled add-ons were removed in May 2026.

• Disabled extensions no longer crash save loading. Extension restoration checks for an unregister hook before calling it, so a disabled module can load safely even when it does not define one.

• Achievement reward caches replenish. Achievement rewards extension records the Detective and Mutant Hunter awards in save data. Every 12 in-game hours after an award, it replenishes the configured medical supplies or armour-piercing ammunition in the Zaton or Jupiter reward box and posts a notification. Players can turn it off from the Extensions menu.

• Saving does not create an inactive psy controller. Save/load code serializes the psy-antenna manager only when it already exists, avoiding state changes caused solely by saving the game.

• Signal lights restore their flight state after loading. Scripted flare force, particles, and timing resume from saved state instead of being left partially initialized.

• Generated character loadouts retain their first item. The character-description builder emits a spawn section that preserves the first configured supply item.

December 2023

• XRF removes its authored multiplayer menu. Multiplayer login, server, profile, and demo classes and forms are deleted, leaving the project-owned main menu focused on single-player. Engine-required multiplayer-named UI definitions remain a separate packaging concern.

• Creatures restore a consistent online position. Stalkers and monsters use an explicit spawn vertex, remembered offline vertex, or assigned smart-terrain job position when synchronizing after net_spawn.

October 2023

• Randomized upgrades. The enhanced-items extension can add random upgrades when equipment first comes online.

• Progressive smart-terrain discovery. XRF initially hides smart-terrain map spots and blocks same-level travel to a terrain until the actor has visited it.

• Extensions can be enabled and disabled from the menu. Modules that allow toggling expose the control in the Extensions dialog, and disabled modules are skipped during registration.

• An optional start-position extension is introduced. Its first version applies an alternative position only to a new game started on Zaton. It was later reworked into the Original start position extension.

• Post-combat idle has a shorter default delay. NPCs wait 5 to 10 seconds after combat instead of vanilla’s 10 to 15 seconds. An explicit post_combat_time value still overrides the default.

• Vendor-logo videos are skipped by default. XRF disables the GSC, ATI, and AMD sequence; the intro renders an empty image item instead.

September 2023

• Translation tooling expands to eight locales. English, French, German, Italian, Polish, Russian, Spanish, and Ukrainian sources can be initialized, merged with imported JSON, and checked for missing or invalid strings.

• The development panel adds registry filters, profiling, and quest controls. Developers can filter live objects, time selected runtime portions, and inspect or manipulate task state.

• Verbose runtime systems can write dedicated logs. Selected managers can write to their own file, either alone or alongside the main engine log.

• World-object lifecycle events are available to runtime modules. Actors, creatures, physical objects, zones, smart terrains, covers, helicopters, and inventory classes emit online/offline registration events.

• The browser UI preview command is removed. Form debugging moves to the bundled engine’s ImGui and in-game development tools.

• Advanced video options expose grass and window controls. Players can change grass detail height and radius and select an engine window mode instead of using the old fullscreen checkbox.

• NPC loading preserves the remembered level vertex. When optional script save data omits a vertex, the binder keeps the stored offline position instead of replacing it with an empty value.

• Psy antennas initialize sound with valid paths and intensity math. The manager starts its sound objects, resolves the tinnitus assets with engine separators, and uses cubic power rather than a bitwise XOR expression.

• Treasure icons show rarity. Treasure map marks can distinguish common, rare, epic, and unique stashes instead of using only the generic treasure icon.

• Off-level smart terrains maintain their jobs. Job creation, update, and selection are no longer skipped merely because the actor is on another level.

• Zombied danger actions require a living NPC. The planner uses the alive property instead of the unrelated ALife property when deciding whether a zombied stalker can move toward danger.

• The Jupiter B4 conversation uses a bound terrain check. Its predicate calls the local smart-terrain helper instead of an unavailable external, preventing the dialogue path from failing.

• Sleeping reliably opens its time-selection dialog. The sleep manager creates the dialog when needed, fixing the path where the sleep UI was absent.

• Field-of-view controls are available in the options UI. XRF adds world-FOV (55 to 115) and HUD-FOV (0.40 to 1.00) sliders to advanced video options.

• Game packages seed explicit FOV values. pack game copies XRF’s root user.ltx, setting initial world FOV to 80 and HUD FOV to 0.7. Players can change these starter values in the XRF options UI.

August 2023

• XRF introduces a scripted dynamic-weather manager. It selects weather-graph states, changes good and bad periods, coordinates surges and time changes, and saves and restores its state.

• Engine declarations and build plugins move into the versioned xray16 package. The shared package replaces the earlier declaration submodule and becomes the base for the broader X-Ray 16 SDK integration.

• Advanced video options have separate frame caps. Gameplay and menu rendering use independent sliders for rs_fps_limit and rs_fps_limit_in_menu.

• The bundled OpenXRay engine adds broader input and UI support. The update includes keyboard and gamepad navigation for PDA, dialog, task-list, and message-box interfaces, plus renderer, audio, animation, grenade, and shutdown fixes.

• The bundled engine includes an ImGui UI debugger and more script hooks. Developers can inspect UI state with F10 and use additional Lua-visible UI callbacks added by the same OpenXRay rollup.

• NPC assistance can retarget while active. When a corpse-search or wounded-help evaluator selects another target, XRF reissues movement instead of keeping the original corpse or wounded NPC.

• Corpse-loot checks stop after the first valuable. Before selecting a corpse to loot, XRF stops inventory iteration when it finds the first valuable item. Vanilla’s evaluator scans the full inventory after setting its shared flag.

July 2023

• XRF supports modular gameplay extensions. It discovers and registers modules from the extensions directory, persists their load order, passes each module its descriptor, and lets extensions load relative LTX files or override the runtime system.ini. The main menu initially managed ordering; enable/disable controls followed in October.

• XRF save data has a separate sidecar. Runtime-specific dynamic data is stored beside each .scop save, and runtime systems can react before and after save or load operations.

June 2023

• Optional resource repositories can be cloned from the CLI. The command lists configured repositories and can clone a selected resource or locale payload with safe, force, and verbose modes.

• Development links can be rebuilt in one command. relink removes and recreates the configured game, gamedata, and log junctions, with an explicit force option when an existing target must be replaced.

• Development commands locate Call of Pripyat through Steam. XRF resolves Steam app 41700 automatically and uses the configured game path as a fallback.

• The CLI can format LTX files. The first formatter normalized line endings and surrounding whitespace.

• Existing translation XML can be imported. The translation workflow converts files or directories back into XRF JSON, detects or accepts the source encoding, and preserves multiline values.

• The development panel gains world-control tools. It can spawn squads and monsters, change actor relations, dump the merged system.ini, and teleport among levels, patrols, and positions.

• Runtime events include game start and game-time timers. Modules can subscribe to game start and register cancellable one-shot timeouts or repeating intervals driven by active game time.

• Static resource builds skip unchanged files. The builder compares source and target metadata before copying. It does not remove stale target files discovered by the comparison.

• ALife catches up briefly after actor reinitialization. XRF permits all ALife objects to update for the first three seconds after actor reinitialization, then restores the configured limit of 20 objects per update. This initializes the world promptly while retaining the normal update budget.

• Nearby weapon fire can put NPCs on alert. XRF passes heard sounds to the stalker danger controller. Eligible NPCs enter danger and move toward a nearby hostile shooter, or assist an ally engaging a mutual enemy. Vanilla’s hearing callback only evaluates configured on_sound transitions.

• Uncompressed game packages can copy the complete built tree. The pack workflow defaults to building and compressing, with explicit opt-out flags for loose-development packages.

April 2023

• The CLI uses one structured command surface. Build, engine, link, log, open, parse, start, and verification tools share subcommands, help text, and option parsing instead of being invoked as unrelated scripts.

• The CLI can create compressed packages and complete game builds. The first package workflow can build gamedata, compress database archives, and copy the configured engine and root payload into a distributable game.

• Packaging distinguishes mods from complete games. pack mod produces a mod-only layout, while pack game includes the configured standalone game payload. Complete game packages use the bundled gold engine by default unless another variant is selected.

• The development dialog gains modular inspection tools. Its sections inspect planner, inventory, registry, relation, scheme, weather, and ALife state and can spawn test items.

• Runtime state uses a central save lifecycle. Managers serialize through the save manager instead of embedding save/load orchestration in the actor binder.

• Surge shelter searches are level-scoped. The surge manager initializes the current level’s cover list and compares squared distances instead of scanning every configured shelter for each lookup.

• Gameplay options expose language and OpenXRay pickup controls. Players can change language and toggle simplified pickup, multi-item pickup, and automatic magazine unloading after pickup.

• The widescreen minimap has a corrected layout. XRF supplies separate 16:9 frame and background dimensions instead of reusing the standard-aspect form.

• Optimized packages can remove Lua logging. pack --optimize builds scripts with Lua logger calls stripped from the generated output.

• Game packages can ship compressed databases with only required loose runtime files. When compression is selected, the packer copies database archives and an explicit runtime gamedata allowlist.

• Build filters can target generated assets. build --filter first targeted generated forms and configs; June expanded it to static UI, configs, and resources.

March 2023

• Runtime and CLI code can be tested outside the game. The Jest harness supplies Lua and X-Ray stand-ins, while Fengari preserves important native Lua behavior for engine-facing TypeScript tests.

• The project is renamed from XRTS to XRF. Commands, documentation, artifact metadata, and repository references adopt the X-Ray Forge name.

• Automated workflows build and validate XRF artifacts. CI runs project checks and can publish assembled gamedata archives with source-revision metadata.

• LTX configuration can be generated from typed TypeScript. The builder supports sections, imports, root fields, and engine binding expressions, allowing generated configs to share constants and helpers.

• Translations are built from a shared multi-locale source. String tables are maintained in JSON and rendered to locale-specific engine XML with the required Windows-1251 encoding.

• Scheme transitions use direct condition dispatch. Active logic resolves each transition type and calls its mapped handler instead of traversing vanilla’s long sequence of Lua-pattern branches.

February 2023

• The script runtime is authored in TypeScript. XRF completed the migration of the vanilla Lua layer to TypeScript compiled through TypeScriptToLua, enabling source typechecking while still emitting Lua for X-Ray.

• Decorated TypeScript classes can implement engine-facing luabind classes. The compiler bridge emits the constructors, inheritance, methods, and properties expected by X-Ray.

• Large binary and resource payloads are versioned independently. Repository setup pins cli/bin and src/resources as submodules while the authored engine source remains in the main repository.

• Builds can layer separately versioned resources. Configured base, override, and locale roots are merged into the assembled gamedata. Locale selection and the option to omit additional override roots followed in April.

January 2023

• The CLI can verify a local XRF development setup. verify project checks the project configuration, game executable, selected engine, gamedata and log links, and configured resource roots.

• The CLI can serialize a directory tree as JSON. The parse command provides a machine-readable inventory for resource and generated-data maintenance.

• Runtime systems communicate through typed game events. Managers and extensions can subscribe, unsubscribe, and emit lifecycle and gameplay events without direct coupling.

December 2022

• The XRF project CLI assembles authored sources into runnable gamedata. Its first build pipeline compiles scripts and generates or copies configs, translations, UI forms, and resources into target/gamedata.

• Builds include output metadata. XRF records build flags and timing, host information, file counts, sizes, and the produced file list beside the assembled gamedata. Source-revision metadata followed in March 2023.

• The CLI manages a local Call of Pripyat development install. Developers can link gamedata and logs, start the game, inspect logs, open configured folders, and list, select, inspect, or restore bundled engines. The initial engine set included release, gold, and later mixed.

• The main menu includes a development dialog. F11 opens a debug panel with runtime-inspection and developer-control sections.

• UI XML can be generated from reusable TSX forms. Project-owned layouts are expressed as typed JSX components and rendered to engine XML during the build.

Credits

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

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

This community project is not affiliated with GSC Game World.

Installation

This 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 are exposed through TypeScript declarations from the xray16 package and the XRF typedefs under src/typedefs. Use the generated type documentation when checking engine class, method, and enum names:

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

Luabind classes

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

Building 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 and can also copy static XML translation files where they are part of the source tree. Use the translation CLI commands when converting existing game XML into JSON sources.

Building Resources

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

Commands

It builds and packages the project, manages resources and engine binaries, links a local game, and handles common format, spawn, particle, translation, and verification tasks.

See the command list for a quick index.

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.

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.

Commands and scripts

Run package scripts from the repository root:

npm run <script>

Run CLI commands through the local wrapper:

npm run cli -- <command>

Package scripts

• setup: initialize and update submodules.
• verify: run verify project.
• build: build scripts, configs, UI, translations, and resources.
• pack:mod: build a mod package.
• pack:game: build a game package.
• watch:scripts: rebuild scripts when TypeScript sources change.
• typecheck: run TypeScriptToLua type checking without emitting files.
• typecheck:tests: type-check test sources with TypeScript.
• lint: run ESLint 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.

CLI Commands

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

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

Build

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

npm run cli -- build

What it builds

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.

Icons

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

npm run cli -- icons <command>

Commands

Options

All icon commands support:

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

Description commands also support:

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

Examples

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

Workflow

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

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

Failure notes

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

Link

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

npm run cli -- link

What gets linked

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

Commands

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

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

Examples

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

Failure notes

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

Lint

Linting is exposed through package scripts, not a Commander subcommand. Use it for TypeScript, TSX, and CLI source 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 export-externs 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 unpack-spawn.

Options

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

Examples

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

Output

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

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

Failure notes

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

Start

start_game starts the configured game executable.

npm run cli -- start_game

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

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

Typical workflow

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

Inputs and output

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

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

Failure notes

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

Test

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

npm test

Common commands

Coverage output is written under target/coverage_report.

Examples

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

Notes

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

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

Translations

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

npm run cli -- translations <command>

Commands

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

Options

init supports:

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

to_json supports:

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

check supports:

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

Examples

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

Failure notes

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

Verify

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

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

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.

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 page for each app tool calls out what is currently wired.

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 Rust commands and a React UI. Use it for interactive inspection and one-off data operations; use the CLI for scripted work.

The application source is split across:

• 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

Project paths

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

Choose the CLI when

Use Tools CLI when the task must be repeatable, scripted, or run in CI.

Archive Editor

The archive editor opens X-Ray .db archive projects, shows their metadata, reads individual files as text, and can unpack them to a folder.

Screens

Backend commands

The Tauri archives-editor plugin exposes:

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

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

Workflow

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

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

CLI equivalent

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

Dialog Editor

The dialog editor is a prototype for dialog graphs. It is not a production workflow for dialog data.

Current routes

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

What is implemented

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

What is not implemented

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

Production workflow

For real dialog changes, edit the engine sources directly:

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

See Dialog configs for the current production documentation.

Config Editor

The config editor works with LTX projects. Verification and formatting are the currently wired workflows.

Screens

Backend commands

The Tauri configs-editor plugin exposes:

• verify_configs_path;
• check_format_configs_path;
• format_configs_path.

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

Workflow

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

CLI equivalent

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

Exports Viewer

The exports viewer reads declaration folders and shows exported conditions, dialog functions, effects, and parameters.

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

Screens

Backend commands

The Tauri exports-editor plugin exposes:

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

Source folders

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

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

Notes

The viewer is read-only. Edit the engine declaration sources, then reload the viewer.

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

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

Icon Editor

The icon editor works with equipment icon sprites and their descriptors. Opening a sprite and packing equipment icons are the fully wired workflows.

Screens

Backend commands

The Tauri icons-editor plugin exposes:

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

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

Workflow

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

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

CLI equivalent

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

Spawn Editor

The spawn editor reads and inspects ALife spawn data. It can open packed files, import and export unpacked folders, and save a packed file.

Screens

Data views

The backend exposes accessors for:

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

Backend commands

The Tauri spawns-editor plugin exposes:

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

Workflow

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

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

Safety

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

Translation Editor

The translation editor opens XRF translation projects for read-only inspection.

Screens

Backend commands

The Tauri translations-editor plugin exposes:

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

Both open/read paths use TranslationProject::read_project.

Workflow

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

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

Limitations

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

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

CLI equivalent

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

Tools CLI

The Rust xrf-cli binary provides repeatable asset inspection, conversion, packing, unpacking, formatting, and verification outside the engine repository wrapper.

xrf-cli <command> --help

The engine CLI wraps selected operations through npm run cli -- .... Use xrf-cli directly for scripts and format-specific workflows.

Command groups

Logging

Some commands offer --silent or --verbose. Rust logging honors RUST_LOG when it is set.

Read and write commands

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

Use explicit input and output paths when documenting or scripting a command. Some commands use named options such as --path and --dest; verify-gamedata uses its assembled gamedata root as a positional operand. Explicit paths make generated assets easier to reproduce.

Usage pattern

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

When running from the engine repository, prefer the engine CLI wrapper if it already exposes the workflow. Use xrf-cli directly when you need a lower-level command that the engine wrapper does not register. On Windows, use xrf-cli.exe or the bundled path under cli/bin/tools.

Archive CLI

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

pack-archive

pack-archive builds database archives from a folder, replacing the xrCompress tool of the original SDK.

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

A set that fits in one volume is written as <name>.db; a larger one splits into <name>.db0, <name>.db1 and so on. The engine mounts any file whose extension starts with db or xdb, so the index is a convenience rather than a requirement. Files the engine expects compressed are compressed and the rest are stored, matching what the engine loads. Identical files are stored once and referenced twice.

Give the archive a [header]. Without one the engine assumes a .db is an encrypted Shadow of Chernobyl archive and decrypts it into nonsense; --xdb is the other way to say an archive is not that.

Options

• -p, --path <path>: folder to pack, normally a gamedata root. Required.
• -d, --dest <dest>: destination folder for the volumes. Defaults to packed.
• -n, --name <name>: base name of the volumes. Defaults to gamedata.
• --ltx <path>: configuration file selecting what to include. Options given on the command line win over it.
• --store: store every file instead of compressing.
• --max-size <megabytes>: maximum volume size. Defaults to and is capped at 1900.
• --xdb: write volumes with the xdb extension.
• --no-skip-list: keep editor and source leftovers the game build normally drops.
• -s, --silent: disable command logging.

Configuration file

Without --ltx the whole folder is packed. The file uses the same dialect xrCompress accepted:

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

[include_folders]
configs = true
scripts = true

[include_files]
gamemtl.xr

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

[include_folders] and [exclude_folders] map a path to whether it applies recursively; .\ names the packed root. [include_files] lists names one per line. [header] is written into the archive verbatim, and its entry_point is where the engine mounts the contents, so an archive of a gamedata tree needs it.

unpack-archive

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

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

Options

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

Relative destination paths are resolved from the current working directory.

Output

Without --silent, the command prints:

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

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

Examples

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

Failure notes

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

Gamedata CLI

Gamedata commands validate one assembled gamedata directory. Run them after building gamedata and before launching or packaging it.

verify-gamedata

xrf-cli verify-gamedata ./target/gamedata

ROOT is the required positional path to the assembled gamedata directory. The command reads configs from ROOT/configs and requires ROOT/configs/system.ltx.

Options

• -i, --ignore <names...>: ignored files or folders. Multiple names are comma-separated.
• --checks <checks...>: selected verification checks. If omitted, all checks run.
• --report <path>: write a JSON verification report.
• --silent: disable logging.
• -v, --verbose: enable verbose logging.
• -s, --strict: fully validate expensive asset payloads.

Accepted check names are animations, levels, ltx, meshes, particles, particles-usage, scripts, shaders, sounds, spawns, textures, weapons, and weathers. The script check parses emitted .script files with the LuaJIT syntax dialect.

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

Checks and rules

A check is a group of related verification, selected with --checks. Inside a check, each individual violation is attributed to a rule, and the rule identifier is what appears in findings and in the JSON report. Rule identifiers are <check>.<rule>:

checks.execution is reported when a check itself fails to run, rather than when content is invalid.

The animation rules validate player HUD and item motions. Missing item motions are allowed where the engine falls back to idle; duplicate motion names across banks in one HUD namespace are reported because their resolution is ambiguous.

textures.bump resolves the bump each .thm declares the way CTextureDescrMngr::LoadTHM does, by the name in the descriptor rather than by a _bump suffix convention. A name that resolves to nothing still takes the _bump shader path, because bump_exist() only checks the name is non-empty: the loader substitutes ed\ed_dummy_bump and logs ! Fallback to default bump map on every load, so the surface is flat and the log is noisy. Importing a texture under a new path is the usual way to produce one, since the copied descriptor keeps pointing into the source layout. Repoint it with patch-thm-bump --to, or patch-thm-bump --off when the bump does not exist and is not going to.

JSON report

Pass --report to write the result for CI or other tooling:

xrf-cli verify-gamedata ./target/gamedata --checks sounds,weathers --report ./verification-report.json

The report is a single object with camelCase keys:

{
  "checks": [
    {
      "durationMs": 114,
      "findings": [],
      "status": "passed",
      "summary": "122/122 weather files valid",
      "verificationType": "weathers"
    }
  ],
  "durationMs": 311,
  "status": "passed"
}

status is one of passed, failed, error, incomplete, or skipped. The top-level status is the most severe individual status. incomplete means a check could cover only part of its expected input; durationMs is null when a check did not run.

Each entry of findings describes one violation:

Findings are ordered by asset path, rule, then message, so two reports over the same gamedata can be compared directly.

Examples

xrf-cli verify-gamedata ./target/gamedata
xrf-cli verify-gamedata ./target/gamedata --checks scripts,ltx
xrf-cli verify-gamedata ./target/gamedata --checks weathers
xrf-cli verify-gamedata ./target/gamedata --checks sounds --strict
xrf-cli verify-gamedata ./target/gamedata --report ./verification-report.json
xrf-cli verify-gamedata ./target/gamedata --ignore .git,textures_unpacked --strict

Result

The command exits with a non-zero status unless the overall result is passed, including when verification is skipped or incomplete. In normal logging mode it prints each failure message before exiting.

The command validates the files present in the assembled tree, including generated scripts and configs. It does not validate source repositories or files that were not included in the build.

LTX CLI

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

format-ltx

Formats one file or every LTX file under a folder.

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

Options:

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

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

verify-ltx

Verifies an LTX project folder, including its schemes and case-sensitive include paths.

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

Options:

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

Failure notes

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

Only sections that declare $schema 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.

OGF CLI

OGF commands inspect X-Ray model files and safely rewrite motion or texture references.

Commands

info-ogf

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

Options:

• -p, --path <path>: path to an .ogf file. Required.
• -s, --silent: disable logging.
• -v, --verbose: turn on verbose logging, which lists each level of detail individually.

Output

The command reads the model and prints available metadata:

• header version, model type, shader id, bounding box, and bounding sphere;
• texture and shader names;
• description chunk data when present;
• bones and parent names when present;
• motion references when present;
• progressive mesh level of detail counts when present;
• unparsed chunk ids, so an incomplete read is visible rather than silent;
• child model texture, shader names, and level of detail counts for nested OGF data.

Progressive level of detail data usually belongs to the nested child visuals rather than the root, so expect the [n] progressive lods lines rather than a single figure for the model. Pass -v to list each level with its index buffer offset, triangle count, and vertex count.

When to use it

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

The command is read-only: it does not rewrite chunks, normalize paths, or repair model data. If a model fails to parse, first confirm the file is an OGF from the expected game version, then compare the reported failure with neighboring meshes from the same source archive.

patch-ogf-motion-refs

An animated model stores the paths of the OMF files it loads animations from. This command rewrites those paths, which is what lets a model be moved to a different directory layout without re-exporting it from the SDK.

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

Options:

• -p, --path <path>: path to an .ogf file. Required.
• -d, --dest <dest>: path to the resulting file. Defaults to rewriting the source file in place.
• -r, --refs <refs>...: one or more motion references to store. Required.
• --dry-run: report what the rewrite would produce without writing anything.

Paths use backslashes and omit the .omf extension, matching how the engine resolves them. A reference ending in \*.omf is a wildcard: the engine loads every OMF in that directory.

What is preserved

Only the motion references chunk is rebuilt. Every other chunk, including geometry, bones and IK data, is copied byte for byte, so patching cannot alter the model itself.

The source file’s chunk form is also preserved. Older models store references as one comma-separated string, newer ones store a counted list; a file keeps whichever form it already used rather than being silently upgraded.

Safety checks

Model geometry cannot currently be re-serialized from parsed data, so the command verifies rather than assumes:

• Before writing, it rewrites the file’s existing references and requires the result to reproduce the source byte for byte. If it does not, the chunk copy would be lossy for that file and the command refuses to touch it.
• After writing, it reads the result back and requires the references to match what was requested.

If the second check fails, the write is undone: an in-place edit is restored from the original bytes, and a separate destination file is removed. A model without a motion references chunk is refused before anything is written.

When to use it

Use it when relocating animation banks, for example when consolidating per-weapon hand animations into one shared directory and pointing every hands model at it with a wildcard. Confirm the result with info-ogf.

patch-ogf-texture-refs

A model stores the path of every texture it uses. This command renames one of those paths, which is what lets an imported texture follow your project’s naming without re-exporting the model.

xrf-cli patch-ogf-texture-refs --path ./meshes/wpn_ak74u.ogf --from "wpn\wpn_aksu\wpn_aksu" --to "wpn\wpn_ak74u\wpn_ak74u"
xrf-cli patch-ogf-texture-refs --path ./model.ogf --dest ./model.patched.ogf --from "old\name" --to "new\name" --dry-run

Options:

• -p, --path <path>: path to an .ogf file. Required.
• -d, --dest <dest>: path to the resulting file. Defaults to rewriting the source file in place.
• --from <name>: the texture reference to rename, matched exactly. Required.
• --to <name>: the reference to write in its place. Required.
• --dry-run: report what the rewrite would produce without writing anything.

It also accepts -s, --silent and -v, --verbose. Paths use backslashes and omit the extension. Matching is exact; rename one source name per run.

Texture names live inside nested child visuals. The command walks those children and rebuilds every texture chunk whose name matches, including when the replacement has a different length.

What is preserved

Only matching texture chunks are rebuilt. Every other chunk, including geometry, is copied byte for byte; each paired shader name is preserved.

Safety checks

The command applies three guards:

• Before writing, it renames the reference to itself and requires a byte-for-byte copy of the source.
• A --from that matches nothing is refused, and the error lists the references the model actually has, so a typo cannot pass as a silent no-op.
• After writing, it reads the result back and requires the old name to be gone and the new name to be present.

If the final check fails the write is undone: an in-place edit is restored from the original bytes, and a separate destination file is removed.

When to use it

Rename the texture files first, patch every model that referenced them, then confirm with info-ogf and verify-gamedata. A missed model leaves a dangling reference.

OMF CLI

OMF commands inspect, re-serialize, and edit the motion set of X-Ray motion files.

Commands

How motions are stored

Both editing commands rely on the same structure, which is worth knowing before using them.

A motion file holds two parallel lists: motion definitions, which carry the name and playback parameters, and motion payloads, which carry the keyframes. They are paired by position. The engine looks a motion up by its definition name and then reads the payload stored at the same position, so the two lists must always be filtered and renamed together. Both commands maintain that pairing; the names an LTX anm_* key refers to are the definition names.

info-omf

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

Options:

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

Output

The command reads the motion file and prints:

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

With -v, each motion is listed individually with its keyframe count, flags, speed, power, accrue, and falloff. Keyframes and speed together give the effective duration. The flags matter more than they look: bit 0b10 means the motion plays once and stops, and a motion without it loops forever. Vanilla idles read 0b00 while draw, shoot and bore motions read 0b10.

When to use it

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

The command is read-only and prints the parsed structure; it does not merge, split, or repair motion files. If an expected animation is absent, check the source OMF first and then inspect the model or config that references the motion name.

repack-omf

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

Options:

• -p, --path <path>: path to an .omf file, or to a directory containing .omf files. Required.
• -d, --dest <dest>: path to the resulting .omf file. Required when writing a single file. Rejected when --path is a directory.
• --verify: compare the re-serialized bytes against the source instead of writing output.

The command has three modes:

• Write. A file path plus --dest reads the source and writes a re-serialized copy.
• Verify one file. A file path plus --verify re-serializes in memory and compares against the source bytes. Nothing is written.
• Verify a directory. A directory path walks it recursively, verifies every .omf beneath it, and prints a summary. Nothing is written, and --dest is rejected.

Unmodified files round-trip byte for byte. The writer preserves the original chunk order and reproduces the nested motion chunk ids, so a repacked file that differs from its source indicates a real change, not serialization noise.

When to use it

Use directory verification as a regression check after changing OMF parsing or serialization, and before relying on generated motion banks. Because it fails on any mismatch, it works as a build or pre-commit gate.

Use single-file write mode when you need a normalized copy of a motion file.

filter-omf-motions

Shared animation banks often carry motions for many weapons at once. This command extracts the subset you need.

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

Options:

• -p, --path <path>: source .omf file. Required.
• -d, --dest <dest>: resulting .omf file. Required.
• -k, --keep <name>...: exact motion names to keep.
• --keep-prefix <prefix>...: keep motions whose name starts with the prefix.
• --dry-run: report the outcome without writing anything.

At least one of --keep or --keep-prefix must be given, and a motion is kept if it matches any of them. Prefixes are matched literally, so ak_74_ and ak74_ select different motions.

Surviving definitions are renumbered so their internal motion index stays consistent with their new position.

--dest is required rather than defaulting to an in-place rewrite. Trimming a shared bank in place would destroy it for every other weapon that sources from it, and the input is often a read-only reference dump.

rename-omf-motions

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

Options:

• -p, --path <path>: source .omf file. Required.
• -d, --dest <dest>: resulting .omf file. Required.
• -m, --map <map>: JSON object mapping existing motion names to new ones. Required.
• --strict: require every motion in the file to appear in the map.
• --dry-run: report the outcome without writing anything.

The map is a flat JSON object:

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

Motions absent from the map keep their current name. Pass --strict when a file is meant to be fully normalized; it fails and lists the motions that have no entry, which is the difference between a deliberate partial rename and an incomplete map.

Renaming updates the definition name and the payload name together, so the new name is what the engine resolves.

duplicate-omf-motion

Copies one motion under a second name, so a bank can provide an animation it does not ship.

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

Options:

• -p, --path <path>: path to an .omf file. Required.
• -d, --dest <dest>: path to the resulting file. Defaults to rewriting the source file in place.
• --from <name>: motion to copy, matched exactly. Required.
• --to <name>: name to give the copy. Required.
• --play-once: clear looping on the copy so it plays once and ends.

Both the definition and the keyframe payload are duplicated rather than aliased, and the copy is pointed at its own new payload slot. That is deliberate: motion definitions and payloads are ordinal pairs, and a definition without a payload would break every later filter or rename. The file grows by one animation’s worth of keyframes.

An unknown --from, or a --to that already exists, is refused rather than producing an unreachable motion.

Why --play-once exists

Some engine states are left only from the animation end callback. Bore is the one that bites: OnAnimationEnd switches it back to idle, and nothing else does. Point anm_bore at a looping motion and the weapon sits in the bore state indefinitely, appearing frozen until some other action forces a state change.

That is the situation when an imported animation pack ships no bore at all. Copying the weapon’s idle and clearing its loop yields a motion that holds the idle pose and then ends, which is enough for the engine to leave the state. Confirm the result with info-omf -v: the copy should read 0b10.

Shared options

All commands accept -s, --silent to disable logging and -v, --verbose to enable verbose logging. Under filter-omf-motions and rename-omf-motions, --verbose prints the resulting motion list.

Under repack-omf, --verbose additionally reports every file that verified as byte identical. Without it, verifying a directory prints only mismatches, read failures, and a closing summary, and verifying a single file that passes prints nothing at all. Scripts can therefore treat single-file verification as silent on success and rely on the exit status.

Failure notes

repack-omf exits with a non-zero status when any file mismatches or cannot be processed. In directory mode it also reports the count of mismatched and errored files. A successful run exits zero.

A file that cannot be read fails before anything is written. The most common cause is a truncated source: a chunk header declares more bytes than the file actually contains. Such files are damaged at the source and need to be re-extracted, usually from the original packed archive with unpack-archive rather than from an unpacked dump.

Writing rejects data it cannot represent faithfully rather than emitting a corrupt file. Motion marks exist only in version 4, so writing a version 3 file that carries marks fails, as does writing a file whose motion count and motion definition count disagree.

The editing commands refuse work that would produce a file the engine cannot use, before writing anything:

• filter-omf-motions fails when no motion matches, since an empty motion file is not useful and the usual cause is a mistyped prefix.
• rename-omf-motions fails when the map matches nothing, and when a rename would give two motions the same name, because lookups are by name and a duplicate makes one of them unreachable.

Particle CLI

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

Commands

Examples

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

Shared options

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

Failure notes

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

Spawn CLI

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

Commands

Examples

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

Options

pack-spawn:

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

unpack-spawn:

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

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

Failure notes

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

Texture CLI

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

Commands

DDS inspection

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

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

Region cropping

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

--source, --output, --x, --y, --width, and --height are required. Coordinates start at the top left. An out-of-bounds region is rejected rather than truncated. The command also accepts -s, --silent and -v, --verbose.

The .png extension selects lossless PNG; any other name produces a BC3 DDS. Prefer PNG as a later packing source to avoid another lossy decode and encode. pack-equipment-icons prefers <section>.png over <section>.dds.

Use this to lift a single icon out of a sprite sheet when the sheet belongs to another project, where unpack-equipment-icons cannot help because that project’s configs do not declare $inventory_icon.

Fitting into different bounds

--fit-width and --fit-height scale the cropped region after cropping. They must be given together.

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

Scaling preserves aspect ratio and centers the result on a transparent canvas instead of stretching it. A matching region is unchanged. pack-equipment-icons uses the same fitting for mismatched icons.

Fitting matters where a target rectangle is fixed by an XML texture description, since pack-texture-description requires the file to match the declared size exactly and does not rescale.

Equipment icons

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

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

Both commands act only on sections with $inventory_icon = true and all four grid fields: inv_grid_x, inv_grid_y, inv_grid_width, and inv_grid_height. Grid fields alone do not opt a section in; $inventory_icon = false excludes it.

The explicit flag matters because inherited grid fields are common on abstract base sections that have no icon of their own.

Without --strict, an opted-in section whose icon file is missing is skipped with a warning. With --strict the command packs nothing and reports every such section in a single error, so the whole list can be fixed in one pass.

Checking the grid before moving an icon

xrf-cli verify-equipment-icons --system-ltx ./configs/system.ltx

Reports every pair of sections whose grid rects cover a shared cell, with the cell and how many cells overlap, and exits non-zero when any are found.

This covers a case packing cannot. pack-equipment-icons warns when two sections write different art to the same slot, which is the common and usually harmless case, because variants such as _nimble, _snag and the pri_a15_ quest copies inherit their base weapon’s position by design. Identical rects are therefore not reported here either.

What it catches instead is a rect reaching into a neighbour: widen a 1x1 icon to 2x1 and it may quietly take a cell another weapon already occupies. Both pack without complaint, and whichever writes last wins those pixels, so the loser silently shows the wrong art. Run this before widening or relocating any icon, and again afterwards.

Grid coordinates are cells, not pixels; a cell is 50x50, hardcoded in the engine.

Bump declarations

A texture’s bump map is not found by naming convention. CTextureDescrMngr::LoadTHM reads the .thm beside the texture and takes its bump name verbatim.

A name that resolves to nothing does not turn bump mapping off. bump_exist() only tests that the name is non-empty, so the renderer still selects the _bump shader variant, and the loader substitutes ed\ed_dummy_bump while logging ! Fallback to default bump map: <name> on every load. The surface renders flat while still paying for the bump path, and the log fills with fallbacks.

This bites whenever a texture is imported under a different path than it had at its source, because the copied descriptor keeps pointing into the source layout. On renderer_r4 the bump is consumed through CTexture::Preload, so it is not a setting the player can opt out of.

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

--path is required, plus either --to or --off. --dest writes elsewhere instead of rewriting in place, --dry-run reports what would change without writing, and -s, --silent and -v, --verbose control logging. The bump name is engine style, backslash separated and without an extension.

For a bump that does not exist and is not going to, declare none rather than leaving a dangling name:

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

--off sets mode to none and clears the name, which is the form STextureParams itself writes, so the result stays diffable against vanilla. Prefer it over leaving the name in place: a dangling name still selects the bump shader path and still logs a fallback on every load.

Omitted fields keep their existing value, so --to alone preserves a use_parallax mode across a rename.

The patch rewrites only the bump chunk and copies every other chunk byte for byte. It first proves that rewriting the declaration the file already has reproduces the source exactly, then confirms the written file reads the requested name back, and reverts rather than leaving a half-written descriptor behind.

Run verify-gamedata -c textures afterwards: it resolves every declared bump the same way the engine does and reports the ones that point at nothing.

Texture descriptions

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

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

A description can name several sheets; both commands rewrite all of them by default. Repeat --file <name> to select one or more. Use the declared path (ui\ui_actor_weapons) with either separator, or an unambiguous bare name (ui_actor_weapons). Missing and ambiguous names are errors.

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

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

Translation CLI

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

Commands

Initialize

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

Options:

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

Build

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

Options:

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

Verify

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

Options:

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

Notes

Use the engine repository’s npm run cli -- translations ... workflow to convert original X-Ray XML string tables to XRF JSON sources.

Extern exports

export-externs reads TypeScript extern(...) declarations.

xrf-cli export-externs <declarations-root> --format json --output <path>

Manifest source paths are relative to the declarations root.

Formats

• json: tracked { "exports": ... } contract; CRLF by default.
• xml: <externs><exports> document; LF by default.
• html: collapsed namespace reference; LF by default.

Use --line-endings lf|crlf to override the default.

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

Check

--check <artifact> validates without writing and cannot be combined with --output.

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

The format is inferred from the extension unless --format is provided. JSON is compared semantically; XML and HTML are compared as rendered text with line-ending differences ignored.

The engine wrapper is npm run cli -- verify externs. It is not a build or CI gate.

Requirements

Names must be unique string literals. Missing or unrenderable callable types are emitted as unknown. Values need value as Type. The command skips *.test.ts, *.spec.ts, and __test__ sources.

Useful Links

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

X-Ray Engine and Modding

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

Asset Tools

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

Development Tools

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

Game SDK

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

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

When to Use the SDK

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

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

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

OpenXRay Reference

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

• OpenXRay repository
• OpenXRay game editor wiki

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

Boundary with XRF

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

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

Common handoff pattern

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

Lua Debugger

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

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

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

Breakpoints

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

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

Practical workflow

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

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

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

Visual Studio Lua Debugger Research

The previous research link for Lua debugging is:

• LuaDkmDebugger
• LuaDkmDebugger pull request 26

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

Related Pages

• Debugging engine
• Logs
• Building scripts

Debugging

Start with the narrowest tool that can explain the problem. Most XRF issues can be isolated with a focused build, runtime logs, and the debug panel before a native engine debugger is needed.

Choose the right tool

The XRF debug panel can inspect objects, managers, tasks, treasures, memory, profiling, and merged runtime data without leaving the game.

Basic workflow

1. Reproduce the issue with a known engine variant and save.
2. Rebuild only the affected target when possible.
3. Check the engine and Lua logs for the first relevant error.
4. Inspect live state with the debug panel or an engine overlay.
5. Reduce the problem to a focused test, config section, scheme, or engine API call.
6. Verify the fix with the same engine, save, and reproduction steps.

Do not build scripts with --no-lua-logs while investigating runtime behavior. Use a disposable save for console commands, object mutation, teleportation, or forced weather changes.

AI and logics

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

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

Capture an NPC

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

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

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

AI overlays

Enable stalker and monster overlays from the console:

ai_dbg_stalker on
ai_dbg_monster on

ai_dbg_stalker on renders debug details for stalker objects:

ai_dbg_monster on renders debug details for monster objects:

Use the matching off command to hide each overlay.

Planner and scheme logs

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

The object section can print:

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

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

Performance stats

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

rs_stats on
ai_stats on

The AI stats overlay shows rows in this shape:

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

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

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

Useful console commands

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

AI debug console commands

Engine debugging (C++)

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

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

Set up the engine project

OpenXRay has build guides for both supported development paths:

• OpenXRay Windows build guide
• OpenXRay Linux build guide

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

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

Debug Lua from Visual Studio

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

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

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

What to debug in C++

Use the engine source when you need to verify:

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

Limitations

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

Debug with logs

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

Find the logs

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

Common files are:

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

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

Check the logs

With a prebuilt engine:

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

With Visual Studio:

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

Print logs with the CLI

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

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

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

Write Lua logs

Use LuaLogger from runtime code:

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

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

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

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

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

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

Flushing

Use the engine flush console command after generating important logs:

flush

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

Build-time logging flag

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

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

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

Debug UI forms

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

Source and runtime files

Most UI work touches one of these areas:

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

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

Check the form path

Runtime code usually resolves a form by path:

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

If a form does not appear, verify:

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

Use engine UI debugging

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

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

show_wnd_rect_all 1
show_wnd_rect_all 0

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

Common failure points

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

References

• OpenXRay UI debugger article

Circular references

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

Manager resolution

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

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

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

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

Trace module loading

forge.ltx has a debug flag for logger creation:

[debug]
resolve_log_enabled = true

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

Turn it back off after the investigation:

[debug]
resolve_log_enabled = false

Dump circular data

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

"<circular_reference>"

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

"<depth_limit>"

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

Practical checks

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

Generate externals documentation

extern.json records the Lua-visible externs declared in TypeScript.

Regenerate

From the engine repository:

npm run cli -- build --include externs

This writes:

src/engine/declarations/extern.json
target/gamedata/extern.json

Check

npm run cli -- verify externs

The check compares the tracked JSON with current declarations and does not write files.

For optional HTML or XML references, use Extern exports.

Run custom scripts

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

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

Run a script file

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

run_script my_debug_script

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

Run one Lua expression

Use run_string for a single Lua command:

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

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

XRF helper examples

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

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

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

Safety

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

Performance statistics

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

Rendering and frame statistics

Use these console commands while the game is running:

rs_stats on
rs_fps on
rs_fps_graph on

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

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

AI statistics

For AI scheduler and planner timing:

ai_stats on

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

Lua profiling

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

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

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

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

Manual profiling portions

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

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

// Code to measure.

portion.commit();

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

Weather

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

Runtime weather flow

On actor network spawn, the manager:

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

During actor updates, it:

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

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

Change weather from scripts

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

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

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

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

level.set_weather(weatherName, isForced);

For weather effects, the engine exposes:

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

Weather console settings

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

Debug weather editor issues

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

If a weather change does not appear:

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

References

• OpenXRay weather editor article

XRF debug panel

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

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

General

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

It can also:

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

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

Commands

The commands section exposes checkbox shortcuts for known console toggles.

Boolean commands are written as:

<command> on
<command> off

Numeric commands are written as:

<command> 1
<command> 0

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

Object

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

It can log:

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

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

Items

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

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

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

Spawn

The spawn section spawns creatures and simulation groups.

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

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

Teleport

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

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

Registry and Tasks

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

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

Treasures

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

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

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

Current shell sections

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

Game engine

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

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

What the engine owns

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

At runtime it also owns:

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

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

What XRF adds

XRF provides the Lua scripts that the engine calls into:

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

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

Where to go next

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

Command line arguments

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

npm run cli -- start_game starts the configured executable with -dump_bindings. It also supports --new, --load, --difficulty, and --no-intro for common test runs. To pass other engine arguments, run the executable directly, configure a launcher shortcut, or extend the local start command.

For example:

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

Common flags

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

Game mode flags

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

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

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

Examples

Start with an explicit filesystem config and user config:

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

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

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

Load a save after initialization:

xrEngine.exe -load quicksave

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

Console commands

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

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

Basic commands

Script commands

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

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

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

AI debug commands

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

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

Render, UI, sound, and gameplay commands

Useful command families include:

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

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

XRF debug panel

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

Execution flow

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

1. Executable startup

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

Important early choices include:

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

2. Lua script engine initialization

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

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

• register;
• bind;
• start.

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

3. Class and callback registration

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

XRF registers:

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

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

4. XRF startup callback

The engine then calls start.callback(isNewGame).

XRF uses this callback to:

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

Managers and schemes are available after this step.

5. Object creation and binding

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

XRF binds engine objects to classes such as:

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

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

6. Active gameplay loop

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

Known X-Ray engine forks

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

Common references

Compatibility checklist

Before moving XRF scripts to a fork, check:

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

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

Lifecycle

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

Global startup

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

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

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

Binder lifecycle

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

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

Manager lifecycle

Managers extend AbstractManager. A manager can implement:

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

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

Event lifecycle

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

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

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

Save and load lifecycle

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

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

AI and logics

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

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

Motivation planner

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

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

State planner

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

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

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

Evaluators

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

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

Actions

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

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

Schemes

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

The stalker binder wires schemes into object lifecycle:

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

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

Luabind

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

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

@LuabindClass()

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

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

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

Class names

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

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

Externals are separate from luabind

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

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

class, property, and super

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

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

Verification

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

Lua extensions

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

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

Runtime availability

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

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

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

Script path

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

Practical checks

When adding a dependency on a Lua module:

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

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

Custom Lua

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

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

Libraries opened by the engine

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

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

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

Useful flags

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

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

Notes for XRF scripts

• Do not assume optional Lua modules such as LFS or marshal are loaded unless the runtime package opens or provides them.
• Use engine APIs for game objects, packets, configs, and path resolution. Standalone Lua behavior is a weak reference when engine bindings are involved.

Marshal

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

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

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

Availability

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

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

When to use it

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

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

Validation notes

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

LFS

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

XRF has TypeScript declarations for common LFS functions:

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

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

Availability

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

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

Practical use

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

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

Verification checklist

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

Online and offline

X-Ray keeps two related views of many objects:

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

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

Offline objects

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

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

Online objects

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

Use online objects for:

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

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

Switching

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

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

Updates and scheduling

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

Binder updates

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

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

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

Actor update events

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

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

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

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

Timers

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

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

ALife scheduling

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

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

Script engine

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

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

Source layout

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

Runtime entry points

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

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

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

Config-driven behavior

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

When changing behavior, trace the full path:

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

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

Validation

Use focused validation first:

npm test -- <path-or-pattern>
npm run typecheck
npm run cli verify ltx
npm run cli -- build --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:

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

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

Configs

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 verify-ltx tool uses these files to check includes, inheritance, field names, and field types.

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

Defining a schema section

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

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

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

Field syntax

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

Available types

Common schema types:

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

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

Arrays, enums, and tuples

Arrays use []:

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

Enums list allowed values:

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

Tuples define ordered values:

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

Strict sections

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

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

Verification

Run:

npm run cli verify ltx

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

Condlists

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

Basic shape:

{conditions} value %effects%

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

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

Conditions

Function parameters use colon separators:

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

Effects

Effects live inside %...%:

%=give_inited_task(jup_b1_task) +jup_b1_started -jup_b1_waiting%

Inside effects:

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

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

Generated condlists

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

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

These helpers keep generated syntax consistent with the runtime parser.

Parser limits

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

Debugging workflow

When a condlist does not behave as expected:

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

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

Dialog configs

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

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

Source files

Core dialog XML files:

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

Dialog text lives in translation files such as:

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

Script callbacks live in:

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

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

Runtime hooks

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

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

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

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

When changing a dialog:

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

Editing workflow

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

For a script-backed phrase:

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

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

Generated XML

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

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

Validation notes

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

Script configs

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

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

Common structure

Most logic files start from [logic]:

[logic]
active = sr_idle

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

[sr_idle@done]

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

Common fields

Common script logic fields include:

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

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

Extern calls

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

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

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

Validation

Use LTX validation after editing script configs:

npm run cli verify ltx

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

Editing workflow

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

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

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

Creatures

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

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

Source files

Runtime binding

Creature sections attach TypeScript runtime code through script_binding.

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

Actor sections

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

Actor-related sections cover:

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

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

Stalker sections

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

Common stalker fields include:

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

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

Monster sections

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

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

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

Online/offline groups

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

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

Editing checklist

When changing creature configs:

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

npm run cli verify ltx

Zones and anomalies

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

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

Source files

Runtime binding

Zone-related sections attach runtime behavior through script_binding.

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

Base zone sections

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

Common zone fields include:

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

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

Script zone objects

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

Important sections include:

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

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

Composite anomaly zones

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

The binder reads fields such as:

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

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

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

Editing checklist

When changing zones or anomalies:

• keep script_binding aligned with the section’s runtime role;
• do not mix regular field sections with anomal_zone composite configs;
• keep $scheme = $zone on sections validated by zone.scheme.ltx;
• verify referenced particles, sounds, postprocess names, artifact sections, and waypoint names;
• check story links and map placement when changing level changers or restrictors;
• run LTX validation after config or schema changes:

npm run cli verify ltx

Smart terrains and jobs

Smart terrain configs describe places where squads and individual objects can work. Job configs decide which object can take which logic section and with what priority.

The source files live mostly under src/engine/configs/scripts/**/smart plus shared smart terrain configs such as sim_smart_base.ltx and sim_smart_resource.ltx.

Smart terrain role

A smart terrain is a server-side simulation object. It owns jobs, tracks assigned objects, and participates in offline ALife simulation. When an assigned object goes online, its binder and scheme logic run on the client side.

Use smart terrain configs for simulation placement and job selection. Use scheme sections for the actual object behavior once the job is active.

Job fields

Common job fields include:

• logic, pointing to the script config and section used by the object;
• prior, defining selection priority;
• suitable, checking whether the object can take the job;
• active, selecting the active logic section;
• path_walk and path_look, used by walker-style schemes;
• on_info and other condlists for switching job state.

The exact fields depend on the scheme used by the job.

Editing workflow

When changing a smart terrain job:

1. find the smart terrain section and job section;
2. follow logic or active to the scheme section;
3. check suitable and prior if the NPC does not select the job;
4. check scheme implementation and parser support for any new field;
5. validate LTX includes and schema.

Run:

npm run cli verify ltx

Treasures

Treasure configs describe hidden stashes and the rewards assigned to them. XRF reads treasure data through TreasureManager and related treasure utilities.

Use this page when you need to add a stash, grant stash coordinates from a quest, or check why a marked stash does not produce the expected reward.

Source files

Treasure manager source files live under:

• src/engine/configs/managers/treasure_manager.ltx
• src/engine/configs/managers/treasures/treasures_zaton.ltx
• src/engine/configs/managers/treasures/treasures_jupiter.ltx
• src/engine/configs/managers/treasures/treasures_pripyat.ltx

Script configs can also reference treasure inventory boxes, for example src/engine/configs/scripts/treasure_inventory_box.ltx.

Quest and restrictor scripts grant stash coordinates with the give_treasure effect. Examples exist in task configs and script logic, including:

• src/engine/configs/managers/tasks/tasks_zaton.ltx;
• src/engine/configs/managers/tasks/tasks_jupiter.ltx;
• src/engine/configs/scripts/jupiter/jup_b43_task_giver_restrictor.ltx;
• src/engine/configs/scripts/pripyat/pri_b36_sr_ahi_place_pda.ltx.

Runtime behavior

Treasure data is loaded by the treasure manager. It tracks which treasures are available, found, or already looted, and coordinates map spot display through map utilities.

The script effect xr_effects.give_treasure calls TreasureManager.giveActorTreasureCoordinates(...) for each passed treasure id. This grants coordinates; the treasure definition still controls the stash metadata and reward contents.

Physical treasure containers enter the manager through object binders. ObjectPhysic and ObjectHangingLamp call TreasureManager.registerItem(this) when they are constructed, so the manager can connect spawned world objects to treasure data.

When changing treasure behavior, check both:

• the manager config that defines treasure metadata and rewards;
• the script config or object section that represents the stash in the world.

Example grant

This pattern appears in Jupiter quest logic. It grants one treasure once and then records that the reward was already given:

[sr_idle@reward]
on_info = {+jup_b43_contract_brought_first_artefact -jup_b43_once_treasure_give_1} %=give_treasure(jup_hiding_place_5) +jup_b43_once_treasure_give_1%

Use an info portion guard when the same logic section can be evaluated more than once.

Editing checklist

• Keep treasure ids stable once saves can reference them.
• Keep reward sections valid and included.
• Check map spot behavior when a treasure should appear on the PDA.
• Check the world object or inventory box section that represents the stash.
• Check quest scripts that grant the treasure with give_treasure.
• Test TreasureManager or treasure utility code when changing runtime behavior.
• Run npm run cli verify ltx after config edits.

Weapons

Weapon configs live under src/engine/configs/items/weapons. They define base weapon sections, HUD sections, sounds, ballistics, upgrade links, add-ons, ammo classes, and mounted weapons.

Source layout

Important files and folders:

• base.ltx for shared weapon definitions;
• index.ltx for includes;
• w_*.ltx for individual weapon sections;
• upgrades/*.ltx for weapon upgrade trees;
• weapon_upgrades.ltx and upgrades_properties.ltx for shared upgrade data;
• $scheme/weapons.scheme.ltx for validation coverage.

Validation schema

Weapon schemas are mostly strict. They model common sections such as:

• $item_weapon;
• $item_weapon_hud;
• $item_weapon_sounds;
• $item_weapon_attachable;
• $item_weapon_params;
• $item_weapon_grenade;
• $item_weapon_knife;
• $weapon_mounted.

If a valid weapon field fails validation, update the narrow matching schema instead of disabling strict validation for the whole weapon category.

Runtime links

Weapon configs reference assets and other config sections:

• visual, item_visual, HUD positions, and bones;
• sound aliases such as snd_shoot and snd_reload;
• particle aliases such as flame_particles and shell_particles;
• ammo sections through ammo_class;
• upgrade sections through upgrades, installed_upgrades, and upgrade_scheme;
• add-on sections for scopes, silencers, and grenade launchers.

Check all referenced sections and assets when adding a weapon variant.

Editing checklist

• Compare against a nearby weapon with the same weapon class.
• Keep HUD and world model sections separate.
• Validate upgrade section names and include order.
• Run npm run cli verify ltx.
• Test script-side weapon utilities only when changing runtime TypeScript behavior.

Common failure points

• Missing include order can make a weapon section valid in isolation but unavailable from the final item index.
• HUD section names must stay aligned with the weapon section fields that reference them.
• Ammo, scope, silencer, and grenade-launcher section names must exist before the weapon can use them.
• Texture, model, sound, and particle references are not fixed by LTX formatting; verify the referenced resource files separately.

Weather

Weather configs define environment cycles, ambient sounds, fog, suns, thunderbolts, weather effects, and manager-level weather selection. Runtime weather behavior is handled by WeatherManager.

Source layout

Important source areas:

• src/engine/configs/environment/environment.ltx;
• src/engine/configs/environment/weathers/*.ltx;
• src/engine/configs/environment/weather_effects/*.ltx;
• src/engine/configs/environment/ambients/*.ltx;
• src/engine/configs/environment/ambient_channels/*.ltx;
• src/engine/configs/environment/fog/*.ltx;
• src/engine/configs/environment/dynamic_weather_graphs.ltx;
• src/engine/configs/managers/weather_manager.ltx;
• src/engine/configs/managers/weather/weather_manager_levels.ltx.

Weather sections

The $weather schema is strict and includes fields for sky, fog, rain, sun, clouds, wind, water, ambient, thunderbolt, and sun shafts. A weather cycle is built from time sections that point the engine at these values.

Weather effect sections describe temporary events such as surge, blowout, and psi storm effects. They reference particles, sound, wind, and lifetime fields.

Runtime manager

WeatherManager subscribes to actor update events and actor online events. It applies configured weather and exposes debug information through the XRF debug panel.

On actor network spawn, the manager reads the current level’s weathers value from game.ltx. If no level-specific value is configured, it uses the AtmosFear-style dynamic weather section. The selected value is parsed as a condition list and becomes the source for later weather section selection.

During actor updates, the manager:

• checks hourly changes and advances weather graph state;
• changes good/bad weather periods when the configured period boundary is reached;
• marks pre-blowout weather when a surge or weather FX is close;
• updates DOF every five game seconds for active AtmosFear weather;
• saves and loads weather section, period, graph state, and active weather FX data.

When changing weather selection logic, update manager tests. When changing only LTX values, validate the configs and check the result in game.

Validation

Run:

npm run cli verify ltx

Use the debugging weather page for in-game inspection and debug panel workflow.

Editing notes

• Edit weather cycle values under environment/weathers when changing sky, fog, rain, sun, or ambient output.
• Edit dynamic_weather_graphs.ltx when changing transitions between clear, cloudy, rainy, or related graph states.
• Edit weather_manager_levels.ltx and game.ltx links when changing which weather set a level uses.
• Use a save/load check after manager logic changes because weather state is serialized.

Effects and conditions

Effects and conditions are Lua externals called from config condlists. They connect LTX logic to XRF TypeScript behavior.

Effects are registered under xr_effects. Conditions are registered under xr_conditions.

Source layout

Config names

Configs call short names:

on_info = {=actor_has_item(af_oasis_heart)} %=give_inited_task(jup_b16_task)%

The registered globals include the namespace:

• actor_has_item resolves to xr_conditions.actor_has_item;
• give_inited_task resolves to xr_effects.give_inited_task.

Search both names before changing an effect or condition.

Function shape

Effect and condition declarations commonly receive the actor object, the current object, and a parameter array parsed from the condlist:

%=play_sound(story_sound_id)%
{=dist_to_actor_le(30)}

Parameters in configs are colon-separated. Keep parsing simple and update parser tests before adding syntax that needs nested values or escaping.

Side effects

Conditions should answer a question. Effects may mutate game state: give or remove info portions, start tasks, play sounds, set weather, spawn objects, save the game, or switch object state.

pickSectionFromCondList can run effects while choosing a section. A field that looks like a value read may still change state if its matching condlist entry contains %...%.

Testing

Effect and condition files have focused Jest tests beside the declarations. When changing behavior, update the matching test:

npm test -- src/engine/scripts/declarations/effects
npm test -- src/engine/scripts/declarations/conditions

For config changes that call the function, also run:

npm run cli verify ltx

Forms

Forms are UI XML sources consumed by engine CUI classes. XRF keeps most form source in TSX under src/engine/forms and builds it into XML.

Runtime UI classes live under src/engine/core/ui. They load XML, initialize controls, register callbacks, and update the UI at runtime.

Source types

Dynamic forms must export create(). The UI build calls it and writes the result through renderJsxToXmlText.

Components

Shared JSX components live under src/engine/forms/components. Common base components include:

• XrRoot;
• XrElement;
• XrStatic;
• XrText;
• Xr3tButton;
• XrCheckBox;
• XrEditBox;
• XrScrollView;
• XrTab;
• XrTexture.

Prefer these helpers over manually assembling repeated XML structures.

Runtime loading

Runtime classes use engine UI helpers such as CScriptXmlInit, CUIScriptWnd, CUIStatic, CUI3tButton, CUIListBox, and related CUI bindings.

When changing a form:

1. find the runtime class that loads it;
2. keep XML node names stable unless the runtime lookup is updated;
3. check paired 16:9 variants such as name.tsx and name_16.tsx;
4. update tests for runtime UI classes when element names or callbacks change.

Validation

Run a focused UI build after form changes:

npm run cli build -- --filter ui

Do not edit generated XML under target/.

Debugging workflow

If a control does not appear or a callback does not fire, check the runtime class before changing the form. Most UI classes look up controls by XML node name, so a renamed node can break runtime initialization even when the XML builds.

For layout issues, compare the generated XML with the TSX source and any paired widescreen variant. For behavior issues, inspect the src/engine/core/ui class that loads the form and binds callbacks.

Patrols

Patrol paths are level-authored waypoints used by stalker schemes, monster movement, smart-cover targets, travel, spawn helpers, and simulation utilities.

For stalker logic, XRF routes most waypoint behavior through StalkerPatrolManager. Schemes such as walker, sleeper, patrol, and reach_task configure the manager with path_walk, optional path_look, team synchronization, suggested states, and waypoint callbacks.

Related schemes

• walker
• remark
• sleeper
• camper
• patrol
• reach_task
• smartcover

path_walk

path_walk is the movement path. The scheme reads it from config, verifies the patrol path exists, parses waypoint metadata, and sends the object along the path.

Supported waypoint flags include:

If no sig is provided on the last walk waypoint, the manager emits path_end.

path_look

path_look is an optional look/idle path paired with path_walk. The engine uses waypoint flags to choose a matching look point for a reached walk point.

Supported look flags include:

syn is intended for terminal coordination. XRF asserts when it is used on a non-terminal waypoint.

Example

Button-style interaction that plays a press state, then switches when the timed animation signal is emitted:

path_look waypoint flags: a=press|t=0|sigtm=pressed
logic field: on_signal = pressed | next_scheme@section

The exact waypoint flag syntax is stored in level patrol data, not in the LTX file. LTX sections reference the patrol path names through fields such as path_walk and path_look.

Debugging

If a patrol does not work:

• verify level.patrol_path_exists(path_name) would pass for path_walk and path_look;
• check that path_look is not the same path as path_walk;
• check waypoint flags when look points are not selected;
• check on_signal when the movement reaches a point but the scheme does not switch;
• use AI debug overlays and object dumps from the debug panel when the active state is unclear.

UI elements

UI elements are engine CUI bindings exposed to Lua. XRF uses them from runtime UI classes and initializes most controls from XML generated by src/engine/forms.

Use the XRF X-Ray 16 SDK as the API reference for exact methods. This page gives the practical map of common classes.

XML initialization

CScriptXmlInit loads XML and creates controls from node selectors.

Common methods include:

• ParseFile(path);
• ParseShTexInfo(path);
• InitWindow(selector, index, window);
• InitStatic(selector, parent);
• InitTextWnd(selector, parent);
• Init3tButton(selector, parent);
• InitCheck(selector, parent);
• InitComboBox(selector, parent);
• InitEditBox(selector, parent);
• InitListBox(selector, parent);
• InitScrollView(selector, parent);
• InitTab(selector, parent);
• InitTrackBar(selector, parent).

Call ParseFile() before using Init* helpers. Controls created with a parent are attached to that parent by the engine binding.

Window base classes

Use CUIScriptWnd for custom script windows that need callbacks or registered child controls.

Static and text controls

Use SetTextST(...) when the text should come from translations.

Buttons and inputs