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 Half-Life Unified SDK uses JSON as the format for all configuration files. Two open-source libraries power this system: NLohmann JSON handles parsing and serialization, while PBoettch json-schema-validator performs schema-based validation. Every configuration file in the SDK — from skill settings to game configuration — is a JSON file that benefits from this shared infrastructure.
All JSON configuration files must use UTF-8 encoding.
Single-line comments (//) are supported in all JSON files throughout the SDK. While this is not part of the official JSON specification, it is a widely supported extension that makes configuration files easier to annotate and maintain. The JSON system uses the logger named json.

​
Parse Error Reporting

If a JSON file contains malformed syntax, the error is reported to the console with a specific error code and a human-readable description of the problem. This makes it straightforward to find the offending line without guessing. For example, a forgotten comma produces an error like this: 
[sv] [json] [error] Error "101" parsing JSON: "[json.exception.parse_error.101] parse error at line 11, column 3: syntax error while parsing array - unexpected '{'; expected ']'"
Refer to the NLohmann JSON exceptions documentation for a full list of parse error codes and their meanings.

​
JSON Schema Validation

Every JSON configuration file in the SDK has an associated JSON Schema that formally describes its expected structure. The SDK uses JSON Schema draft 7 to perform this validation. When validation is enabled, the system reports errors by showing the JSON path of the invalid element and the value that failed (truncated to 100 bytes if it is too long). For example, an invalid Name value in a Sections array produces an error like this: 
[sv] [json] [error] Error validating JSON "/Sections/1" with value "{"Color":"255 160 0","Name":"foo"}": no subschema has succeeded, but one of them is required to validate
This tells you that the second element (index 1, since arrays start at 0) of the Sections array does not match any of the valid subschemas.
Use json_generateallschemas to export all schemas to disk, then point your editor at them for inline validation and autocompletion while editing configuration files.

​
Enabling Validation

Schema validation is controlled by the json_schema_validation console variable: 
json_schema_validation 1
Set it to 0 to disable validation. Validation is disabled by default.

​
Console Commands

The JSON system is available on both the client and server, so all commands are prefixed with either cl_ or sv_ depending on which side you are issuing them from.

​
json_listschemas

Syntax: json_listschemas Prints a list of all registered JSON schemas to the console. Use this to discover the names of schemas you can generate with json_generateschema.

​
json_generateschema

Syntax: json_generateschema <schema_name> Generates a single schema file for the given schema name. The file is written to schemas/<shortlibraryprefix>/. Use the schema name as reported by json_listschemas.

​
json_generateallschemas

Syntax: json_generateallschemas Generates schema files for every registered schema in a single pass. All files are written to schemas/<shortlibraryprefix>/. This is the quickest way to get a complete set of schemas for editor integration.

​
Console Variables

​
json_schema_validation

Syntax: json_schema_validation <0|1> Boolean value that controls whether JSON Schema validation is performed when loading configuration files. Set to 1 to enable, 0 to disable.

Build docs developers (and LLMs) love

Get started for freeTalk to us