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.

AssetSynchronizer is a .NET tool designed for active development workflows. While it is running it monitors the assets repository directory and automatically copies files to the mod installation whenever they are created, changed, or renamed. This keeps your game directory in sync with the source assets without requiring a manual copy step. The tool is included in the hlu/tools directory of every Unified SDK release.
AssetSynchronizer overwrites destination files without warning and without keeping a backup. Make sure to maintain regular backups of your files. Once a file is overwritten you will not be able to recover its previous contents.
Files deleted from the source (assets) directory are not deleted from the destination (mod) directory. Removal must be done manually if needed.
AssetSynchronizer is a .NET tool. On Windows you can run it as AssetSynchronizer.exe [options] or dotnet AssetSynchronizer.dll [options]. On Linux use dotnet AssetSynchronizer.dll [options].

​
Command line usage

Usage:
  AssetSynchronizer [options]

Options:
  --assets-directory <assets-directory>  Path to the assets directory
  --mod-directory <mod-directory>        Path to the mod directory
  --asset-manifest <asset-manifest>      Path to the asset manifest file
  --version                              Show version information
  -?, -h, --help                         Show help and usage information

​
Options

--assets-directory should point to your local clone of the assets repository. --mod-directory should point to your local copy of the mod installation — typically the hlu folder inside your Half-Life game directory. --asset-manifest should point to the AssetManifest.json file contained inside the assets repository. This file controls which files are copied and where they go.

​
Running AssetSynchronizer

AssetSynchronizer.exe ^
    --assets-directory "halflife-unified-sdk-assets" ^
    --mod-directory "C:/Program Files (x86)/Steam/steamapps/common/Half-Life/hlu" ^
    --asset-manifest "halflife-unified-sdk-assets/AssetManifest.json"

​
Using a script

Because the arguments are the same each time, it is recommended to save them in a script placed next to the assets repository directory. 
dotnet "path/to/AssetSynchronizer.dll"^
    --assets-directory "halflife-unified-sdk-assets"^
    --mod-directory "C:/Program Files (x86)/Steam/steamapps/common/Half-Life/hlu"^
    --asset-manifest "halflife-unified-sdk-assets/AssetManifest.json"

​
Error reporting

If errors occur, AssetSynchronizer logs them to the console and continues running. Common causes include files being read-only, attempting to copy a file when a directory of the same name already exists, or security settings that prohibit copying or overwriting.

​
AssetManifest.json format

The asset manifest is a JSON file that tells AssetSynchronizer which files to copy and where. It contains a list of pattern groups, each with a destination path root and a list of filters.

​
Top-level structure

{
    "PatternGroups": [
        {
            "Path": "%ModDirectory%",
            "Filters": []
        }
    ]
}
Path is the directory under the Half-Life game folder where destination paths begin. The special constant %ModDirectory% resolves to the mod directory specified on the command line. You can use variants like %ModDirectory%_hd to also copy content to related mod directories such as the HD content folder.

​
Filter objects

Each entry in the Filters array is an object with the following properties:
PropertyDescription
SourceRelative path to the source directory inside the assets directory. Use an empty string "" to refer to the root of the assets directory.
DestinationRelative path to the destination directory inside the game directory. Use an empty string "" to refer to the root of the mod directory.
PatternA wildcard pattern used to filter which files are matched in the source directory.
RecursiveWhether subdirectories are also scanned. Defaults to false if not specified.
Multiple filters may share the same Source and Destination, but avoid reusing the same Pattern across filters for the same pair — this causes the same file to be copied more than once.

​
Example manifest

// This file contains a list of filters to copy assets to the game directory.
{
    "PatternGroups": [
        {
            "Path": "%ModDirectory%",
            "Filters": [
                {
                    "Source": "cfgsrc",
                    "Destination": "",
                    "Pattern": "server.cfg"
                },
                {
                    "Source": "cfgsrc",
                    "Destination": "cfg",
                    "Pattern": "*.json",
                    "Recursive": true
                },
                {
                    "Source": "cfgsrc",
                    "Destination": "",
                    "Pattern": "*.scr.install"
                },
                {
                    "Source": "cfgsrc",
                    "Destination": "",
                    "Pattern": "titles.txt"
                },
                {
                    "Source": "resourcesrc",
                    "Destination": "resource",
                    "Pattern": "*.txt",
                    "Recursive": true
                },
                {
                    "Source": "soundsrc",
                    "Destination": "sound",
                    "Pattern": "*.txt"
                }
            ]
        }
    ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us