Developers

Repository Layout

See Architecture for the full directory layout.

What is site/? Nothing you edit — it is the local HTML output of mkdocs build. It is gitignored and is not pushed to GitHub. The published site is built in CI from docs/ + mkdocs.yml. See Repository artifacts for site/, build/, .venv, mirrors, and vendored .github/ folders.

VENDOR.md (repo root) is part of the developer workflow: CMake reads it for csr version. It is documented for humans as Vendor table (VENDOR.md) — keep both in sync when bumping vendored-tree revisions.

Build Commands

./tools.sh build:full           # Clean + engine + client/server + install + package
./tools.sh build:engine         # Xash3D-FWGS (Waf, 64-bit, release)
./tools.sh build:engine:debug   # Xash3D-FWGS debug build
./tools.sh build:release        # Client + server DLLs (CMake release preset)
./tools.sh build:debug          # Client + server DLLs (CMake debug preset)
./tools.sh build:check          # Quick compile check (debug, no install)
./tools.sh build:clean          # Remove build/ and build-debug/
./tools.sh build:clean:all      # Also removes engine Waf output
./tools.sh install:addons       # Re cmake-install + Metamod + NodeMod (+ npm admin if ENABLE_NODEMOD_PIPELINE=1)

Run Commands

./tools.sh run:game             # Normal game start from game-test/
./tools.sh run:debug            # With debug log (logs/csretro-debug.log)
./tools.sh run:game:debug       # Full debug + auto-load de_dust2
./tools.sh run:server           # Dedicated server (MAP/PORT/MAXPLAYERS env vars)

Exit / crash on quit (NodeMod): If quitting still hits a V8 assertion during Meta_Detach after this fix, your libnodemod.so may be an older tarball without MultiIsolatePlatform::DisposeIsolate() in NodeImpl::Stop(). Rebuild NodeMod from source when libnode_fat.a is available. Details: NodeMod component (Engine shutdown and V8).

Environment Variables

Variable	Default	Description
`CSRETRO_ASSET_ROOT`	–	Path to Half-Life installation (cstrike + valve)
`ENABLE_NODEMOD_PIPELINE`	`1`	Set to `0` to skip npm/TypeScript build
`CSRETRO_SKIP_SMOKE`	`0`	Set to `1` to skip smoke checks after build:full
`CSRETRO_DEBUG_VERBOSE`	`0`	Set to `1` for `+developer 1 -condebug` in run:debug
`CSRETRO_NONINTERACTIVE`	`0`	Set to `1` for CI (no interactive prompts)
`NODEMOD_SKIP_BUILD`	`0`	Set to `1` to skip NodeMod CMake build
`NODEMOD_SKIP_NATIVE`	`0`	Set to `1` to skip NodeMod native CMake only (tarball may still apply)
`NODEMOD_SKIP_RELEASE_DL`	`0`	Set to `1` to skip NodeMod binary download fallback
`NODEMOD_BUILD_NODE`	`0`	Set to `1` to build Node.js from source (very slow)
`NODEMOD_ADMIN_STRICT`	`1`	Set to `0` to allow missing npm/node in the admin pipeline (not recommended)

Refreshing vendored upstreams

Upstream code is not pulled via git submodule. To merge a newer xash3d-fwgs, cs16-client, metamod-fwgs, or nodemod-goldsrc release, replace the corresponding tree (strip all .git / .gitmodules from the import), update VENDOR.md with the new short revision strings, and commit. Options include git subtree or a clean copy from a fresh clone of the upstream repo.

Validation

./tools.sh validate:warnings    # Check build logs for compiler warnings/errors
./tools.sh info                 # Project status (build state, engine, assets)
./tools.sh check:menu           # Verify engine mainui runtime file is present

Developer Console Variables

Cvar / Command	Description
`developer 1`	Enable developer console output
`bot_quota <n>`	Number of AI bots
`bot_difficulty <0-3>`	Bot difficulty level
`mp_startmoney <n>`	Starting money for testing
`csretro_ver`	Read-only CVAR set by the client DLL; holds the one-line version banner (used by menu background)

`csr version` command

csr version

Server: registered in the game DLL (GameDLLInit). Prints the component table to the server console.
Client: registered in the client DLL (pfnAddCommand). Use in the developer console (~); output includes client DLL build number (Q_buildnum / cscl_ver) plus the same component revision table as the server (values from VENDOR.md at CMake configure time).

csr is the top-level command; version is the subcommand.

The version string is generated at CMake configure time from VENDOR.md (SHA extraction), the monorepo git short SHA (CSRETRO_GIT_SHORT), configure date (CSRETRO_BUILD_DATE), and pinned component versions. The generated header is ${CMAKE_BINARY_DIR}/csretro_version.h (included by both game and client DLLs).

