Synopsis
goldutil [global options] <command> [command options] [command arguments]
goldutil help [command]
goldutil bsp [info | remap-materials]
goldutil fgd
goldutil map [export | graph | neat]
goldutil mod [filter-materials | filter-wads]
goldutil nod [export]
goldutil spr [create | extract | info]
goldutil wad [create | extract | info]
goldutil wav [loop]
Description
goldutil can read, modify, and write multiple file formats used by the GoldSrc (Half-Life) engine.
BSP Manipulation
goldutil bsp info <input>
Print parsed data from a BSP.
goldutil bsp remap-materials --out <output> [--original-materials <path>] [--replacement-materials <path>] [--verbose] <input>
On a BSP with embedded textures, change the texture names to match what is in
the original game’s 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
--original-materials <path>-
Path to the materials.txt file of the original game, defaults to valve/sound/materials.txt.
--out <output>-
Where to write the remapped BSP.
--replacement-materials <path>-
Path to the replacement materials.txt file, defaults to valve_addon/sound/materials.txt.
--verbose-
Output to STDOUT what the original texture names were remapped to.
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 STDIN.
--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 <path>] <file>
Process neat_* entity macros and outputs the generated .map to standard output.
See Neat entities and goldutil fgd.
--moddir <path>-
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>] [--original-positions] <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 <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.
<frame0> [<frameX>…]-
Paths to the individual sprite frames in PNG format.
--format <format>-
Texture format, determines how the palette is interpreted and the texture is rendered by the engine. <format> can be any one of:
additive-
Additive 256 colors sprite, dark values are rendered as transparent, the darker the less opacity.
alpha-test-
Transparent ("masked") 255 colors sprite. The 256th color on the palette will be rendered as fully transparent.
index-alpha-
Monochromatic sprite with 255 alpha levels, the base color is determined by the last color on the palette.
normal-
256 colors sprite (default).
--out <path>-
Path to the output .spr file.
--type <type>-
Sprite type,
<type>can be any one of:facing-upright-
Like parallel-upright but faces the player origin instead of the camera.
oriented-
Orientation set by the level.
parallel-oriented-
Faces camera but can be rotated by the level.
parallel-upright-
Always face camera except for the locked Z axis.
parallel-
Always face camera (default).
goldutil spr extract [--dir <dir>] <file>
Output all frames of a sprite as PNGs in the current working directory.
The output files will be named after the original sprite file name plus a frame
number suffix and an extension.
--dir <dir>-
Output frames to <dir> directory instead of the current working directory.
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.
<input0> [<inputx>…]-
Paths to the input PNG files.
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 utilities
goldutil fgd
Output to STDOUT 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.
<bsp0> [<bspx…]-
Paths to the BSP files to scan for used texture names.
--in <materials>-
Path to the input materials.txt file you want to filter.
goldutil mod filter-wads --out <wad_out> -bspdir <dir> <wad_in0> [<wad_inx>…]
Read all BSP files at the given directory and create 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.
<wad_in0> [<wad_inx>…]-
Input WADs for non-embedded textures.
--out <wad_out>-
Path were the output WAD will be written.
--bspdir <dir>-
Path of the directory containing the BSPs to use as a used texture list.
goldutil wav loop --out=<out> <wav>
Make a WAV loop by setting CUE points.
In GoldSrc only the presence of these CUE points is checked, not their position.
This commands adds a CUE point at the end so ambient_generic can do its work.
<wav>-
Input WAV file.
--out <out>-
Path were the output WAV will be written.
Neat entities
neat_master
An entity that can be used as a master in other entities, avoiding
multisource quirks and limitations.
When targeting it:
-
trigger_relaytargetstateis respected. -
All other callers are handled and will toggle by default, including
multi_manager,trigger_changetarget,path_track, and monsters usingTriggerTarget. -
You can target
<targetname>_on,<targetname>_off, or<targetname>_toggleto set the corresponding state on the master without having to set up a trigger_relay.
Internally it works by setting up a button_target (<targetname>_proxy), a
multisource (<targetname>), and three trigger_relay (<targetname>_on,
<targetname>_off, and <targetname>_toggle).
trigger_relay entities targeting <targetname> are redirected to
<targetname>_proxy. All other entities targeting <targetname> will be
rewritten to target <targetname>_toggle.
Properties
targetname(target_source)-
Base name of the
multisourceentity, should be used as themasterproperty in other entities, can also be used as atargetin other entities which will toggle themultisource. target(target_destination)-
Copied verbatim to the underlying
multisource. globalstate(string)-
Copied verbatim to the underlying
multisource.
neat_message
Equivalent to env_message with three important differences:
-
The message duration is read from titles.txt.
-
The
targetisn’t fired until the message ends. -
The
delayis used as padding in addition to message duration.
Properties
targetname(target_source)-
Entity name
target(target_destination)-
Entity to trigger when the message ends.
delay(string)-
Additional delay before triggering
target.
The following properties are copied verbatim to the generated env_message:
-
message(string) -
spawnflags(flags) -
messagesound(sound) -
messagevolume(string) -
messageattenuation(choices) -
triggerstate(choices)