Flexible HUD for ioq3

Aspect correct widescreen HUD in Quake 3 on q3dm11.

ZTM’s Flexible HUD mod for ioquake3 (Quake 3 and Team Arena expansion).


This mod is based on the ioquake3 mod code. The default changes are that the HUD will be aspect correct and the Quake 3 start server menu will display 8 maps instead of 4. You can configure the HUD with cvars listed below.

For the flexible hud mod to be used in multiplayer the server needs to run Quake III Arena (baseq3) or Team Arena (missionpack) and not some other mod, and have pure mode disabled (set sv_pure cvar to 0) or have the flexible hud pk3 files installed on the server. This means it will not work on most public servers.

This is available as-is. I have no interest in providing support for it or making it work with other mods. You can ask for help or provide help to other users on Discord at Clover.moe Community’s #idtech3-general channel.

If you’re playing single player, want instagib and/or unlagged modes, or want to host a server for using this mod you would likely have a better experience using Spearmint Quake 3.

Known issue: The first person gun model is not displayed correctly with widescreen field of view. This is due to the field of view (FOV) of the weapon model being the same as the world FOV. This is fixed in Spearmint where the first person gun model has a separate FOV (cg_weaponFov cvar, 90) but I haven’t got around to fixing it in the flexible hud mod which requires an entirely different method to implement it.


Download [release 7, October 7, 2019]: ztm-flexible-hud-r7.zip

Download the zip and put the flexible hud pk3 files in your baseq3 and missionpack folders.

If “vm” directory exists in ioquake3’s baseq3 and missionpack folders rename it to “vm-ioq3”, otherwise it will override the mod files in flexible hud pk3.

New Cvars

cg_stretch [0 – 1] stretch 4:3 HUD to fit screen (default: 0)

cg_fovAspectAdjust [0 – 1] automatically convert 4:3 cg_fov values to current aspect (default: 0)
cg_fovGunAdjust [0 – 1] controls gun offset based on FOV. 0 uses Q3A code, 1 uses new code (works with FOV < 90 and fixed FOV dmflags) (default: 0)

The following cvars all default to 1. Only cg_drawWeaponBar is usable in Team Arena.
cg_statusScale [0.0 – 1.0] set scale of status bar (ammo, health, head, armor, CTF flag).
cg_drawStatusHead [0 – 2] 0 disables drawing head, 1 acts like Q3A, 2 drawing health item instead (supports 3D and 2D icons).
cg_drawPickups [0.0 – 1.0] set scale of item pickup message (0 to disable).
cg_drawWeaponBar [0.0 – 1.0] set scale of weapon select popup (0 to disable).
cg_drawScores [0 – 1] toggle drawing scores in bottom right corner (no scaling support).

Recommended Settings

cg_stretch 0; cg_fovAspectAdjust 1; cg_fovGunAdjust 1; cg_fov 90;

Aspect correct widescreen HUD in Team Arena on mpq3ctf1.

Source Code

The source code is available on GitHub licensed as GPLv2+ in the zturtleman/ioq3 repository in the flexible_hud branch and flexible_hud-r7 tag.

git clone https://github.com/zturtleman/ioq3.git zturtleman-ioq3
cd zturtleman-ioq3
git checkout flexible_hud-r7

Other Notes

The pk3s contain cgame QVM for HUD changes. They also contains qagame and ui QVMs. This allows me to distribute improvements to them (committed to ioquake3) and fix local server player pain sounds due to ioq3’s qagame <-> cgame communication not being compatible with official Quake 3 QVMs.

cg_fovAspectAdjust is based on a formula posted by LordHavoc and implemented in QtZ by Razor.

Widescreen support is based on Spearmint Quake 3. However, Spearmint Quake 3 does not have cg_stretch 1, cg_drawStatusHead, cg_drawWeaponBar, or hud scaling options.

Past Versions

Release 1, November 7 2013: ztm-flexible-hud-r1.pk3 (baseq3)
Release 2, August 30 2014: ztm-flexible-hud-r2.pk3 (baseq3)
Release 3, May 29 2017: ztm-flexible-hud-r3.pk3 (baseq3)
Release 4, May 14 2018: ztm-flexible-hud-r4.zip (baseq3 and missionpack)
Release 5, October 11 2018: ztm-flexible-hud-r5.zip (baseq3 and missionpack)
Release 6, November 16 2018: ztm-flexible-hud-r6.zip (baseq3 and missionpack)

The source code for release 1 and 2 can be obtained by applying a patch in the pk3 file (a renamed zip file) to ioquake3’s source code. The ioquake3 git version is included in patch file. The source code for release 3 and later are tagged as flexible_hud-r3 etc in zturtleman/ioq3 GitHub repo, see Source Code section above.