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.

The Half-Life Unified SDK gives mod developers a single, coherent foundation for building Half-Life mods. It merges the codebases of the original game, Opposing Force, and Blue Shift — eliminating duplication while adding new systems for configuration, scripting, logging, sound, and more. The SDK uses a CMake-based build system with vcpkg for dependency management, and targets Visual Studio 2019/2022 on Windows and GCC 11 on Linux.
Pre-alpha builds are not ready for production mod development. Features are still being developed and may be unstable. Check the releases page for the latest stable build.

Installation

Install the Unified SDK mod and set up your development environment step by step.

Building the SDK

Configure CMake, generate project files, and compile the SDK on Windows or Linux.

Project Structure

Understand how the SDK’s source code, assets, and tools repositories are organized.

Mod Setup

Create a new mod: name it, configure liblist.gam, and set up a development workflow.

​
Core Systems

The Unified SDK introduces a suite of new systems that replace or extend the original Half-Life engine’s capabilities.

JSON System

JSON-based configuration with schema validation for all SDK config files.

Game Configuration

New JSON server config system replacing cfg-based server.cfg and listenserver.cfg.

Skill System

JSON skill variables with per-difficulty overrides and code-level constraints.

Logging System

spdlog-based logging with named loggers, file output, and configurable levels.

Sound System

OpenAL-powered audio supporting Wave, MP3, Ogg Vorbis, FLAC, and more.

AngelScript

Scripting support for conditional config evaluation and gameplay logic.

​
Tools

MapUpgrader

Upgrade original Half-Life maps to work with the Unified SDK.

Content Installer

Copy, convert, and upgrade maps from HL1, Opposing Force, and Blue Shift.

Asset Synchronizer

Automatically mirror asset repository changes to your mod directory.

Packager

Create mod installation archives ready for distribution.

​
Prerequisites

Before working with this SDK, you should be comfortable with:
  • C++ — the entire game codebase is written in C++
  • CMake — the build system used to generate project files
  • Git & vcpkg — for version control and dependency management
  • Visual Studio (Windows) or GCC (Linux) — supported compilers
  • JSON — most configuration files use JSON syntax
If you need help or want to discuss mod development, join the TWHL Discord or visit the TWHL website. The TWHL wiki also has tutorials for getting started with Half-Life programming.

Build docs developers (and LLMs) love

Get started for freeTalk to us