‎‎

Q3PLUS DOCUMENTATION – HUDS


You can highly customize the appearance of your HUD by the so called hud files.
The /hud <yourHUDname> command will load the file q3plus/hud/yourHUDname.cfg.

Note: There is the special default hud to disable the whole customizable HUDs.

So the command /hud default will disable and fallback to the default hud defined in the code.
To get your preferred HUD loaded automatically you can set the cg_hud variable in your config file.
Note that the /hud command will also set this variable for you.

Check out the great SuperHud Editor (github link). It provides a visual editor, reducing the creation of a new HUD to a few mouse clicks.


SYNTAX

The syntax has been derived from CPMA, so most HUDs should load just fine.

# single-line comment
// single-line comment
/* multi-line comment */

NetGraph {
   rect 592 432 48 48
   bgcolor 0.25 0.25 0.25 0.25
   fill
}

NetGraph { rect 592 432 48 48; bgcolor 0.25 0.25 0.25 0.25; fill; }

DIFFERENCES

There are some differences compared to CPMA.

All elements are optional. Loading an empty file will result in an empty screen.
In contrast, CPMA draws some elements even if not defined, probably the most noticeable one would be Console. We have a flexible z-layer.

Elements defined first will be drawn first, this PreDecorate and PostDecorate are just the same.
If you run into problems with your existing HUDs and overlapped elements, just change the order.
Such fixed HUDs will load fine in Q3Plus, Excessive Plus and CPMA.

Elements can be defined multiple times and each appearance will be drawn.
For example you can display your health two or even ten times all over the screen, if you fear the death.

Several elements can be disabled by the default variables like cg_drawFPS, even the Draw3D property can be overwritten by /set cg_draw3dicons 0.
Of course you can only toggle the display if the element is actually defined by the hud file. If there is no FPS defined, you cannot display the FPS with /set cg_drawFPS 1.

We have new properties not available for CPMA, namely: Anchors, Param and VerticalBar.


PROPERTIES

Note: All sizes, positions and drawing is done in an virtual 640x480 box and then scaled to your actual screen resolution.


Anchors Flags


Defines to which directions the element will be anchored relative to the drawn screen.
This property will be applied when cg_aspectRatio is enabled, which allows the HUD to not look stretched on non-4:3 resolutions.
The possible flags are:

1 - top
2 - right
3 - bottom
4 - left

Flags can be combined.
For example, the default value of 15 (which is 8 + 4 + 2 + 1) will anchor the element in all directions, which means that CPMA HUDs will look stretched, just like if cg_aspectRatio is disabled.

Angles Pitch Yaw Roll [ Pan | -Rotate ]


Used to alter the display of a Model.
The fourth value is optional, if given it will either pan or rotate the model, depending on the algebraic sign (positive or negative).

BGColor Red Green Blue Alpha

Defines the background color for the element, valid values are 0..1.
In combination with Rect and Fill this will fill the area with the color.


Color Red Green Blue Alpha or Color T | E


Defines the foreground color for the element, valid values are 0..1. Icons and image properties will use this color.
There are two special colors T and E, they will represent the colors red or blue depending on your current team.

Note: Define BGColor to control the alpha of these special colors.

DoubleBar [ 0 | 1 ]


Makes the elements StatusBar_ArmorBar, StatusBar_AmmoBar and StatusBar_HealthBar use two lines instead of one.

Note: If optional parameter is omitted it will default to 1.

Draw3D [ 0 | 1 ]


Will force the display of a 3d model. This can be overwritten by /set cg_draw3dIcons 0

Note: If optional parameter is omitted it will default to 1.


Fade Red Green Blue Alpha

If both Fade and Time are defined, the element will linearly fade from Color to this.

Fill [ 0 | 1 ]

Will fill the area defined by Rect with BGColor.

Note: If optional parameter is omitted it will default to 1.

Font fontname

Defines the font for an element. If omitted xp will be used.

xp is the default Q3Plus and Excessive Plus font
numbers supports only numbers, no letters
ui is the font used by Quake 3 UI
baseq3 will use the old Quake 3 font

Compatibility mode:

