# ezQuake Manual: Head Up Display - HUD

This client has MQWCL's customizable Head Up Display.

## Examples

Type one of the following lines into the console to load example HUD configurations:

    /exec cfg/hud_berzerk
    /exec cfg/hud_corner
    /exec cfg/hud_dobbz
    /exec cfg/hud_empezar
    /exec cfg/hud_murdoc
    /exec cfg/hud_vleesh

This client allows you to modify your HUD as you wish, you can choose which HUD elements to draw, where to draw them, how to draw them and how large to draw them.

You can either use your keyboard to move, hide and show, align, group, scale and change style of HUD elements on your screen or you can learn using commands to customize the HUD.

## Customizing HUD with keyboard

Since ezQuake version 1650 you we provide you a way to do most of the customization using your keyboard. To start with that, go to the game, join/start a map and type following:

    /exec cfg/ezhud

A list of instructions now appears on screen / in console. You should notice that you can select hud elements using your `[` and `]` keys, move them using arrow keys, and perform other actions using keys on the numpad, page up, page down, home, end, insert, delete, space, enter, z, x, c, v, combine some keys with shift, and finally save your work by pressing `U` key.

You get your config saved into the <quake>/ezquake/configs directory. It's full name will be printed on the screen.

## Customizing HUD with commands

Some specific HUD elements have specific properties which you cannot change using the way described above and you might also want to know all the potential this client offers you in HUD scripting. Here you will learn how to customize the HUD using commands you type into console or configuration files.
Following text is based upon MQWCL HUD readme.

To enable new HUD, you have to type `/scr_newhud 1` - which disables FuhQuake-originated HUD. If you're missing some features of FuhQuake HUD, you can combine those two HUDs using `/scr_newhud 2`.

This flexibility comes at a price though, it usually takes a while to understand how to work with the HUD system, but once you've managed that, it will be great fun to design your very own Quake HUD.
Check the examples throughout this document, if you have any problems with understanding the HUD system.

## Contents of this document:

1. What is a HUD element?
2. Showing and hiding
3. Moving HUD elements
   1. Possible places
   2. X-alignment
   3. Y-alignment
   4. Relative positioning
   5. Add/remove frame
4. HUD elements
   1. armordamage
   2. clock
   3. frags
   4. fps
   5. healthdamage
   6. net
   7. netgraph
   8. ping
   9. speed
   10. teamfrags
   11. tracking
5. HUD variables
   1. hud_planmode <0|1|2>
   2. hud_tp_need <0|1>

## What is a HUD element?

A HUD element is a single 2D element, that can be drawn on-screen, moved to different positions, aligned etc. For most HUD elements it's also possible to display a frame in the background behind them.

Every HUD element has a name which is a string, like "netgraph", "fps" etc.. You use that name in HUD commands, like "show netgraph". The HUD element used remembers all its settings (its properties) as variables, which are named hud_<hud_name>_<property_name>.

Examples:

hud_netgraph_frame
  This will display the current setting for the netgraph frame
hud_ping_period
  This will determine how often the ping display will be updated.

Changing a property of an element is simple. Obviously, a simple way to do this is changing the appropriate variable, however there is a more convenient way: try typing the element name at console, like this:
`netgraph [ENTER]`
You will see some infos about netgraph and a list of its properties with its current values. If you want to change some - it's easy:

netgraph frame 0
  This will disable the background graphic drawn behind the netgraph.
netgraph show 0
  This will disable that the netgraph is displayed (same as hide "netgraph").

It's possible to use TAB completion for HUD properties, so if you type "netgraph inf" and press [TAB], it should complete. All variables for HUD elements (hud_*_*) are hidden.

Some properties (like "show") are controlled by commands (like "show" and "hide"). Some of them (those for setting element position) will not have a effect if you change them directly by variables. If you do so and you see no change, try the "hud_recalculate" command.

## Showing and hiding

To show a certain HUD element, use the "show" command with the element name as a parameter. Giving no parameters will display a list of all HUD elements with their current status. There is a special parameter "all" which you can use to show all elements.

Examples:

show netgraph
  This will display the netgraph.
show fps
  This will display your current FPS.
show
  This will print a list of all HUD elements on the console as well as their current settings.
show all
  This will display all hud elements.

The opposite to "show" is the command "hide", which obviously hides the specified HUD element. The current status is remembered as a "show" property, so typing "show netgraph" will have the same effect as typing "netgraph show 1".

## Moving HUD elements

When you want to move a certain HUD element, first you have to decide what screen area it occupies, the command used for placing a HUD element is: "place <element-name> <where-to-place>".

### Possible places

screen
  visible part of the screen
view
  view area (depends on viewsize variable)
top
  area above status bar
sbar
  status bar area (health bar + inventory bar, no free space after sbar, if you play at higher res)
ibar
  inventory bar (upper part of sbar)
hbar
  health bar (lower part of sbar)
sfree
  free area after status bar (if res > 320 or hud_sbar_size changed)
ifree
  free area after inventory bar
hfree
  free area after health bar

Examples:

place netgraph screen
  place the netgraph on the screen
place fps top
  place the fps in the area above the status bar
place health hfree
  place te health in the free area next to the health bar

If you have a place for your favorite element, align it to some edges. The command is "align <element-name> <X-alignment> <Y-alignment>".

### X-alignment

left
  left edge of area chosen by "place"
center
  center
right
  right area
before
  explained later in this document
after
  explained later in this document

### Y-alignment

top
  top edge
center
  center
bottom
  bottom
console
  below console (like clock by default)
before
  explained later in this document
after
  explained later in this document

Examples:
align netgraph left top | left upper corner
align fps right bottom | right lower corner

Finally, if the element position still does not match your preferences, you can fine-tune it by using the command "move <element_name> <X-offset> <Y-offset>". Offsets can be either negative or positive. Setting a positive X-offset moves the element to the right, and a positive Y-offset moves the element to the bottom.

Examples:
move netgraph 2 2 | move the netgraph 2 pixels right and 2 pixels down
move fps -10 5 | move the FPS 10 pixels left and 5 pixels down

Note that your element will not be drawn, if you locate it off the screen, even partially.

All those commands ("place", "align", "move") can be used without parameters, (print help then) or with on parameter - HUD element name. Then current values are printed.

### Relative positioning

You can align some elements relative to other elements. First you have to decide, if the element that you are locating now (element B) is to be positioned inside another element (element A) or outside it.

If inside do | place A @B
If outside do | place A B

Examples:

- place fps @net
- place health face
- place iammo health
- place ammo iammo

Then you have to align it. If you want to place it outside, you have some additional alignments - before and after.

Examples:

- place health after top
- place iammo after top
- place ammo after top

and you have a nice chain combined of health, armor and it's icons.

The difference between inside and outside placing can easily be seen if you add a frame to your elements and enlarge them (for example by using frame 2).

### Add/remove frame

Frame is a regular property, it differs a little because every HUD element can have a frame. Values for frame property are:

0 | no frame
(0..1) | transparent frame, lower number means more transparency
1 | black frame
2 | a box like that for netgraph

Examples:

net frame 2
  add nice frame for network statistics
netgraph frame 0
  make netgraph more useful
fps frame 0.6
  make FPS more readable

### HUD elements

Currently the list of HUD elements contains few elements for occasional use (like netgraph), many elements taken from your status bar (reorganize your screen with them) and additional "group" objects, which display nothing (except frame if enabled) and can be used for grouping some objects together (like ammo counts).

Full list is:
ammo | current ammo value
ammo1 | number of shells
ammo2 | number of nails
ammo3 | number of rockets
ammo4 | number of cells
armor | armor level
armordamage | amounf of received damage to armor
clock | clock
face | player face
fps | fps counter
frags | small scoreboard
group1 | grouping object
group2 | grouping object
group3 | grouping object
group4 | grouping object
group5 | grouping object
gun | current weapon icon
gun2 | shotgun icon
gun3 | super shotgun icon
gun4 | nailgun icon
gun5 | super nailgun icon
gun6 | grenade launcher icon
gun7 | rocket launcher icon
gun8 | lightning gun icon
health | health level
healthdamage | amounf of received damage to health
iammo | current ammo icon
iammo1 | shells icon
iammo2 | nails icon
iammo3 | rockets icon
iammo4 | cells icon
iarmor | armor icon
key1 | silver key
key2 | gold key
net | net statistics
netgraph | everything about net
pent | pentagram icon
ping | small net statistics
quad | quad icon
ring | ring icon
sigil1 | sigil 1 icon (rune)
sigil2 | sigil 2 icon
sigil3 | sigil 3 icon
sigil4 | sigil 4 icon
speed | your current speed
suit | suit icon
teamfrags | number of frags per team
tracking | name of tracked player

Every element has its own properties. You can check them, by simply typing the element name in console. Some common properties are described below, which affect your inventory elements (guns, health etc):

align
  used for numbers (health, armor etc..) and determines how they should be aligned
digits
  used for numbers and specify how many digits they should display, for example to save space, you can have your ammo printed only with two digits, it will always show 99 if is more than 100
frame
  You can set the opacity of background of current element where 0 equals transparent background and 1 is solid background.
scale
  This is mostly for GL users and currently it doesn't work in the software renderer. This lets you change the size of an element, for example you can make health 2 times bigger. With scale you can make a HUD that looks like in 320x200 (big numbers) and still have -width 640 without conwidth, so your console holds more text.
style
  This always changes the look of the element, styles are different, depending on the element type. Usually there is one style which, when enabled, enables text-mode look of element (like gun6 is "gl", health level with small text etc.). Style values are cardinal numbers (0, 1, ...).
wide
  only used with "gun" and "gun8" and affects style of lightning gun icon

Grouping elements have only two properties (width and height), they should be self-explanatory.

## Specific HUD elements

Below are some HUD elements that may be of interest. All of them have the property "frame" even though it is not listed. You can check the status of properties of a certain element by typing "<name of the HUD element> <property>".

Examples:

