Engine: Xash3D FWGS

CSRetro uses a vendored, CSRetro-modified fork of Xash3D FWGS as its game engine (engine/). The full source tree is committed in-tree (no submodules). Upstream project attribution: Credits.

Vendored tree revision in this build: see VENDOR.md and Vendor table (VENDOR.md).

What is Xash3D FWGS?

Xash3D FWGS is a game engine that provides compatibility with Valve's original GoldSrc / Half-Life Engine and extends it significantly. It is a heavily modified fork of the original Xash3D Engine by Unkle Mike, maintained by the FWGS team.

CSRetro release workflow: CMake builds client and server DLLs on Linux, Windows, and macOS (x64) in CI. The engine binary is produced by the Waf build under engine/ (see ./tools.sh build:engine); day-to-day developer docs focus on Linux x64 for the engine install into game-test/, while the source under engine/ follows upstream multi-platform layout.

Key engine features

Steam Half-Life (HLSDK 2.5) support
Cross-platform and modern compiler support (Windows, Linux, BSD, Android – x86 & ARM)
Better multiplayer: multiple master servers, headless dedicated server, voice chat, IPv6 support
Multiple renderers: OpenGL, GLESv1, GLESv2, Software
Advanced virtual filesystem: .pk3 / .pk3dir, GoldSrc FS compatibility, case-insensitivity emulation
TrueType font rendering (via mainui_cpp)
PNG, KTX2, Ogg Vorbis (.ogg) and Ogg Opus (.opus) support
External VGUI support module

In CSRetro

The engine is built automatically by ./tools.sh build:engine (Waf, 64-bit, release) and installed to game-test/ by ./tools.sh install:engine.

./tools.sh build:engine        # Build Xash3D-FWGS (Waf, 64-bit release)
./tools.sh build:engine:debug  # Debug variant
./tools.sh install:engine      # Copy built binaries to game-test/
./tools.sh build:full          # Full pipeline (engine + client/server + addons)

The engine binary is placed at game-test/xash3d (Linux) and loads game data from game-test/cstrike/.

Source tree layout (`engine/`)

engine/
├── waf                   # Waf build script (bundled)
├── engine/               # Core engine source
├── 3rdparty/             # Vendored engine dependencies (SDL2, mainui, ...)
└── Documentation/        # Engine documentation (Markdown, vendored with the tree)

Environment variables (from `engine/Documentation/environment-variables.md`)

The engine honours these stable environment variables (paths are examples; behaviour matches upstream docs):

Variable	Type	Description
`XASH3D_GAME`	string	Overrides default game directory. Ignored if `-game` is set on the command line.
`XASH3D_BASEDIR`	string	Sets the base (root) directory instead of the current working directory.
`XASH3D_RODIR`	string	Read-only base directory. Ignored if `-rodir` is set on the command line.
`XASH3D_EXTRAS_PAK1`	string	Extra archive added to the VFS at lowest priority.
`XASH3D_EXTRAS_PAK2`	string	Second extra archive, next in priority after `XASH3D_EXTRAS_PAK1`.

Variables not listed in upstream environment-variables.md are internal and not guaranteed stable.

mdldec (same file)

Variable	Type	Description
`MDLDEC_ACT_PATH`	string	If set, read activities list from this path.

Index of `engine/Documentation/` (in-tree)

All paths are relative to engine/Documentation/. CSRetro targets Linux x64 for desktop; skip Android/Vita-only notes unless you care about upstream parity.

Root-level topics

File	Summary
`gameinfo.txt`	`gameinfo.md` — Syntax and keys for `gameinfo.txt` / `liblist.gam` conversion.
`environment-variables.md`	Engine and tool env vars (excerpt above).
`goldsrc-protocol-support.md`	Supported network protocol versions and GoldSrc compatibility modes.
`bug-compatibility.md`	Engine bug-compatibility toggles for mod compatibility.
`ports.md`	Platform porting notes.
`nat-bypass-usage.md`	NAT traversal / connectivity helper usage.
`hd-textures.md`	High-resolution texture support.
`supported-mod-list.md`	Mods known to work.
`not-supported-mod-list-and-reasons-why.md`	Unsupported mods and rationale.
`opensource-mods.md`	Open-source mod pointers.
`musl.md`	Building/running on musl libc.
`touch-controls.md`	Touch control configuration (mobile-oriented).
`psvita.md`	PlayStation Vita port notes.
`donate.md`	Upstream donation / support links (informational).

`protocol/`

File	Summary
`protocol/01-introduction.md`	Protocol overview (Xash3D 49 vs legacy).
`protocol/02-connectionless.md`	Connectionless packets and queries.
`protocol/03-netchan.md`	Net channel message flow.

`extensions/`

File	Summary
`extensions/library-naming.md`	Shared library naming (`_amd64`, etc.).
`extensions/addon-folders.md`	Addon search paths and packaging.
`extensions/console-scripting.md`	Console script facilities.
`extensions/entity-tools.md`	Entity debugging / tooling.
`extensions/expanded-common-structures.md`	Extended shared structures vs GoldSrc.
`extensions/input-interface.md`	Input interface (English).
`extensions/input-interface-ru.md`	Same topic (Russian).
`extensions/mp3-loops.md`	MP3 looping behaviour.
`extensions/native-object.md`	Native object bindings.
`extensions/sounds.lst.md`	`sounds.lst` format.
`extensions/steam-broker.md`	Steam integration broker notes.

`development/`

File	Summary
`development/debugging-using-minidumps.md`	Crash dumps and debugging.
`development/mod-porting-guide.md`	Porting mods to Xash3D FWGS.
`development/engine-porting-guide.md`	Porting the engine to new platforms.
`development/cross-compiling-for-windows-with-wine.md`	Cross-compile workflow with Wine.
`development/setting-up-qt-creator.md`	Qt Creator IDE setup.

Common developer-oriented cvars (summary)

Exact names and defaults depend on build and fork. Typical GoldSrc/Xash-style entries include:

CVar	Typical use
`developer`	Extra console messages (0/1).
`host_framerate`	Fixed timestep / profiling (often 0 in normal play).
`sv_cheats`	Allow cheat commands (server).

For exhaustive lists, use cvarlist / cmdlist in the console at runtime.

Attribution

Xash3D FWGS is developed and maintained by the FWGS team. See docs/credits.md for full attribution including original Valve GoldSrc engine acknowledgement.