cpma, sansman will be xp with TextStyle 4 (lite)
idblock will be numbers
id will be baseq3
threewave will be baseq3 with TextStyle 8 (outline)

Any other fonts will output a warning and the default font will be used instead.

Note: It is highly suggested to use font xp for elements that can contain player names, because Q3Plus (XP) allows highly customized names with bold/lite styles and special characters not present in other fonts.

FontSize PointSize or FontSize Width Height

The default Q3Plus (Excessive Plus) font is already aspect-adjusted and generally looks best if you just specify the PointSize.
It is suggested to use a distinct Width and Height for all other fonts, with Height being 25-50% larger then Width.

Note: Negative values can be used to create mirrored text.


Image "path/to/image_or_shader"


Displays the image in the area defined by Rect. You can use any image or shader available in a PK3. If Color is present, it will colorize the image.
This can also be used to load a skin for a Model, just point the path to a .skin file.

Note: On a sv_pure enabled server you can only use images available in the PK3s the server provide.


Model "path/to/model.md3"

Displays a 3d model in the area defined by Rect. A specific skin can be loaded for that model with the Image "path/to/skin_name.skin" property.
Use Angles and Offset to further customize the display.


Monospace [ 0 | 1 ]

By default, all fonts are proportionally spaced. Meaning that an "i" takes up less room than an "m". Use this to get the old Quake 3 behaviour but generally this is not suggested.

Note: If optional parameter is omitted it will default to 1.


Offset X Y Z

Changes the offset of a Model along the X Y Z axis.


Param Value1 [ Value2 [ Value3 [ Value4 ] ] ]

Up to four special parameters for some elements.


Rect X Y Width Height

Defines the position and size of an element.

Note: Elements and especially Image can be mirrored using negative Width or Height values.


Text "some text here"

Will output the text in the area defined by Rect. Currently only supported by PreDecorate and PostDecorate.


TextAlign L | C | R

Justify the text either left, centered or right within Rect.

Note: In combination with some elements, this will define the element's position rather then it's text.


TextStyle Flags


1 - text will have a drop shadow
2 - ignores inline color codes and forces color defined by the Color property
4 - forces a text to be "lite". Only works in combination with the xp font
8 - text will have an outline shadow

Flags can be combined e.g. TextStyle 6 will be 4 (lite) + 2 (force color).


Time Interval

Defines how long the element will be displayed in milliseconds.


VerticalBar [ 0 | 1 ]

Makes the elements StatusBar_ArmorBar, StatusBar_AmmoBar and StatusBar_HealthBar be vertical instead of horizontal.

Note: If optional parameter is omitted it will default to 1.


ELEMENTS


!Default

This is a helper element and will not be drawn. Once defined, all followed elements will inherit properties from this element.
You can reuse this element as often as you want

PreDecorate and PostDecorate

Empty elements that can be used to draw decoration like separator bars, static Text, images etc.

Note: Because HUDs have a dynamic z-layer, both elements are the same and are just there for compatibility reasons.
The draw order is defined by appearance order in the file.

AmmoMessage


"LOW AMMO WARNING" and "OUT OF AMMO" message. Display can be toggled by cg_drawAmmoWarning.

AttackerIcon

Icon of the player who last attacked you. Time can be used.

AttackerName

Name of the player who last attacked you. Time can be used.

Chat1 till Chat8

Display up to eight lines of player chats. Time can be used.

Note: This can prepend the client number, depending on cg_drawClientNum.

Console

Replacement for the engine notify console. Time can be used. Display can be toggled with cg_drawNotify.


FlagStatus_NME


Status of the enemy flag in CTF gametypes.

Note: Use Color E to get a red or blue flag, depending on your current team.

FlagStatus_OWN


Status of your own flag in CTF gametypes.

Note: Use Color T to get a red or blue flag, depending on your current team.

FollowMessage

"Following <PlayerName>" message. Obviously will only display when following a player while spectating.


FPS

Frames per second. Can be toggled by cg_drawFPS.


FragMessage

"You fragged <PlayerName>" message. Time can be used.


GameTime

Displays the game timer. Can be toggled by cg_drawTimer.

Note: The last 60 seconds will display milliseconds while overtime will change color to cyan.


GameType

