TF2 HUD editing: how to change a HUD's files by hand

A TF2 HUD is a folder of text files. Editing a HUD means opening those files and changing numbers and names: where a panel sits, how large it is, which font and colour it uses. This page explains the files and the values in them. To change a HUD without touching files, use the HUD builder in your browser.

What you need to edit a TF2 HUD

A text editor. The HUD reference by JarateKing advises against Notepad, because of how it handles line endings, and names Notepad++ and VS Code among the alternatives.
GCFScape, to open the game's VPK files and take the default files out.
VTFEdit, only if you want to change images. HUD images are in the VTF format.

The folders of a HUD

A HUD is a folder inside tf/custom. Its name is yours to choose. Inside it:

File or folder	What it holds
`info.vdf`	Tells the game which version of the interface the HUD was made for.
`resource/clientscheme.res`	The named colours, fonts and borders that the other files use.
`resource/ui/*.res`	One file per part of the HUD: hudplayerhealth.res, hudammoweapons.res, scoreboard.res and so on.
`scripts/hudlayout.res`	Where most panels sit on the screen and how large they can be.
`scripts/hudanimations_tf.txt`	The animations, such as low health flashing and changing colour.
`scripts/hudanimations_manifest.txt`	The list of animation files the game loads.
`materials`	The images the HUD uses.

Every HUD needs an info.vdf like this one. The reference says that most HUD files do not load when the file is missing or the number is too low. The default HUD is at 3 today.

"MyHud"
{
    "ui_version"    "3"
}

A HUD does not need every file. A file that is not in your HUD is loaded from the game, so a HUD can hold only the files it changes. Take those from the default HUD files or from an existing HUD you installed.

What a .res file says

A .res file is a list of elements. Each element is a name with a block of values in curly brackets. This is the ammo panel in the default hudlayout.res:

HudWeaponAmmo
{
    "fieldName"     "HudWeaponAmmo"
    "visible"       "1"
    "enabled"       "1"
    "xpos"          "r95"
    "xpos_minmode"  "r85"
    "ypos"          "r55"
    "ypos_minmode"  "r36"
    "wide"          "94"
    "tall"          "45"
}

xpos and ypos place the element across and down the screen.
wide and tall set its size.
zpos, where it is present, decides which of two overlapping elements is drawn on top: the higher number.
visible and enabled turn the element on and off. The reference warns that the game forces many elements on whatever these say. Its way to hide such an element is to move it off the screen with an xpos of 9999.
A value that ends in _minmode replaces the plain one in minimal HUD mode.

Positions and sizes

The numbers are not pixels. The screen is always 480 units tall. Its width in units depends on the aspect ratio: 640 at 4:3, 768 at 16:10 and about 853 at 16:9. A letter in front of the number changes where the count starts.

xpos or ypos	What it means
`50`	50 units from the left edge for xpos, or from the top for ypos.
`r50`	50 units from the right edge for xpos, or from the bottom for ypos.
`c50`	50 units right of the centre for xpos, or below it for ypos. A negative number goes the other way.
`rs1.0`	Like r, counted in the element's own size: 1.0 moves it in by its full width or height.
`cs-0.5`	Like c, counted in the element's own size: -0.5 puts its middle on the centre of the screen.

wide or tall	What it means
`50`	50 units wide or tall.
`f0`	The full width of the screen at every aspect ratio.
`p0.5`	Half of the screen's width for wide, or of its height for tall.
`o0.5`	The same share, taken from the other direction. With a p value on the other line it makes a square.

A panel in hudlayout.res also cuts off what is inside it. The reference notes that an element which is larger than its panel, or sits outside it, is not drawn. Some HUDs make the panel cover the whole screen, with wide f0 and tall 480, and place everything in the element's own file.

Colours and fonts: clientscheme.res

clientscheme.res has a section for colours, one for fonts and one for borders. A colour is a name with four numbers: red, green, blue and alpha. A font entry has a name that the other files refer to, the font to use, a height in tall and antialias for smooth edges. To change the size of a number on the HUD, find the font name its element uses and change tall in that entry. The TF2 fonts guide lists the game's fonts and shows how to add one.

See a change without restarting

Command	What it does
`hud_reloadscheme`	Reloads the HUD's layout and animation files while the game runs.
`vgui_cache_res_files 0`	The setting the HUD reference recommends while you reload HUD files. 1 by default.
`vgui_drawtree 1`	Opens a list of every panel that is drawn, with its name. It works only while sv_cheats is 1.
`vgui_drawtree_draw_selected 1`	Highlights on the screen the panel you select in that list.
`showschemevisualizer`	Shows the colours, borders and fonts of a scheme file. With no name after it, clientscheme.res.
`cl_hud_minmode 1`	Turns on minimal mode, to check the values that end in _minmode.

hud_reloadscheme has limits. The reference says it does not reload clientscheme.res or most menus, so a new font or colour shows after you restart the game. Type the commands in the console.

Which file draws what

tf2-res-file-list by cooolbros is a table of HUD files with a screenshot of what each one draws. In the game, vgui_drawtree 1 shows the name of every panel that is on the screen.

Make it work on Linux

Linux tells upper and lower case apart in file names, and the reference says every file name has to be lower case to load there: resource/ui/mainmenuoverride.res, not Resource/UI/MainMenuOverride.res. It also says fonts on Linux need 0.8 times the size they have on Windows to look the same. The HUDs for Linux list shows the HUDs whose authors list Linux support.

Where this comes from

How the files work is from TF2-Hud-Reference by JarateKing (MIT licence), which goes much further than this page: animations, materials, health, ammo and damage numbers each have a chapter. The ammo panel and the version number are from the default HUD files in TF2-Default-HUD. What the commands do is from the reference and from the game's own help text, as listed in mastercomfig's docs.

Start from a HUD that already has options to switch on, in the customizable HUDs list, put a custom crosshair in a HUD, add transparent viewmodels, or go back to the default HUD.