MOTD: On every ServerActivate, CSRetro_GenerateMOTD() writes {gamedir}/motd_csretro.txt and sets motdfile to motd_csretro.txt. Joining players see the CSRetro description + versions in the MOTD window.

To update versions after importing a new upstream release: 1. Update VENDOR.md with the new SHA. 2. Re-run CMake configure (cmake -B build …). 3. Re-build.

See also: ./tools.sh version for the equivalent shell-side version output.

Continuous integration (GitHub Actions)

The workflow .github/workflows/ci.yml runs on push/PR to main and builds the CMake targets client and regamedll on a matrix of x64 hosts:

OS	Role
Linux	Primary sanity check (same as historical single-job CI): Ninja + Release, system packages for SDL2/freetype/etc.
Windows	Best-effort compile of the same targets with MSVC + Ninja (toolchain preinstalled on `windows-latest`).
macOS	Best-effort compile with Homebrew-provided dependencies.

The full engine build (Waf under engine/) is not run in CI by default — it is heavier; run ./tools.sh build:engine locally or extend CI if you need automated engine binaries.

What you might miss locally vs CI: CI does not install Steam assets, does not run the game, and does not execute the NodeMod npm pipeline unless a workflow step is added. Use ./tools.sh build:full before release-quality validation.

Artifacts / releases: pushing a version tag v* triggers .github/workflows/release.yml, which builds on Linux, Windows, and macOS (x64) and attaches CPack packages (CSRetro-Linux.tar.gz, CSRetro-Darwin.tar.gz, CSRetro-Windows.zip, names may vary) to the GitHub Release. Compile verification on every push to main / PRs uses ci.yml (same three OS, targets client + regamedll). Documentation deploy uses docs.yml (MkDocs to GitHub Pages), not the game build.

Documentation site (MkDocs)

The published site is built with MkDocs and the Material theme (see mkdocs.yml). Python dependencies are pinned in requirements-docs.txt at the repository root (MkDocs + Material only). That file is the single source for the docs toolchain version range; CI (.github/workflows/docs.yml) installs from it for GitHub Pages.

Local build (recommended: venv)

Many Linux distributions use PEP 668 (externally managed Python). Prefer a virtual environment:

python3 -m venv .venv
.venv/bin/pip install -r requirements-docs.txt
.venv/bin/mkdocs serve    # or: .venv/bin/mkdocs build --strict

Authoring workflow (curated docs)

Base facts on in-tree sources where possible: engine/Documentation/ (Xash3D), client/3rdparty/yapb/ (ConVar registrations), 3rdparty/nodemod/, and runtime checks (cvarlist, meta list).
If you need a full upstream HTML tree for comparison, download it outside this repository (for example ~/tmp/csretro-upstream-ref/). Do not commit snapshots. Maintainer policy: .github/documentation-policy.md in the repository.
Summarize and adapt content under docs/ (English). Attribute upstream projects; avoid large verbatim copies of copyrighted manuals.
Run mkdocs build --strict before pushing doc changes.

MkDocs vs GitHub Wiki: the canonical documentation lives in the docs/ folder with PR review; the Wiki is optional and not required for CSRetro. See Community.

NodeMod Development

See NodeMod for plugin build and installation details.

Engine environment variables (Xash3D FWGS)

The engine honours these variables (see engine/Documentation/environment-variables.md in the vendored tree). They apply when launching xash3d (Linux) or the platform binary from game-test/.

Variable	Description
`XASH3D_GAME`	Overrides default game directory if `-game` is not set.
`XASH3D_BASEDIR`	Base directory instead of the current working directory.
`XASH3D_RODIR`	Read-only base directory (ignored if `-rodir` is set).
`XASH3D_EXTRAS_PAK1` / `XASH3D_EXTRAS_PAK2`	Optional extra archives on the virtual filesystem search path.

Other variables may exist for internal use and are not guaranteed stable.

CMake / Presets

Root presets in CMakePresets.json:

Preset	Platform	Type
`linux-x64-release`	Linux	Release
`linux-x64-debug`	Linux	Debug
`windows-x64-release`	Windows	Release
`macos-x64-release`	macOS	Release

All presets set XASH_COMPAT=ON for Xash3D FWGS 64-bit ABI support in ReGameDLL_CS.

Upstream Contributions

When upstreaming fixes: - xash3d-fwgs: https://github.com/FWGS/xash3d-fwgs - cs16-client: https://github.com/Velaron/cs16-client - ReGameDLL_CS: https://github.com/rehlds/ReGameDLL_CS - metamod-fwgs: https://github.com/FWGS/metamod-fwgs - nodemod-goldsrc: https://github.com/nodemod/nodemod-goldsrc