Displays the current gametype like "Freeze Tag" while spectating or during warmups.


ItemPickup

Name of the item you've just picked up. Time can be used.


ItemPickupIcon

Icon of the item you've just picked up. Time and Draw3D can be used.


NetGraph

Displays your net graph or lag-o-meter. Can be toggled by cg_lagometer.


NetGraphPing

Displays your current ping, based on the net graph. Can be toggled by cg_drawPing.


PlayerSpeed

Your current speed on the X-Y-axis in units per second. Can be toggled by cg_drawSpeed.


Powerup1_Icon till Powerup4_Icon

Powerup icons. Draw3D can be used.

Note: CTF gametypes will display the flag in Powerup1_Icon while you hold it.


Powerup1_Time till Powerup4_Time

Powerup time left in seconds.


RankMessage

"1st place with 12" message. Time can be used.


Score_Limit

Fraglimit, Roundlimit or Capturelimit. Can be toggled by cg_drawScores.


Score_NME

Enemy score. Can be toggled with cg_drawScores.

Note: Use Color E in combination with Fill to get a red or blue background, depending on your current team.


Score_OWN

Your score. Can be toggled with cg_drawScores.

Note: Use Color T in combination with Fill to get a red or blue background, depending on your current team.


SpecMessage

Help message for spectators, explaining the keys or informing about your thaw status in Freeze Tag.


StatusBar_AmmoBar, StatusBar_ArmorBar, StatusBar_HealthBar

Current ammo/armor/health in bar form. For a single bar, it will get full when it reaches the hard limit.
DoubleBar can be used to get two lines instead of one, representing the soft and hard limits.
TextAlign will change the alignment of the whole bar and Image can be used to customize it even further. Can be toggled by cg_drawStatus.

This element accepts an additional Param, which can be a combination of the following flags:

1 single bar will behave like the second bar of DoubleBar
2 single bar will get full when it reaches the soft instead of hard limit

Combining those flags on different bars can achieve some fancy effects. See hud/qlive_snippet.cfg for an example.

Note: If Color alpha is 0, flexible color will be used. Red for critical, orange/yellow for normal and white for over limit values.


StatusBar_AmmoCount, StatusBar_ArmorCount, StatusBar_HealthCount

Current ammo/armor/health in numeric form. Flexible colors are enforced. Can be toggled by cg_drawStatus.


StatusBar_AmmoIcon, StatusBar_ArmorIcon, StatusBar_HealthIcon

Current ammo/armor/player icon. Draw3D can be used. Can be toggled by cg_drawStatus.

Note: If both Image and Model is ommited in StatusBar_HealthIcon, your current model will be used.


TargetName

Current crosshair target's name. Can be toggled by cg_drawCrosshairNames.


TargetStatus

Current crosshair target's status, only available for team members. Can be toggled by cg_drawCrosshairNames.


TeamCount_NME

Players alive on enemy team, only for Freeze Tag and Clan Arena. Can be toggled by cg_drawScores.


TeamCount_OWN

Players alive on your team, only for Freeze Tag and Clan Arena. Can be toggled by cg_drawScores.


TeamIcon_NME

Defaults to red/blue Sarge icon, depending on your team. You can use any Image or Model.


TeamIcon_OWN

Defaults to red/blue Sarge icon, depending on your team. You can use any Image or Model.


Team1 till Team8

Teamoverlay for up to 8 team members. Can be toggled by cg_drawTeamOverlay. TextStyle will change alignment for the whole element.

Note: The column design will be kept, no matter if Monospace is set or not. Generally it will look better without.


VoteMessageWorld

Current vote text.

Note: Votes can be called at the end of a map, while the scoreboard is displayed. A position should be taken to work for both, in-game and scoreboard.


WarmupInfo

"Waiting for players", "Warmup", "Starts in: X" etc.


WeaponList

The weapon list has some special settings that differ from the rest.

The Width and Height are for each weapon, not the total. TextStyle can be used to have a horizontal or vertical weapon list.
Color defines the color for your current selected weapon and Fill will show ammo for weapons you do not have.

Note: The list will wrap at the bottom of the screen for both vertical styles. This way you can get a multi-column list.