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.

Creating a new mod with the Unified SDK involves more than writing C++ code. You will also need to configure your mod’s identity in Steam, keep game assets synchronised between the assets repository and your local installation, and eventually package a distributable archive. This page walks you through each of those steps.
The repository currently contains a pre-alpha build. Pre-alpha builds are not ready to be used as the base for a shipping mod — features are still being developed and may be unfinished or buggy.

​
Changing the Mod Name

Your mod’s display name — shown in the Steam game list, the game window title, and Task Manager — is defined in the liblist.gam.in template file located in the config/ directory of the SDK repository.
1

Open the template file

Open config/liblist.gam.in in your editor. The relevant line looks like this:
game "Half-Life Unified SDK"
2

Set your mod name

Replace the quoted string with your mod’s name:
game "My Mod Name"
3

Commit the change

Commit config/liblist.gam.in to your version control repository so that the change is tracked alongside your source code.
The actual liblist.gam file is generated from this template when you build the INSTALL CMake target. That generated file is what Steam reads, so make sure you have run an install build before launching through Steam.

​
Launching Your Mod Through Steam

Steam discovers mods by reading the liblist.gam file in your mod directory. Once that file has been generated by the INSTALL build target, your mod will appear in the Steam game list and its name will be used as the window title.

​
Development Process

Because there is no single repository for the mod installation itself, assets must be copied from the assets repository to your local game installation. The SDK provides four .NET tools to automate this and the rest of the development workflow.

​
AssetSynchronizer

The AssetSynchronizer tool handles the continuous mirroring of assets from the assets repository to your mod directory.
  • On startup it copies every file that differs between the source and destination.
  • It then monitors the assets repository for any changes and automatically mirrors them as they happen.
  • A configuration file controls which files are watched and where they are copied.

​
Packager

The Packager tool creates a distributable ZIP archive of your mod installation.
  • A configuration file controls which files are included or excluded from the archive.
  • Archive filenames include a UTC timestamp to uniquely identify each build.
  • On successful completion, old archives in the output directory are automatically removed.

​
ContentInstaller

The ContentInstaller tool copies, converts, and upgrades maps taken from the original Half-Life, Opposing Force, and Blue Shift installations.
  • Original maps cannot be redistributed, so this tool regenerates them locally.
  • Changes to the SDK code that affect map content are applied automatically during the install step.

​
MapUpgrader

The MapUpgrader tool is a standalone version of the map-upgrade functionality built into ContentInstaller.
  • Use it to upgrade a custom map to the Unified SDK, provided the map was originally made for the vanilla Half-Life engine (not another mod or game).
Most modders will not need to use ContentInstaller or MapUpgrader directly during day-to-day development. They exist to streamline the full release-packaging pipeline as much as possible.
The Half-Life Uplink demo is not available on Steam, so its maps are bundled with the Unified SDK mod installation directly. When the Packager creates a release archive it looks for Uplink maps inside the mod directory named valve_uplink. You must manually copy the Uplink maps into valve_uplink/maps for this lookup to succeed. 
<mod_installation>/
└── valve_uplink/
    └── maps/
        ├── t0a0.bsp
        └── ...

​
Summary of the Development Workflow

1

Edit source code and assets

Make changes to C++ code in the SDK repository and to assets in the assets repository.
2

Build and install

Build the project and run the INSTALL CMake target to deploy updated binaries and generate liblist.gam.
3

Synchronise assets

Run AssetSynchronizer to copy changed assets from the assets repository into your local mod directory. Leave it running to mirror changes automatically.
4

Test in-game

Launch your mod through Steam and test your changes.
5

Package for distribution

Run Packager to produce a timestamped ZIP archive ready for release.

Project Structure

Understand the three repositories and the source code layout before diving in.

.NET Tools

Install the .NET 6 SDK and learn how to invoke any Unified SDK tool from the command line.

Build docs developers (and LLMs) love

Get started for freeTalk to us