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 replaces the original cfg-based server configuration system with a new JSON-based game configuration system. The classic cvars servercfgfile and lservercfgfile, along with their associated files server.cfg and listenserver.cfg, are no longer used. A copy of server.cfg is still included with the mod installation to suppress console warnings, but it performs no meaningful configuration.
The game configuration system uses the logger named gamecfg.
Types of Configuration Files
Two kinds of game configuration files exist, each serving a distinct purpose:
| Type | Default Path | Cvar | When Applied |
|---|
| Server configuration file | cfg/server/server.json | sv_servercfgfile | At the start of every new map |
| Map configuration file | cfg/maps/<mapname>.json | (auto-discovered) | Immediately after the server config |
sv_servercfgfile to an empty string to disable it entirely.
The map configuration file is map-specific and is loaded automatically when the map matches. It is the right place for per-map settings like skill files, material lists, HUD colors, and entity templates.
Configuration File Syntax
A game configuration file is a JSON object that may contain two top-level keys:
Includes — An optional array of relative paths to other configuration files that are loaded before this file. This lets you share common settings across many maps. The same file cannot be included more than once.SectionGroups — An optional array of section group objects. Each group contains a Sections object and an optional Condition string.
Sections within a group are applied in an unspecified order that may change between loads of the same map. A section group with a Condition is only applied when that condition evaluates to true. See the AngelScript conditional evaluation documentation for the full list of supported conditions.
You may have both Includes and SectionGroups in the same file.
Game Mode Properties
The following top-level properties control the game mode when present in the configuration file:
| Name | Type | Purpose |
|---|
GameMode | string | Name of the game mode to activate |
LockGameMode | boolean | When true, the server operator cannot override the active game mode |
Section Types
Lists of Filenames
Several section types accept a list of filenames using the same shared syntax:
"FileNames": ["path/to/file.ext"],
"ResetList": false
FileNames is an array of relative file paths. ResetList, when set to true, clears any entries that were added by the game’s own startup code before adding the entries in FileNames. Use ResetList when you want to completely replace the default list rather than append to it.
The following section types all use this filename list syntax:
| Section | Availability | Purpose |
|---|
Sentences | Map config | Specifies sentences files |
Materials | Map config | Specifies materials files |
Skill | Map config | Specifies skill configuration files |
GlobalModelReplacement | Map config | Specifies global model replacement files |
GlobalSentenceReplacement | Map config | Specifies global sentence replacement files |
GlobalSoundReplacement | Map config | Specifies global sound replacement files |
Echo
Prints a message to the console via the gamecfg logger at the info log level. Useful for diagnosing which configuration files are being loaded and in what order.
Available in all configuration files.
| Name | Type | Purpose |
|---|
Message | string | Message to print in the console |
Commands
Executes a list of console commands, replacing the functionality of the original server.cfg and listenserver.cfg files. The syntax is identical to the console and classic cfg files.
Available in all configuration files.
"Name": [
// disable autoaim
"sv_aim 0",
// player bounding boxes (collisions, not clipping)
"sv_clienttrace 3.5",
// disable clients' ability to pause the server
"pausable 0",
// default server name. Change to "Bob's Server", etc.
// "hostname \"Half-Life\"",
// maximum client movement speed
"sv_maxspeed 270",
// load ban files
"exec listip.cfg",
"exec banned.cfg"
]
Map configuration files may only execute commands listed in the whitelist file at cfg/MapConfigCommandWhitelist.json. If the whitelist file does not exist, map configuration files cannot execute any commands at all.
HudReplacement
Specifies replacements for HUD configuration files. The section is an object with optional keys for replacing the main HUD file and individual weapon HUD files.
Available in map configuration files.
| Name | Type | Purpose |
|---|
HudReplacementFile | string | Replaces hud.json with the specified file |
Weapons | object | Maps weapon classnames to replacement HUD filenames |
"HudReplacement": {
"HudReplacementFile": "sprites/op4/hud.json",
"Weapons": {
"weapon_9mmar": "sprites/op4/weapon_9mmar.json"
}
}
HudColor
Sets a custom HUD color for all players. The value is a string in R G B format where each component is a number from 0 to 255. Some game modes may override this setting.
Available in map configuration files.
SuitLightType
Sets the suit light type for all players. Must be one of:
Available in map configuration files.
"SuitLightType": "nightvision"
EntityTemplates
Specifies entity templates to apply to specific entity classnames. The section is an object mapping classnames to template filenames.
Available in map configuration files.
"EntityTemplates": {
"monster_zombie": "cfg/entitytemplates/mymaps/zombie.json"
}
EntityClassifications
Specifies the path to an entity classifications definition file. Only one file can be active at a time for a given map.
Available in map configuration files.
"EntityClassifications": "cfg/mymaps/entity_classifications.json"
SpawnInventory
Defines the initial inventory that players receive when they join the server or respawn after death. The section is an object with optional properties.
Available in map configuration files.
| Name | Type | Default | Purpose |
|---|
Reset | boolean | false | Resets spawn inventory configuration to its default empty state |
HasSuit | boolean | false | Whether the player starts with the HEV Suit |
HasLongJump | boolean | false | Whether the player starts with the Long Jump Module |
Health | integer | 100 | Starting health (range: 1–100) |
Armor | integer | 0 | Starting armor (range: 0–100) |
Weapons | object | {} | Set of weapons to give the player |
Ammo | object | {} | Set of ammo to give the player |
WeaponToSelect | string | "" | Which weapon to select automatically |
Weapons maps weapon classnames to objects. Each object may optionally include a DefaultAmmo key specifying the amount of ammo loaded into the weapon. Both DefaultAmmo and ammo values accept -1 to grant the maximum possible amount.
Ammo maps ammo type names to integer quantities.
"SpawnInventory": {
"HasSuit": true,
"Weapons": {
"weapon_crowbar": {},
"weapon_9mmhandgun": {
"DefaultAmmo": -1 // Give a pistol with maximum ammo
}
},
"Ammo": {
"Hand Grenade": 2
},
"WeaponToSelect": "weapon_9mmhandgun"
}
Sample Configuration Files
The following example is a map configuration file that conditionally applies multiplayer-specific settings: it replaces the default material lists, adds a global model replacement file, sets a custom HUD color, and switches the suit light to nightvision.
{
"SectionGroups": [
{
// Only use this in multiplayer
"Condition": "Multiplayer",
"Sections": {
"Materials": {
// Completely override the default materials used by these maps.
"ResetList": true,
"FileNames": [
"sound/mymaps/my_default_materials.json",
"sound/mymaps/my_map_specific_materials.json"
]
},
"GlobalModelReplacement": {
"FileNames": ["cfg/Op4ModelReplacement.json"]
},
"HudColor": "0 160 0",
"SuitLightType": "nightvision"
}
}
]
}
Includes:
{
"Includes": [
"cfg/OpposingForceConfig.json"
]
}