Building CSRetro

Toolchain policy (use current stable)

CSRetro is developed and tested with current stable tool releases. Older versions may work but are not guaranteed.

Tool	Policy	Notes
CMake	Latest stable 4.x (minimum 3.21 as in `CMakeLists.txt`)	cmake.org
Ninja	Latest stable	e.g. `ninja-build` on Debian/Ubuntu, or upstream ninja-build
Clang / GCC	Latest stable C++ toolchain with C++17	On Linux, Clang is recommended; MSVC 2022+ on Windows
Python 3	3.10+ (3.12+ recommended)	Engine Waf configure/build; cs16-client extras
Waf	Bundled `engine/waf` (from upstream Xash3D-FWGS)	Upstream Waf project: gitlab.com/ita1024/waf
Node.js + npm	18+	Only for the NodeMod TypeScript plugin pipeline (`ENABLE_NODEMOD_PIPELINE`); not required for engine/client/ReGameDLL/Metamod binaries

Platform: Linux, Windows, macOS – x64 only.

Third-party source trees are vendored in this repository (see VENDOR.md). A normal clone contains everything; no git submodule steps.

Clone

git clone https://github.com/benjarogit/csretro.git
cd csretro

Build

Full build (recommended)

Cleans everything, builds engine + client/server, installs to game-test/, creates a release package:

./tools.sh build:full

Individual steps

./tools.sh build:engine     # Xash3D-FWGS only (Waf, 64-bit)
./tools.sh build:release    # Client + server DLLs only (CMake)
./tools.sh build:debug      # Debug build of client/server
./tools.sh build:clean      # Remove build/ and build-debug/
./tools.sh build:clean:all  # Also remove engine Waf tree

Engine (Waf) and Git metadata

The vendored engine/ tree has no .git directory (see VENDOR.md). Upstream Waf would normally read commit hash, branch, and commit date from Git; without that, embedded strings would be wrong and the client could reject the engine (host_ver / build number).

./tools.sh build:engine (and build:full) exports CSRETRO_REPO_VCS_* from the CSRetro repository root before running waf configure, so libxash.so embeds your monorepo’s short commit, branch, and ISO commit time.
engine/public/wscript picks these up when the default Git discovery finds nothing under engine/public/.

Manual engine builds from engine/ without tools.sh: set the same variables yourself, or rely on the engine’s Q_buildnum() fallback in engine/public/build.c when no valid date is available.

Metamod, NodeMod, and npm plugins (incremental)

After you have a successful build:release (or build:full), you can refresh CMake install + Metamod + libnodemod.so + gameinfo.txt / plugins.ini without rebuilding the engine:

./tools.sh install:addons              # default preset: linux-x64-release
./tools.sh install:addons linux-x64-debug

With ENABLE_NODEMOD_PIPELINE=1 (default), this also runs the npm step for @nodemod/admin and csr_botmenu (requires Node.js 18+ and npm).
build:release installs native Metamod/NodeMod binaries but does not run that npm pipeline; use build:full or install:addons for the TypeScript plugins.

CMake presets (advanced)

cmake --preset linux-x64-release
cmake --build build/linux-x64-release -j$(nproc)

Available presets: linux-x64-release, linux-x64-debug, windows-x64-release, macos-x64-release.

Documentation (MkDocs)

Python packages for the documentation site are pinned in requirements-docs.txt at the repo root (MkDocs + Material only). Use a virtual environment (same as Developers):

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

CI runs mkdocs build --strict on pushes to main (.github/workflows/docs.yml) using the same requirements-docs.txt.

Assets

CS 1.6 game data (maps, sounds, etc.) is not included.
Copy from a Steam Half-Life installation or provide a path manually:

./tools.sh install:assets
# or:
CSRETRO_ASSET_ROOT=/path/to/Half-Life ./tools.sh install:assets

Run

./tools.sh run:game          # Normal start from game-test/
./tools.sh run:debug         # With debug log (logs/csretro-debug.log)
./tools.sh run:server        # Dedicated server

Documentation site (MkDocs)

The public site at benjarogit.github.io/csretro is built from main by the Docs workflow in .github/workflows/docs.yml (GitHub Actions → GitHub Pages).

Local preview (use a venv on distributions with PEP 668 / “externally managed” Python):

python3 -m venv .venv
.venv/bin/pip install -r requirements-docs.txt
.venv/bin/mkdocs serve

Repository settings (one-time): Settings → Pages → Build and deployment → Source: GitHub Actions (not “Deploy from a branch”).

Engine build internals

The engine (engine/) is built with Waf as provided by xash3d-fwgs:

cd engine
python3 waf configure -T release --64bits --prefix=<game-test-path>
python3 waf build -j$(nproc)

tools.sh build:engine runs this automatically.