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 Unified SDK ships a collection of smaller .NET conversion utilities designed to migrate legacy Half-Life asset formats into the JSON-based formats used by the SDK, as well as supporting tools for developers working with maps and entity data. All of these tools are included in the hlu/tools directory of every Unified SDK release and follow the same platform conventions: on Windows run them as ToolName.exe [options] or dotnet ToolName.dll [options]; on Linux use dotnet ToolName.dll [options].

​
Hud2Json

Hud2Json converts Half-Life 1 sprites/hud.txt and sprites/weapon_*.txt HUD definition files into the Unified SDK’s hud.json format.

​
Command line usage

Usage:
  Hud2Json <filename> [options]

Arguments:
  <filename>  hud definition to convert

Options:
  --output-filename <output-filename>  If provided, the name of the file to write the hud.json contents to.
                                       Otherwise the file is saved to the source directory with the same
                                       name and 'json' extension. []
  --version                            Show version information
  -?, -h, --help                       Show help and usage information
If --output-filename is not specified, the output file is written to the same directory as the input file, with the extension changed to .json.

​
Examples

Convert hud.txt and save the result alongside it:
Hud2Json.exe "C:/Half-Life/valve/sprites/hud.txt"
Convert hud.txt and write to a specific output path:
Hud2Json.exe "C:/Half-Life/valve/sprites/hud.txt" --output-filename "C:/output/hud.json"

​
Error reporting

If any errors occur, Hud2Json logs the details to the console and stops execution.

​
Materials2Json

Materials2Json converts Half-Life 1 sound/materials.txt files into the Unified SDK’s materials.json format.

​
Command line usage

Usage:
  Materials2Json <filename> [options]

Arguments:
  <filename>  materials to convert

Options:
  --output-filename <output-filename>  If provided, the name of the file to write the materials.json contents to.
                                       Otherwise the file is saved to the source directory with the same
                                       name and 'json' extension. []
  --version                            Show version information
  -?, -h, --help                       Show help and usage information
If --output-filename is not specified, the output file is written next to the source file with the extension changed to .json.

​
Examples

Convert materials.txt in place:
Materials2Json.exe "C:/Half-Life/valve/sound/materials.txt"
Convert and write to a custom path:
Materials2Json.exe "C:/Half-Life/valve/sound/materials.txt" --output-filename "C:/output/materials.json"

​
Error reporting

If any errors occur, Materials2Json logs the details to the console and stops execution.

​
Sentences2Json

Sentences2Json converts Half-Life 1 sound/sentences.txt files into the Unified SDK’s sentences.json format.

​
Command line usage

Usage:
  Sentences2Json <filename> [options]

Arguments:
  <filename>  Sentences definition to convert

Options:
  --output-filename <output-filename>  If provided, the name of the file to write the sentences.json contents to.
                                       Otherwise the file is saved to the source directory with the same
                                       name and 'json' extension. []
  --version                            Show version information
  -?, -h, --help                       Show help and usage information
If --output-filename is not specified, the output file is written next to the source file with the extension changed to .json.

​
Examples

Convert sentences.txt in place:
Sentences2Json.exe "C:/Half-Life/valve/sound/sentences.txt"
Convert and write to a custom path:
Sentences2Json.exe "C:/Half-Life/valve/sound/sentences.txt" --output-filename "C:/output/sentences.json"

​
Error reporting

If any errors occur, Sentences2Json logs the details to the console and stops execution.

​
Skill2Json

Skill2Json converts Half-Life 1 skill.cfg files into the Unified SDK’s skill.json format.

​
Command line usage

Usage:
  Skill2Json <filename> [options]

Arguments:
  <filename>  skill.cfg to convert

Options:
  --output-filename <output-filename>  If provided, the name of the file to write the skill.json contents to.
                                       Otherwise the file is saved to the source directory with the same
                                       name and 'json' extension. []
  --version                            Show version information
  -?, -h, --help                       Show help and usage information
If --output-filename is not specified, the output file is written next to the source file with the extension changed to .json.

​
Examples

Convert skill.cfg in place:
Skill2Json.exe "C:/Half-Life/valve/skill.cfg"
Convert and write to a custom path:
Skill2Json.exe "C:/Half-Life/valve/skill.cfg" --output-filename "C:/output/skill.json"

​
Error reporting

If any errors occur, Skill2Json logs the details to the console and stops execution.

​
KeyValueMatcher

KeyValueMatcher is a developer utility that scans BSP files in one or more maps directories and searches for entities matching specified patterns. It is useful for auditing entity data across a large set of maps — for example, finding all entities of a particular classname or locating every keyvalue that matches a given regular expression.

​
Command line usage

Usage:
  KeyValueMatcher [<maps-directory>...] [options]

Arguments:
  <maps-directory>  One or more paths to the maps directories to search

