This is an addendum to
the original tutorial series, concerning
other things to consider for your mod that is not covered in previous articles, and outside the realm of actual mapping, modelling, programming, etc.
Other things you can customize
The general rule of thumb is that you can always omit
stuff that you don't want to customize, as the game will read the default files from Half-Life (the valve folder) and optionally the mod defined in your liblist.gam's fallback_dir
.
Custom music
Whereas WON GoldSrc spins up your physical CD drive looking for the soundtrack, they're included in the Steam version in the
media/
folder, comprised of a bunch of mp3 files. Customizing these simply involve adding mp3 files of the same name in the same location in your mod. Consult the
target_cdaudio
page for the
track number → filename mapping.
Custom GUI scheme – TrackerScheme.res
This file defines the UI scheme for GoldSrc's Steam UI, but you can have a custom one for your mod. Things such as UI colours, fonts for various elements, and borders, are defined here.
To customize your mod's UI scheme, copy the original from
<Half-Life>/valve/resource/TrackerScheme.res
(updated for HL25) or
<Half-Life>/platform/resource/TrackerScheme.res
(not updated for HL25) into
<Half-Life>/<your_mod_here>/resource/TrackerScheme.res
.
The following block, for example, defines the font properties for the game menu.
"MenuLarge"
{
"1"
{
"name" "Verdana"
"tall" "18" // increase this to make menu items larger
"weight" "1000"
"antialias" "0" // set to 1 to enable anti-aliasing (why wouldn't you want anti-aliased texts?)
}
}
And the following block defines its colours and metrics:
InGameDesktop
{
"MenuColor" "200 200 200 255"
"ArmedMenuColor" "255 255 255 255"
"DepressedMenuColor" "192 186 80 255"
"WidescreenBarColor" "0 0 0 0"
"MenuItemVisibilityRate" "0.03" // time it takes for one menu item to appear
"MenuItemHeight" "28" // should be larger than the font size
"GameMenuInset" "32"
}
The following block allows you to add custom fonts that doesn't require the players to install into their OS (and of course, you need to ship the .ttf files along). If you do not see this block in the file, add them towards the end of the file (before the final closing bracket
}
).
//////////////////////// CUSTOM FONT FILES /////////////////////////////
//
// specifies all the custom (non-system) font files that need to be loaded to service the above described fonts
CustomFontFiles
{
"4" "resource/linux_fonts/DejaVuSans.ttf"
"5" "resource/linux_fonts/DejaVuSans-Bold.ttf"
"6" "resource/linux_fonts/DejaVuSans-BoldOblique.ttf"
"7" "resource/linux_fonts/DejaVuSans-Oblique.ttf"
"8" "resource/linux_fonts/LiberationSans-Regular.ttf"
"9" "resource/linux_fonts/LiberationSans-Bold.ttf"
"10" "resource/linux_fonts/LiberationMono-Regular.ttf"
"11" "resource/linux_fonts/FiraSans-Regular.ttf"
"12" "resource/linux_fonts/FiraSans-Medium.ttf"
// additional fonts go under this line. examples:
"13" "resource/SuperMystery.ttf" // Super Mystery
"14" "resource/Growl_rounded.ttf" // Growl_rounded
}
Check which branch of Half-Life you're running and targeting. There are major differences in the format and value of both GameMenu.res
and TrackerScheme.res
. As of writing the steam_legacy
version of these files would work on the default HL25 branch, but the reverse is not true.
To check or change branches of Half-Life from your Steam library, right-click Half-Life > Properties... > Betas > Beta participation dropdown. None = HL25, steam_legacy = pre-HL25.
autoexec.cfg
This file is executed at some point in the game initialization, and is a way to have a default
command list that is not managed by the game (
config.cfg
gets overwritten by the game when cvars and keybinds change.)
A common use case for
autoexec.cfg
is to ensure a certain set of
CVARs are set as default. For example, if a mod's art style demands the unfiltered pixelated textures look, it can define
gl_texturemode
with the appropriate value.
Another use case for
autoexec.cfg
is to define aliases, which is not possible with
config.cfg
. These are strings of commands you can execute in a single command, and bindable to keys. Aliases prefixed with + or - work as a pair, and used for keybinds (the + alias is executed on key down, the - one on key up). You can use this, and some script-fu, to have, for example, the Ctrl key toggle ducking, or a "bullet time" key.
I used to recommend using userconfig.cfg
here but autoexec.cfg is actually the better, and more apt, route for this.
CVAR config pages – settings.scr
and user.scr
Multiplayer Advanced dialog with a custom user.scr
See also: settings.scr and user.scr
This pair of files is a way of mapping the GUI to
CVARs in ways not covered by the standard engine GUI.
settings.scr
corresponds to the Create Server > Game dialog (for multiplayer server cvars)
user.scr
corresponds to Options [> Multiplayer] > Advanced dialog (for client and singleplayer cvars)
You can, for example, add a checkbox that toggles whether the game ignores textures embedded in maps (
r_wadtextures
), a text box to set your FOV (
default_fov
), or a drop down that lets you select between filtered or pixelated textures a-la software mode (
gl_texturemode
). Do make sure that you add only server cvars to
settings.scr
, and only client cvars to
user.scr
.
Keyboard bindings page – kb_act.lst
and kb_def.lst
Inside the file
gfx/shell/kb_act.lst
is the list of keybindable
commands, as seen in the
Options > Keyboard dialog. You may want to customize this file to give yourself and other players easier means to bind keys to custom aliases you may have defined in
autoexec.cfg
.
If your mod has custom code that adds new keybinds, you need to edit this file with the new entries, and ship this file.
The default keybinds are defined in
gfx/shell/kb_def.lst
and will be applied when the
Use Defaults button in the
Options > Keyboard dialog is pressed. Please use this instead of a custom
config.cfg
file.
commandmenu.txt
A commandmenu in game.
Half-Life and many first-party mods supports
commandmenu.txt
, though this feature is largely unknown outside of the TFC and CS communities.
You can use this feature, for example, to add a chapter selection menu, change
CVARs on the fly, or add a developer menu.
However, you'd need to edit
gfx/shell/kb_act.lst
and add a keybind option for
+commandmenu
as per aforementioned.
If you want to have your menu's command accept a text input (such as entering a map name), set messagemode <command_name>
as the command. This also applies to keybinds/aliases described elsewhere on this page.
skill.cfg
This file manages the skill system, defining NPC's health, ammo pickup, and damage dealt. Although it is
strongly advised against editing these, it is one way of
modifying the balancing of a mod without diving into code.
A Mod, or an Addon Pack? The <game>_addon
folder
Post-SteamPipe GoldSrc supports the [over]loading of files without overwriting the base file through the
<game>_addon
folder. This is also the case for HD and server-downloaded content via the
_hd
and
_downloads
suffixes.
Thus, some circumstances where separate mods were required before, might now be a simple drop-in into the
valve_addon
folder, without the risk of permanently corrupting your game. To disambiguate, lets call the _addon folder use case as an Addon Pack instead of a Mod.
Is my content a Mod or an Addon Pack?
Your content might fit the case of being an Addon Pack if:
- They are multiplayer maps.
- They are edits, additions, or upgrades to another base game/mod such as new background, custom models, etc.
- It's a short mission pack (but can still be considered a mod as otherwise people can't access your maps without typing in the console.)
- It's basically Half-Life but with a gimmick that doesn't involve custom maps.
- People might want to mix and match your content with other people's content.
On the other hand, you must distribute as a Mod if:
- You have custom server/client code.
- Your content is entirely self-contained.
Enabling addons on the 25th Anniversary branch
So, what changed?
An addon pack installs differently to a mod. Firstly you don't need the
liblist.gam just to add, say, custom models to Half-Life. Secondly, players can mix and match other things in their games, and they can toggle them on or off (details below), or otherwise jump between vanilla and modded setup quickly.
Other things about addons
To toggle the loading of this folder:
- Pre-Anniversary branch: Options > Video > Enable custom content
- 25th Anniversary branch: Options > Content > Allow custom addon content
The addon system
also works for mods! You can, for example, have addons for Poke646 populating the
poke646_addon
folder, and toggle them on and off.
The kitchen sink approach of this system is not great (compared to HL2's
custom/
folder) but it beats needing to surgically remove files, or reinstalling whole mods and losing saves due to corrupted modifications.
Distributing your mod/addon pack
You have your mod (or an addon pack). You want others to play them. You need to send these files to them. This raises a question: how, where, and which files?
What to [not] include
Firstly, it depends on whether you're distributing your content as a mod or an addon pack.
For mods:
- liblist.gam (and .dll/.so if using custom code) is required
- you're free to ship modified versions of titles.txt, sentences.txt, materials.txt, etc.
- you can have maps share textures in external WADs instead of packing them into the bsp files.
- custom assets can be organized however seems fit, but do consider how others might want to reuse them for addon packs of their own
- EXCLUDE: SAVE folder, config.cfg, unedited Half-Life base files e.g. halflife.wad
For addon packs:
- mapname.res is required for custom multiplayer maps
- game files such as titles.txt, sentences.txt, and materials.txt ideally shouldn't be changed
- packing all custom textures into the BSP means not having to distribute any WAD files
- organize sounds/models/sprites used in maps into subfolders (usually the map's name or the author's name). This is strongly endorsed by mods such as Sven Co-op.
For a general release, you wouldn't want to include the working files or file sources (e.g. the PSDs for the textures, or the source code*); only the end products needed for the game engine would suffice. These would be the files with extensions that includes but isn't limited to:
bsp, wad, res, mdl, wav, spr, tga, txt, mp3. Use a RES generator to double check that you didn't miss anything. If using a number of large WADs, consider extracting used textures and place them in a single WAD file that you reference in the maps to cut down on size.
A useful workflow to have is a mod folder for development (e.g.
mymod_DEV
), a separate folder for finalized mod files (e.g.
mymod
), and a script that copies over only relevant file formats from the former to the latter.
For a full source release that includes file sources, consider putting your mod files in an online Git repository instead.
TL;DR:
- ADD the sum of everything a resgen program reports to you, for every map
- SUBTRACT from the list files that comes with Half-Life or the base game/mod
- ADD liblist.gam (for mods only) and other modified game files
- If your mod contains custom code/entities, include the FGD, sample zoo/tutorial maps in rmf/jmf/bsp, etc.
- If your mod has a distinct style/setting, include your WADs (and your .rad files too!)
- Compile your map with
-wadinclude
, so that all textures are baked into the BSP and you don't need to distribute the WADs you used.
- Use
game_text
instead of a modified titles.txt
- For most games/mods, you can employ the 12-character materials hack to have your custom textures sound properly.
- Start with a separate mod folder from the get go. Don't develop it inside your Half-Life (valve) folder, then ship the entire folder, renamed or otherwise.
- Likewise if developing a mod on top of another mod, use liblist.gam's
fallback_dir
property and direct users to download that mod as a prerequisite instead of including all files from that mod, which is legally dubious.
For reference, the asset loading hierarchy is as follows (credit to
Yui/SirYodaJedi):
<moddir>_addon
<moddir>_hd (if enabled)
<moddir>
<moddir>_downloads
<fallbackdir>_addon
<fallbackdir>_hd (if enabled)
<fallbackdir>
<fallbackdir>_downloads
valve_hd (if enabled)
valve
platform
And as always,
give credit to the authors whose content you used in your mod.
Packing the files
The best practice is to pack the files into a ZIP archive, as most OSes natively support it. 7z is also a popular format that achieves better compression for larger mods.
Do not create an installer, as was common in the 00s. Those often made assumptions that has since been obsoleted (e.g. assuming you have WON, or asking for your Steam's email which no longer works after the SteamPipe update), create clutter on people's systems (e.g. desktop icons, entries in "installed programs", and uninstallers, all of which cease to work if you move your Steam library), and generally confuse more than help contemporary players.
For mods:
- With the Half-Life directory open, take the folder that contains your mod, and put it into an archive.
- Once the archive is created, check that inside the archive is that same folder, and the directory structure is preserved.
- If you have working files you wish to exclude, remove them at this stage.
For addon packs:
- With the addon folder open, select every file related to your content pack and add them to an archive.
- Once the archive is created, check that the archive contains your files and the directory structure is preserved (not flat.)
- If you have working files you wish to exclude, remove them at this stage.
Installation
To help would-be players, include a readme file in the archive directing them to extract the archive into the correct installation folder. Also provide them information to verify what a correct installation looks like.
Example install instruction for a mod:
INSTALLATION
1. In your Steam library, right click on Half-Life > Manage > Browse local files.
2. Extract the archive into that folder.
3. After extraction, find the folder <modfolder> inside the folder, which should also have the valve folder.
4. Restart Steam. The new mod should appear in your Steam library list.
Example install instruction for an addon pack:
INSTALLATION
1. In your Steam library, right click on Half-Life > Manage > Browse local files.
2. Inside that folder, create a new folder named "<gamefolder>_addon" if it doesn't already exists.
3. Extract the archive into the <gamefolder>_addon folder.
4. After extraction, you should find <example new file> inside <gamefolder>_addon/<path to new file>.
Never instruct players to install into valve
(or other mods) and overwrite the existing files. You may corrupt their existing games/mods, and when they're done with your stuff (or if your stuff breaks their game) they have no choice but to reinstall the game/mod, and they wouldn't be happy about it.
Don't forget to test your package to triple check that you didn't omit any mod assets. Temporarily rename your WIP mod/addon folder, do the installation steps, launch the mod, and load every map.
Hosting the files
There are several places on the Internet that can host your mod/addon files, including:
Some of these sites require you to fill a form, so have these information figured out in advance:
- General description and summary
- Installation directions
- Tools used
- Credits
- Licensing
which brings us to...
Licensing
Note: this is not legal advice. IANAL.
It's the last thing on your mind when you're in the zone. You might assume it'd be one of "here's the files, do whatever" or "credit me if you do stuff with it" and you'll be correct, but the platforms you distribute your mod under has other assumptions, and you may not want to go with the default.
The website
https://choosealicense.com/ can help you decide which license you want to distribute your mod under. Then, select the appropriate license type on the hosting website's upload form.
A few pointers:
- GameBanana defaults to Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International (CC BY-NC-ND 4.0). The "NoDerivatives" clause may not be what you want if you're putting out things like prefabs; in general preventing others from having their own take on your stuff and sharing it legally.
- Use GameBanana's custom license checklist. It presents you with a checklist of what you want to allow.
- TWHL defaults to "All rights reserved." Use any other license, unless you're absolutely sure you want to keep it a sealed box.
*Some licenses might obligate you include source files; for others, a link to a source repository (e.g. GitHub) would be satisfactory. Read the terms of the license you end up using.
**GPL licenses are NOT compatible with Half-Life SDK license.
In The End
🎉 Congratulations! You've published your mod (or addon pack)! 🎉
Hopefully the series has been helpful in assembling and getting your stuff out into the world, for other people to enjoy.
Also it's past midnight and I have to postpone integrating this to the rest of the tutorial's navigation.
-wadinclude
compile command-line argument andgame_text
entities. I think they are better suited for addon pack where you "can't" edit the original files and copying/pasting the original ones is not an option as if everyone was doing that, it would "overlap".For mods, shipping the WAD(s) and using titles.txt is fine since it's distributed as "standalone".