Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/twhl-community/halflife-unified-sdk/llms.txt

Use this file to discover all available pages before exploring further.

Building the Half-Life Unified SDK from source produces the client and server game libraries (DLLs on Windows, shared objects on Linux) that power your mod. The SDK uses CMake to generate project files for Visual Studio on Windows or Unix Makefiles on Linux, and relies on vcpkg to automatically download and compile most third-party dependencies. Once built, the INSTALL target copies the compiled libraries directly into your mod directory so you can launch and test immediately.
These instructions assume a strong grasp of C++, CMake, Git, vcpkg, and your platform’s compiler toolchain (Visual Studio on Windows or GCC/Make on Linux). All Linux instructions are written for Ubuntu — substitute commands as needed for your distribution.

​
Minimum Requirements

All platforms require CMake 3.23 or newer. Download it from cmake.org/download.
Avoid CMake 3.28 and 3.28.1. These versions have a known bug that causes them to fail to download vcpkg dependencies. See this vcpkg issue for details. Use 3.27.x or 3.29+ instead.
During Visual Studio installation, select the following components:Workloads:
  • Desktop development with C++
Individual components:
  • MSVC v142 — VS 2019 C++ x64/x86 build tools (Latest), or the equivalent for your Visual Studio version
  • C++ profiling tools
  • Windows 10 SDK (select the latest available version)
vcpkg uses the latest version of Visual Studio installed on your system to compile dependencies. If you have multiple versions installed, always use the newest one to build the SDK itself — mixing versions can cause compiler errors.

​
Clone the Repository

The SDK uses Git submodules, so you must clone with --recurse-submodules to get all required source code: 
cd path/to/where/you/want/source/code
git clone --recurse-submodules https://github.com/twhl-community/halflife-unified-sdk.git
It is recommended to place the cloned directory inside a dedicated parent folder so you can keep the source tree and the CMake build directory side-by-side: 
mkdir halflife-unified-sdk_dev
cd halflife-unified-sdk_dev
git clone --recurse-submodules https://github.com/twhl-community/halflife-unified-sdk.git
If you prefer a graphical Git client, Sourcetree works well. When cloning, open Advanced Options on the Clone page and tick Recurse submodules.

​
Change the Mod Name

Before generating project files, set the display name for your mod. This name appears in the game window title, Task Manager, and Steam. Open config/liblist.gam.in in a text editor and change: 
game "Half-Life Unified SDK"
to the name of your mod, then commit the change to version control.

​
Generate Project Files with CMake

Open CMake GUI and set the two path fields:
  • Where is the source code — the directory you cloned the repository into
  • Where to build the binaries — a new directory next to the source folder, e.g. halflife-unified-sdk_build
Click Configure. In the dialog that appears, enter:
  • Generator: Visual Studio 16 2019 (or your installed version)
  • Platform: Win32
  • Toolchain: select Specify toolchain file for cross-compiling, then click Next
Browse to the source directory, open the cmake folder, and select WindowsToolchain.cmake. Click Finish.CMake will perform its first-run setup. vcpkg will download, build, and install all dependencies — this can take several minutes the first time.After configuration completes, you will see new variables highlighted in red. Set these key variables:
VariableDescription
CMAKE_INSTALL_PREFIXPath to your mod directory, e.g. C:/Program Files (x86)/Steam/steamapps/common/Half-Life/hlu
HalfLife_HLDS_DIRECTORY(Optional) Path to the directory containing hlds.exe if you want dedicated server debugging
HalfLife_RELEASE_TYPESet to Pre-Alpha or Alpha to enable the on-screen project info overlay
You can also configure optional debugging helpers:
VariableDescription
HalfLife_ENABLE_CONSOLEEnable the developer console on startup
HalfLife_ENABLE_CHEATSEnable cheats on startup
HalfLife_DEVELOPER_LEVELSet the developer output verbosity level
HalfLife_ADDITIONAL_COMMAND_ARGUMENTSExtra launch arguments, e.g. +map c2a5
Once all variables are set, click Generate to produce the Visual Studio solution.
If CMake repeatedly fails to locate third-party dependencies, delete the CMake cache (CMakeCache.txt in the build directory, or use File → Delete Cache in CMake GUI) and re-run the configure step from scratch. Stale cached data is a common cause of hard-to-diagnose dependency errors.

​
Build and Install

Open HalfLifeMod.sln from the build directory in Visual Studio. The solution contains the following projects:
ProjectPurpose
clientHalf-Life mod client library
serverHalf-Life mod server library
INSTALLBuilds all targets and copies libraries + debug info to CMAKE_INSTALL_PREFIX
ALL_BUILDCMake utility — builds all projects
ZERO_CHECKRe-runs CMake when built
ProjectInfoRegenerates the HUD project info; built automatically with client/server
Build the INSTALL project to compile the mod and deploy the libraries to your mod directory. Then press F5 to launch the game (Steam must be running).

Build docs developers (and LLMs) love

Get started for freeTalk to us