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.

MapUpgrader is a .NET tool that processes compiled Half-Life BSP map files and applies all necessary upgrades and bug fixes required for use with the Unified SDK. It handles maps from the base game and each supported expansion, with an optional --game flag to specify which game’s upgrade ruleset to apply. The tool is included in the hlu/tools directory of every Unified SDK release.
MapUpgrader is a .NET tool. On Windows you can run it as MapUpgrader.exe [options] or dotnet MapUpgrader.dll [options]. On Linux use dotnet MapUpgrader.dll [options].

​
Command line usage

Usage:
  MapUpgrader [<maps>...] [options]

Arguments:
  <maps>  List of maps to upgrade

Options:
  --game <bshift|cstrike|czero|czeror|dod|gearbox|ricochet|tfc|valve>
                                            The name of a game's mod directory to apply upgrades for
                                            that game [default: valve]
  --diagnostics-level <All|Common|Disabled> The diagnostics level to set [default: Disabled]
  --version                                 Show version information
  -?, -h, --help                            Show help and usage information

​
The --game parameter

The --game value is the mod directory name of the game the maps originate from. If not specified, maps are treated as vanilla Half-Life maps (valve). Supported values are:
ValueGame
valveHalf-Life (default)
gearboxHalf-Life: Opposing Force
bshiftHalf-Life: Blue Shift
cstrikeCounter-Strike
czeroCounter-Strike: Condition Zero
czerorCounter-Strike: Condition Zero — Deleted Scenes
dodDay of Defeat
ricochetRicochet
tfcTeam Fortress Classic

​
Running MapUpgrader

Upgrade a single Half-Life map using the default valve ruleset:
MapUpgrader.exe "C:/Half-Life/valve/maps/c1a0.bsp"
Upgrade multiple Opposing Force maps at once:
MapUpgrader.exe "C:/Half-Life/gearbox/maps/of1a1.bsp" "C:/Half-Life/gearbox/maps/of1a2.bsp" --game gearbox
Upgrade a Blue Shift map with diagnostic output:
MapUpgrader.exe "C:/Half-Life/bshift/maps/ba_yard1.bsp" --game bshift --diagnostics-level All
Pass multiple map paths as separate arguments in a single invocation to batch-upgrade all maps in one run.

​
Diagnostics level

The --diagnostics-level option controls how much information the tool prints about the upgrade process:
ValueDescription
DisabledNo diagnostics output (default)
CommonPrint commonly useful diagnostic messages
AllPrint all available diagnostic messages

​
Error reporting

If any errors occur, MapUpgrader logs the details to the console and stops execution immediately. Check the console output for the error message and verify that the map path is correct and the file is not read-only before retrying.

Build docs developers (and LLMs) love

Get started for freeTalk to us