openxray-launcher
xr-launcher — universal OpenXRay game installer/launcher
This repository contains xr-launcher — a cross-platform GUI app (Crystal + egui-cr) that assembles playable S.T.A.L.K.E.R. distributions on OpenXRay from copies the user already owns. It does not build the engine and it does not ship game assets: an "install" is a small folder of symlinks + config files pointing at an existing OpenXRay build and an existing GOG/Steam game install.
Supported games:
| id | game | status |
|---|---|---|
| soc | S.T.A.L.K.E.R.: Shadow of Chernobyl | works, experimental engine platform (#392) |
| cs | S.T.A.L.K.E.R.: Clear Sky | engine has -cs mode, untested |
| cop | S.T.A.L.K.E.R.: Call of Pripyat | engine's native platform |
Build
Requires the Crystal toolchain and ruby/rake (for egui-cr's vendored C shims). Then, from the checkout root:
rake all # deps + native shims + release build -> bin/xr-launcher
rake spec # headless specs (no egui backend required)
or via crosspack from this folder (crosspack.yml; every entry runs rake deps → crystal spec → rake release, so a build never ships with red specs):
crosspack deps # verify/install this host's build deps
crosspack build launcher # linux/amd64
crosspack build launcher-macos # darwin/arm64
crosspack build launcher-windows # from an x64 Native Tools prompt
crosspack pack ubuntu-25.10 # deb (also: debian-12, fedora-41 rpm,
# arch PKGBUILD, windows-11.0 MSI via WiX,
# macos .app) — output in crosspacks/
Runtime library deps (GL/X11/libyaml/openssl, verified with ldd) are declared in the deps: section and land in the package metadata (crosspack resolve <target> prints the resolved Depends line).
egui-cr's shard.yml pins one dependency to an SSH git URL; shards.override.yml in this folder reroutes it over https so plain checkouts work without an SSH key.
What an "install" is
The install wizard first forks: register an already assembled game folder as-is, or assemble a new distribution from three folders — engine, original game, target. Assembly creates:
<target>/
bin/ per-file symlinks to the engine build (xr_3da, *.so)
fsgame.ltx per-game FS layout; the engine finds it in the cwd
(portable mode, see CLocatorAPI::setup_fs_path)
gamedata/
shaders/gl symlink to the engine's res/gamedata/shaders/gl
config[s]/openxray.ltx [compatibility] game_mode = <soc|cs|cop>
configs/ (CoP/CS) unpacked configs symlinked from the original
scripts/ (CoP/CS) shipped scripts copied, engine's updated
res/gamedata/scripts overlaid on top
_appdata_/ savedgames/, logs/, screenshots/ — everything the
game writes stays inside the install
<game data> SoC: gamedata.db0..dbd symlinks; CoP/CS: levels/,
resources/, localization/, mp/, patches/ symlinks
Launch runs bin/xr_3da <mode-flag> with <target> as the working directory (plus the matching -shoc/-cs/-cop flag, so the mode is set by both the config file and the command line). The Last save toggle under the Play button makes it launch with -lastsave, so the engine loads the most recent save straight away, skipping the main menu (no last save or a broken one → a normal menu start, see the engine's plans/LASTSAVE_LOAD.md); it is stored per install ("launch_mode" in the config), so xr-launcher run follows it too. The engine process is detached: closing the launcher does not close the game.
Delete removes only this folder. It refuses to delete folders not registered in the launcher config, never follows symlinks while deleting, and the original game copy is never touched. Saves live in _appdata_/ and are deleted with the install — the confirmation says so.
Modified game (Mods)
Below the game list the sidebar has a Mods («Моды») entry — the same wizard with one extra step (setup type → compatibility mode → engine/source) where a selectbox picks the mode (soc / cs / cop) the engine runs the distribution in. The mode sets the launch flag (-shoc / -cs / -cop), game_mode in openxray.ltx and the fsgame.ltx layout; the source folder is validated against the picked mode. Point it at a full modified copy of the game (a mod applied on top of a GOG/Steam install). Such installs are marked custom in launcher.json, listed on the Modified game page (with their mode) and excluded from the per-game counts.
Per-game quirks baked into the templates
- SoC
fsgame.ltxusesconfig\(notconfigs\), needs the root-scanning$arch_dir$line for its.dbarchives, and its configs/scripts stay inside the archives — onlyopenxray.ltxis overlaid (SoC needs-shocor the CoP factory breaks spawns in confusing ways). - CoP/CS point
$arch_dir_levels$/$arch_dir_resources$/… at the symlinked unpacked folders. - The SoC/CoP layouts are byte-identical to the field-tested portable rigs (
~/soc-openxray,~/cop-openxray).
i18n (interface languages)
The launcher is fully translated (English / Русский):
- Translations live in
launcher/config/locales/{en,ru}.ymland are embedded into the binary at compile time (I18n::Loader::YAML.embed, crystal-i18n) — a distributedxr-launchercarries its catalogs and needs no locale files on disk. Because of that, builds must run fromlauncher/(both the embed and the exmlread_fileresolve from the compile working directory; the Rakefile and crosspack steps already do). - The active language is picked at startup: the saved setting wins, else the system locale (
LANG/LC_ALL,ru_RU.UTF-8→ Russian), else English. It is stored as"locale"inlauncher.jsonand switched live from the Settings → Настройки menu (File/Settings/Help menu bar — exml-declarative,assets/launcher.exml) or the combo box on the Settings page; a switch applies on the next frame. - The exml markup (menu bar, settings page, status bar) interpolates i18n store slots (
{menu_file}…), so translated chrome needs no markup duplication. The dynamic home (game tabs, installs, wizard) renders natively through the sameL.tseam. - All core messages (validation errors, install log lines, CLI output) go through
Launcher::L.twith English fallbacks, so even a headless CLI on a system without the locale still speaks English.spec/i18n_spec.crenforces that every locale file carries the full key set — a new string without translations fails the spec suite, not the user.
Adding a language: copy en.yml → <code>.yml, translate the values, add the code to Locale::AVAILABLE (src/launcher/i18n.cr). The key-set spec picks the new file up automatically.
Launcher state
- The install list lives only in the config (single source of truth; no on-disk install markers). Saves are atomic (PID-suffixed tmp + rename) and keep the previous config as
launcher.json.bak; a corrupt config is backed up tolauncher.json.corruptinstead of being silently reset. - The sidebar section open at exit (
"last_played_section") reopens at the next start; per install,"launch_mode"records the Play-button last-save toggle. - Only one launcher instance may run: an exclusive
flockon<config_dir>/lock; a second instance exits with an "already running" error (localized) instead of racing over the config. - Index + recents:
~/.config/xr-launcher/launcher.json(Linux) /%APPDATA%\xr-launcher\(Windows) /~/Library/Application Support/xr-launcher/(macOS).
CLI (headless)
The GUI binary doubles as a CLI — same file, same logic:
xr-launcher list
xr-launcher install soc --engine ~/xray-16 --source ~/GOG/soc --dir ~/Games/OpenXRay/soc
xr-launcher run ~/Games/OpenXRay/soc
xr-launcher remove ~/Games/OpenXRay/soc
Desktop shortcut
assets/icons/launcher.png is the app logo (radiation trefoil — generated, no licensing baggage); per-game icons come from misc/media/icons. A Linux menu entry:
[Desktop Entry]
Type=Application
Name=OpenXRay Launcher
Comment=Assemble and run S.T.A.L.K.E.R. on OpenXRay
Exec=/path/to/xr-launcher
Icon=/path/to/launcher/assets/icons/launcher.png
Categories=Game;
assets/xr-launcher.desktop ships this template with TryExec=xr-launcher — install to ~/.local/share/applications/ and fix the icon path, or let a distro package substitute the prefix.
Layout / code map
src/launcher.cr library entry + headless CLI (no egui)
src/launcher_gui.cr egui-cr GUI: exml chrome + native home — the
only egui-dependent file
src/launcher/i18n.cr locale init/switch + the L.t lookup seam
src/launcher/catalog.cr game definitions: mode flags, fsgame.ltx
templates, source validation
src/launcher/engine.cr engine folder detection (checkout / bin dir /
installed prefix)
src/launcher/installer.cr the assembler (symlinks, overlays, config)
src/launcher/uninstaller.cr safe recursive delete (config-gated,
symlink-aware)
src/launcher/runner.cr detached launch with the right cwd + mode flag
src/launcher/store.cr JSON index of installs + locale setting
src/launcher/single_instance.cr flock guard: one launcher at a time
src/launcher/paths.cr per-OS config dirs (spec-overridable)
assets/launcher.exml declarative UI: menu bar, settings page,
status bar (hot-reloads; embedded as a
compile-time fallback)
config/locales/*.yml embedded translations (en/ru)
spec/ headless specs (fake engine + fake game trees,
locale key-set completeness)
Verification: rake spec (unit) and the real-world end-to-end — install SoC/CoP from a GOG copy, launch, check _appdata_/logs/ for FATAL / SCRIPT RUNTIME ERROR / early log end, then remove.
openxray-launcher
- 0
- 0
- 0
- 0
- 2
- 4 days ago
- October 30, 2026
Tue, 17 Nov 2026 13:53:00 GMT