Options:
  --print-mode <Entity|KeyValue|Nothing>    What to print when a match is found [default: KeyValue]
  --classname <classname>                   Classname regex pattern
  --key <key>                               Key regex pattern
  --value <value>                           Value regex pattern
  --flags-name <flags-name>                 If specified, name of the flags key to match (e.g. spawnflags)
  --flags-match-mode <Exclusive|Inclusive>  How to match flags [default: Inclusive]
  --flags <flags>                           Flag value to match [default: 0]
  --version                                 Show version information
  -?, -h, --help                            Show help and usage information
All pattern arguments (--classname, --key, --value) accept regular expressions. If a pattern is not provided it is treated as matching everything (.*). The --print-mode option controls what is printed for each match:
ValueDescription
KeyValuePrint the matching key-value pair (default)
EntityPrint all keyvalues of the matching entity
NothingSuppress output (useful for counting only)
The --flags-match-mode option controls how flag bits are compared:
ValueDescription
InclusiveMatch if the entity’s flags include the specified bits (default)
ExclusiveMatch only if the entity’s flags exactly equal the specified value

​
Examples

Find all trigger_once entities across two map directories:
KeyValueMatcher.exe "C:/Half-Life/valve/maps" "C:/Half-Life/gearbox/maps" --classname "trigger_once"
Print the full entity block for every entity that has a target key:
KeyValueMatcher.exe "C:/Half-Life/valve/maps" --key "target" --print-mode Entity
Find entities where spawnflags inclusively matches bit 1:
KeyValueMatcher.exe "C:/Half-Life/valve/maps" --flags-name spawnflags --flags 1

​
Error reporting

If any errors occur, KeyValueMatcher logs the details to the console and stops execution.

​
MapCfgGenerator

MapCfgGenerator generates map configuration files for official Half-Life, Opposing Force, and Blue Shift maps. All maps from a given game share the same configuration contents, so this tool automates the creation of per-map cfg files that reference a shared game config. The destination directory should point to the cfgsrc/maps directory in your local copy of the assets repository.

​
Command line usage

Usage:
  MapCfgGenerator <destination-directory> [options]

Arguments:
  <destination-directory>  Where to put the generated files

Options:
  --version       Show version information
  -?, -h, --help  Show help and usage information

​
Generated file format

Each generated file references a shared per-game configuration file. For example, a configuration file for a Half-Life map contains: 
{
    "Includes": [
        "cfg/HalfLifeConfig.json"
    ]
}
The included file varies depending on which game the map belongs to.

​
Examples

Generate map cfg files into the assets repository’s maps config directory:
MapCfgGenerator.exe "halflife-unified-sdk-assets/cfgsrc/maps"

​
Error reporting

If any errors occur, MapCfgGenerator logs the details to the console.

​
Bsp2Obj

Bsp2Obj converts Half-Life 1 BSP map files into the Wavefront OBJ format. This is useful for inspecting map geometry in 3D modelling software or for reference during development. For each BSP file the tool generates the following output files:
  • mapname.obj — geometry in Wavefront OBJ format
  • mapname.mtl — material library file
  • mapname_material_index.tga — texture image for each embedded material (one file per material)
mapname is derived from the BSP filename. index is the sequential number of the generated material. Materials and textures are only generated when the texture is embedded directly in the BSP file; otherwise a dummy material with no texture is used.

​
Command line usage

Usage:
  Bsp2Obj <filename> [options]

Arguments:
  <filename>  Path to the BSP file

Options:
  --destination <destination>  Directory to save the OBJ, material and texture files to.
                               If not provided the files will be saved to the directory that
                               the source file is located in. []
  --version                    Show version information
  -?, -h, --help               Show help and usage information
If --destination is not specified, all output files are saved to the same directory as the input BSP file.

​
Examples

Convert a BSP and save the output alongside the source file:
Bsp2Obj.exe "C:/Half-Life/valve/maps/c1a0.bsp"
Convert a BSP and write the output to a specific directory:
Bsp2Obj.exe "C:/Half-Life/valve/maps/c1a0.bsp" --destination "C:/output/c1a0"

​
Error reporting

If any errors occur, Bsp2Obj logs the details to the console and stops execution.

​
MapUpgraderDocGenerator

MapUpgraderDocGenerator is a developer utility that generates Markdown documentation for the map upgrades implemented by the MapUpgrader.Upgrades library. It reads the XML documentation file produced when that library is built and converts it into human-readable Markdown text.

​
Command line usage

Usage:
  MapUpgraderDocGenerator <xml-file> [options]

Arguments:
  <xml-file>  Name of the XML file to convert

Options:
  --version       Show version information
  -?, -h, --help  Show help and usage information

​
Examples

Generate documentation from the XML doc file produced by the build:
MapUpgraderDocGenerator.exe "MapUpgrader.Upgrades.xml"

​
Error reporting

If any errors occur, MapUpgraderDocGenerator logs the details to the console.

Build docs developers (and LLMs) love

Get started for freeTalk to us