NAME

goldutil - GoldSrc modding utility.

SYNOPSIS

DESCRIPTION

goldutil can read, modify, and write multiple file formats used by the GoldSrc (Half-Life) engine.

BSP MANIPULATION

goldutil bsp info FILE

Print parsed data from a BSP.

goldutil bsp remap-materials --out PATH [--verbose] [--original-materials PATH] [--replacement-materials PATH] FILE

On a BSP with embedded textures, change their names so they can match what is in the original game materials.txt.
This allows setting proper material sounds to custom textures without having to distribute a materials.txt file.
Warning: The BSP cannot use any of the textures listed in the original materials.txt

--out PATH

Where to write the remapped BSP.

--verbose

Output to STDOUT the details of what materials were remapped to.

--original-materials

Path to the materials.txt file of the original game, defaults to valve/sound/materials.txt.

--replacement-materials

Path to the replacement materials.txt file, defaults to valve_addon/sound/materials.txt.

MAP MANIPULATION

goldutil map export [--cleanup-tb] [FILE]

Export a .map file the way TrenchBroom does, removing all layers marked as not exported. Output is written to stdout, if no FILE is provided the map will be read from standard input.

--cleanup-tb

Also remove properties added by TrenchBroom that are not understood by the engine and spam the console with errors.

goldutil map neat [--moddir] FILE

Process neat_ entity macros and outputs the generated .map to standard output.

--moddir

root of the mod directory (eg. 'valve'), defaults to the current working directory.

goldutil map graph [FILE]

Create a graphviz digraph of entity caller/callee relationships from a .map file. ripent exports use the same format and can be read too. Output is written to stdout.

NOD MANIPULATION

goldutil nod export [--input-format FORMAT] FILE

Extract node positions from a .nod graph into a .map populated with corresponding info_node entities.
Links between nodes are represented using target/targetname, nodes are duplicated to allow showing all links, TrenchBroom layers are used to separate links by hull type. The resulting .map file is not for engine consumption, only for TrenchBroom-assisted archaeology.

--input-format FORMAT

Parse the .nod file using a different node graph format instead of using the PC release format. FORMAT can be any one of:

· valve Standard Half-Life node graph (default).
· decay PlayStation 2 release of Half-Life: Decay.

--original-positions

Use the node positions as they were set in the original .map instead of their position after being dropped to the ground during graph generation.

SPR MANIPULATION

goldutil spr create --out PATH [--type TYPE] [--format FORMAT] FRAME0 [FRAMEX…]

Create a sprite from the given ordered list of PNG frames and write it to the given output path.

Input images must be 256 colors paletted PNGs, the palette of the first frame will be used, the other palettes are discarded and all frames will be interpreted using the first frame's palette.
If the palette has under 256 colors it will be extended to 256, putting the last color of the palette in the 256th spot and remapping the image to match this updated palette. This matters for transparent formats.
If you use pngquant(1) to create your palletized input files, you can use its --pngbug option to ensure the transparent color will always be last.

--out PATH

Path to the output .spr file.

--type TYPE

Sprite type, TYPE can be any one of:

· parallel Always face camera (default).
· parallel-upright Always face camera except for the locked Z axis.
· oriented Orientation set by the level.
· parallel-oriented Faces camera but can be rotated by the level.
· facing-upright Like parallel-upright but faces the player origin instead of the camera.

--format FORMAT

Texture format, determines how the palette is interpreted and the texture is rendered by the engine. FORMAT can be any one of:

· normal 256 colors sprite (default).
· additive Additive 256 colors sprite, dark values are rendered as transparent, the darker the less opacity.
· index-alpha Monochromatic sprite with 255 alpha levels, the base color is determined by the last color on the palette.
· alpha-test Transparent 255 colors sprite. The 256th color on the palette will be rendered as fully transparent.

goldutil spr extract [--dir PATH] FILE

Output all frames of a sprite to the current directory. The output files will be named after the original sprite file name plus a frame number suffix and an extension.

--dir PATH

Output frames to the specified directory instead of the current one.

goldutil spr info FILE

Print parsed frame data from the given FILE.

WAD MANIPULATION

goldutil wad create --out PATH INPUT0 [INPUTX…]

Create a WAD file from a list of PNG files and directories. Directories are not scanned recursively and only PNG files are used.
File base names (without extensions) are uppercased and used as texture names.
Warning: Names exceeding 15 chars will trigger an error as this is the maximum length supported by the WAD format.

--out PATH

Path to the output .wad file.

goldutil wad extract --dir DIR PATH

Extract a WAD file in the given DIR as a bunch of PNG files.

--dir DIR

Path to the directory where to write PNG files.

goldutil wad info PATH

Print parsed data from a WAD file.

MISC MODDING UTLITIES

goldutil fgd

Outputs the FGD to use with goldutil map neat.

goldutil mod filter-materials --in MATERIALS BSP0 [BSPX…]

Takes a materials.txt file and only keep the texture names that are used in the given BSP files.
This is useful to keep a final materials.txt under 512 entries when working with large texture collections.
Filtered materials are written to STDOUT.

--in MATERIALS

Path to the materials.txt file you want to filter.

goldutil mod filter-wads --out WAD_OUT -bspdir BSPDIR WAD_IN0 [WAD_INX…]

Reads all BSP files at the given directory and creates a WAD containing only the textures used by the BSPs.
This allows using large texture collections during development but only distribute the smallest possible WAD at release time.
Be aware that Half-Life requires the wads from the "wads" property to be present and will attempt to load them.
Before release you should generate the output WAD, remove the WADs that were used during filtering from your worldspawn "wads" property, add the output WAD, and then rebuild your maps.

--out WAD_OUT

Path were the output WAD will be written.

--bspdir BSPDIR

Path of the directory containing the BSPs to use as a used texture list.