- clock style
- fps frame

You can change their value with "<name of the HUD element> <property> <value>".

Examples:

- fps frame 1
- ping period 0.5

Also all of the below elements have +/- commands to enable/disable them for easier binding. These commands always look like this: "+hud_<name>".

Examples:

- +hud_netgraph
- +hud_speed

### armordamage

Displays amount of damage done to your armour.

Properties are:

duration
  Adjusts the period of time after which the information vanishes from the screen.

### clock

This displays the current local time (hh:mm). As stated above, it is a HUD element.

Properties are
big | if should be BIG,
blink | if ':' should blink,
style | check yourself, values are (0, 1) for big one, and (0, 1, 2, 3) for small one

### fps

The FPS counter is a HUD element now, so you can place it wherever you want.

Properties are:
show_min | show minimum framerate in last second
title | if the annoying "fps" text should be displayed

### frags

Displays short version of scoreboard, shows amount of frags per player.

Properties are:

teamsort
  Players will be sorted according to teams first.
cols
  Number of columns.
rows
  Number of rows.
cell_width
  Width of each table cell (pixels).
cell_height
  Height of each table cell (pixels).
vertical
  Sorts cells in vertical order first.
strip
  Cut the element size according to number of players.
space_x
  Horizontal margin.
space_y
  Vertical margin.

### healthdamage

Displays amount of damage done to your health.

Properties are:

duration
  Adjusts the period of time after which the information vanishes from the screen.

### net

This element displays statistics about your connect. It used to be "+shownet", but since this has now been transformed into a HUD element, there is no use for "+shownet" anymore.

Properties are:

period
  time between recalculates (for example if it is "3", the statistics are recalculated every 3 seconds and contain data from the last 3 seconds), the minimum period is your frame time.

### netgraph

The netgraph has been made a HUD element, it is a good tool to monitor your ping and see how it changes during battles. However, in QWCL the netgraph had ugly scale, and your ping was nearly invisible unless it was > 100. This is changed in this client and its HUD features, you can now change the scale, width, height, background etc.

Properties are:

alpha
  this lets you regulate netgraph transparency, mostly for use if your netgraph does not have a frame (netgraph frame 0), it's available only in GL version of this client.
full
  check yourself, netgraph is more detailed this way, but looks ugly; in GL this can be fixed with a lower alpha value like "0.4"
height
  height of graph-part
inframes
  setting this to "1" lets you measure your latency in an alternate way every level of netgraph will mean one frame of delay, between sending it to server and getting answer. On local/lan server you'll always get one frame of delay, even with low FPS.
lostscale
  lets you cut down those red, yellow, blue and gray bars, which are always full-height; possible values are the range from 0 to 1
ploss
  print packet loss or not
scale
  sets the maximum ping that the netgraph is able to display, by default "256". As you can easily check, netgraph has 16 levels (unless it is "full 1"), so default value of 256 means every level is 16 ms of ping.
swap_x
  reverse horizontally, like for placing at left edge of the screen
swap_y
  reverse vertically, like for top edge
width
  width of graph-part

Note, that some of these properties/variables are used by server browser connection tester. These are: alpha, full, inframes, lostscale, scale.

### ping

This HUD element displays your ping and by default your PL as well.

Properties are:

blink
  enable yellow blinking dot, which shows when your ping is recalculated
period
  period of time between updates (minimum value is your frame time)
show_dev
  show standard deviation of each period
show_min
  show minimum ping of each period
show_max
  show maximum ping of each period
show_pl
  show current packet loss

### speed

The speed display is a HUD element now, so the "show_speed" variable is no longer needed and has thus been removed.

Properties are:

xyz
  This toggles whether the speed is measured over the XY axis (xyz 0) or the XYZ axis (xyz 1)

### teamfrags

Displays short version of scoreboard, shows amount of frags per team.

Properties are:

cols
  Number of columns.
rows
  Number of rows.
cell_width
  Width of each table cell (pixels).
cell_height
  Height of each table cell (pixels).
vertical
  Sorts cells in vertical order first.
strip
  Cut the element size according to number of teams.
space_x
  Horizontal margin.
space_y
  Vertical margin.

### tracking

Displays nickname of tracked player while being spectator or watching demo. Usually displays instruction how to change point of view (POV) to next player too.

Properties are:

alttext
  If you don't like default text content of this element you can change it using this property.

## HUD variables

Here are some variables, which will be useful when changing the design of your HUD:

hud_planmode

  0 | display all items normally (default)
  1 | draw all items as if you have them; this for planning your HUD, for example you can move the quad icon to the desired position, because you see this icon even if you don't have quad at the moment; you should rather not play or do "cfg_save" with that

hud_tp_need

  0 | do not apply teamplay need settings to status bar drawings
  1 | this will apply teamplay need settings to your status drawings, like your health will be red if below "tp_need_health", not if below 25, armor will depend on tp_need_ga, tp_need_ya, tp_need_ra, not always red if below 10 etc

Last update: 28.09.2006 02:13 PDT, made by JohnNy_cz | ezQDocs