
Challenge ProMode Arena: Client HUD Settings
--------------------------------------------
Date : 7-Jul-2007

This is a snapshot of http://www.promode.org/wiki/index.php/Custom_HUDs
The wiki will almost certainly be more up to date than this document.

Since the release of CPMA 1.34 we have had extremely configurable HUDs.
This document explains some of the Client HUD settings for CPMA.
It will never be as current as the changelog, so you should always
check that with each new release.

Note: cvars such as cg_drawfps, cg_drawtimer plus many others have been
removed and their functions moved to the custom hud.

Creating a HUD .cfg
-------------------
    * ALL hud configs go in Quake3/cpma/hud. CPMA's sample HUDs 1-7 are
      also in that directory. 
    * You can select a config using \ch_file hud where 'hud' is the file
      you would like to use (without .cfg). You do NOT \exec hud. 
    * Use \reloadHUD to reload your HUD if you have changed it. Must 
      also be used after \ch_file change. 
    * The default HUD is in the PK3: if you want to customise it, pull it
      out of there with the unzip utility of your choice, RENAME it, and
      put the copy in cpma/hud/. Remember to point ch_file at the new version. 
    * The default HUD references (nearly) everything that can be drawn.
      Hud7 has nice examples of decoration use. 


Syntax
------
The syntax for CPMA's SuperHud is fairly easy to comprehend, and supports
both multi-line and single-line arguments.

ELEMENT
{
    ELEMENT_COMMAND VALUE
    ELEMENT_COMMAND VALUE
}

ELEMENT { ELEMENT_COMMAND VALUE; ELEMENT_COMMAND VALUE; }

You can comment using #. // cannot be used.
Some Element Commands have optional "," separators.


Elements
--------
Each piece of the HUD is called an ELEMENT. Elements are sorted z-layer-wise
alphabetically.

!DEFAULT
    The first element in the hudfile MUST be "!DEFAULT", and every other
    element inherits from that default: this gives you an easy way to change
    fonts/colors/etc for a whole bunch of elements at once. !DEFAULT can be
    reused later in the document affecting every following element but it
    will not overwrite the parameters set by previous !DEFAULT(s). It is
    advisable to place Team1-8 and Chat1-8 at the bottom of your hud config
    so that !DEFAULTs can be used without interfering with other elements.

AmmoMessage
    Low ammo/Out of ammo. The audio feedback "click" can be toggled using
    cg_ammoWarning. 

Chat1-8
    Chat area - if you want the order of the messages reversed then reverse
    the Y coordinates.

Console
    Replacement for ID's console. Use with con_notifyTime -1. 

FlagStatus_NME
    Status of enemy flag. To get old RED/BLUE use color T and color E, plus
    bgcolor. Check hud/old.cfg. 

FlagStatus_OWN
    Status of your flag. To get old RED/BLUE use color T and color E, plus
    bgcolor. Check hud/old.cfg. 

FollowMessage
    Following <Player> 

FPS
    Frames Per Second 

FragMessage
    You fragged <Player> 

GameTime
    Game Clock 

GameType
    Game Type - warmup only. Cannot be omitted. To hide place at off-screen
    x,y coordinates or set alpha 0. 

ItemPickup
    Text string of whatever item you pick up 

ItemPickupIcon
    Icon of whatever item you pick up 

NetGraph
    Lagometer 

NetGraphPing
    Ping 

PlayerSpeed
    Units Per Second 

PowerUp1_Icon to PowerUp4_Icon
    Powerup Icons. PowerUp1_Icon is also used for the O/D indicator in CTFS
    - and also for FLAG 

PowerUp1_Time to PowerUp4_Time
    Powerup Time remaining

RankMessage
    Placed 1st with 30 frags 

Score_Limit
    Frag/Cap limit (if set) 

Score_NME
    Enemy score. Cannot be omitted. To hide place at off-screen x,y
    coordinates or set alpha 0. To get old RED/BLUE use color T and
    color E, plus bgcolor. Check hud/old.cfg. 

Score_OWN
    Your score. Cannot be omitted. To hide place at off-screen x,y
    coordinates or set alpha 0. To get old RED/BLUE use color T and
    color E, plus bgcolor. Check hud/old.cfg. 

SpecMessage
    SPECTATOR, FRAGGED (in CA/CTFS/FT) 

StatusBar_ArmorBar
    Armor level in bar form 

StatusBar_ArmorCount
    Armor level in number form 

StatusBar_ArmorIcon
    Type of armor - essential in CPM but irrelevant in VQ3 

StatusBar_AmmoBar
    Ammo level in bar form 

StatusBar_AmmoCount
    Ammo level in number form 

StatusBar_AmmoIcon
    Current weapon ammo icon 

StatusBar_HealthBar
    Health level in bar form 

StatusBar_HealthCount
    Health level in number form 

StatusBar_HealthIcon
    Defaults to Mynx icon but can be any model, image or shader found in
    pk3s (provided that the pk3 is on the pure server you join) 

TargetName
    Current target's playername - requires cg_drawCrosshairNames 1 or 2

TargetStatus
    Current friendly target's health/armor level - requires
    cg_drawCrosshairNames 1 or 2

TeamCount_NME
    Players alive on enemy team (CA/CTFS/FT) 

TeamCount_OWN
    Players alive on your team (CA/CTFS/FT) 

TeamIcon_NME
    Defaults to Sarge icon but can be any model, image or shader found in
    pk3s (provided that the pk3 is on the pure server you join) 

TeamIcon_OWN
    Defaults to Mynx icon but can be any model, image or shader found in
    pk3s (provided that the pk3 is on the pure server you join) 

Team1-8
    Teamoverlay

VoteMessageArena
    Multiarena, ra3maps

VoteMessageWorld
    Normal votes 

WarmupInfo
    10sec countdown, Waiting for players, etc. Cannot be omitted. To hide
    place at off-screen x,y coordinates or set alpha 0. 

WeaponList
    The WeaponList has to get a little funky to be able to handle all the
    legacyhud tricks: W and H are the size of EACH weapon, not the total. 
    For the horizontal weaponlist (textalign C) X is the point to center
    around.
    Use FILL to show ammo for weapons you do not have, useful for TDM. 
    Weaponlist wraps at the bottom of the screen so you can sneak a
    multi-column one in.


Special Elements
----------------

PreDecorate and PostDecorate (up to 64 total)
    Empty elements that can be used to draw separator bars etc.
    PreDecorates will be drawn before/behind any other elements.
    PostDecorates will be drawn after/on top of any other elements.
    hud7 is a nice example of their use. 


Colors
------
CPMA HUD uses r g b a, which is red green blue alpha. Each channel can have
    values from 0-1.

Color 1 1 1 1 is white, full alpha
Color 0 0 0 0.5 is black, half transparent
Color 0.25 0.25 1 0.75 is blue, somewhat transparent

Note that colors set in SuperHud do not override colors set elsewhere. For
    example if your \nick or \name is ^3hello it will be yellow regardless.


Special Colors
--------------
Color T and color E for elements to use red/blue according to your current
    team. Might be useful for ctf, but not necessesary for tdm/1v1. Set
    bgcolor for these, even for images - see hud/old.cfg


Element Commands
----------------
The commands you can use within an element are:

BGCOLOR r g b a
    Sets the background color for the element 
    The element must have a width and height 

COLOR r g b a
    Sets the foreground color for the element 

DOUBLEBAR
    Makes bars two lines. Obviously only works on BAR elements
    (StatusBar_ArmorBar etc). Check out hud7 for examples. 
    Note: Gets a little funky if RECT Height is set below 6 as the space
    between the two bars is 4 pixels and each bar requires 1 pixel
    (4+1+1=6) 

FADE r g b a
    If the element has a TIME, its text will fade from COLOR to this
    linearly over TIME millisecons.

FILL
    If the element has a background color, this fills the area it
    occupies with that color.
    The element must have a width and height 

FONT name
    Selects one of three standard fonts: 
 CPMA - Bitstream Vera Bold, which is a high-resolution font best suited
    to 1024x768 and up - or large font-size on low-resolution 
 ID - which is the standard Q3 font - good for small font-size and/or
    low-resolution 
 IDBLOCK - only supports numbers, NOT letters 
 THREEWAVE - which is an outlined copy of the id font 

FONTSIZE pointsize | xsize ysize
    The CPMA font is correctly aspect-adjusted already, and generally looks
    best if you just specify a pointsize. 
    The other two fonts are square, and generally look much better if you
    specify distinct x and y sizes, with y being 25-50% larger than x. 
    Element texts can be mirrored using negative x y. Note this is an
    unintended and unsupported "hack", so might be a bit buggy. 

IMAGE pathname
    Display the image specified. You can use ANY image or shader found in
    pk3s. Mostly useful for displaying team/enemy model icons in CA/CTFS/FT.

MONOSPACE
    By default, all HUD fonts are proportionally spaced, meaning that an
    "i" takes up less room than an "m". Monospacing forces every character
    to take up the same amount of space. It's very useful for the team
    overlay, as it keeps everyone's health and armor in the same columns,
    but generally looks worse than proportional spacing on everything else,
    especially chat. It also takes up more room overall. 

RECT x y w h
    Sets the position and size of the element. Note that text is NOT
    "clipped" to this rectangle. 
    Elements can be mirrored using negative w h. Note this is an
    unintended and unsupported "hack", so might be a bit buggy. 

TEXTALIGN l | c | r
    Justify the text either Left, Centered, or Right within RECT 

TEXTSTYLE flags
    Currently, only one flag is supported: "1", for dropshadowed text 

TIME
    How long the element will be displayed for if it doesn't update again.
    Generally used for item pickups, frag messages, chat, etc. 


HUD Related Cvars
-----------------
These cvars do not directly influence the SuperHud but are still related
to the HUD in some way.

cg_customLoc <0|1> (default = 1)
    Use custom locations for a map if possible. 
    Loc files are locs/map.cfg, and must have a "v2" header 
    Can only replace existing locations 

cg_drawRewards <0|1> (default = 1)
    Toggle display of reward icons and the accompanying sounds

cg_teamChatsOnly <0|1> (default = 0)
    controls what text reaches the HUD Chat elements if set, non-team
    text still shows up in the console area 

ch_3waveFont <0|1> (default = 1)
    Toggle use of the Threewave font (does not affect SuperHud settings)

ch_drawWarmup (<0|1> (default = 0)
    Toggle display of arena settings before a game starts 

ch_drawWeaponSelect <0|1> (default = 0)
    Toggle id standard weapon selection 

ch_recordMessage <0|1> (default = 1)
    0 gets rid of the sodding "recording blahblah" message.
    Must be set before demo record start 

ch_selfOnTeamOverlay <0|1> (default = 1)
    Toggle your own information showing in the team overlay 

ch_shortNames <0|1> (default = 0)
    Toggle use of \nick - set a short name to use for team chat/overlay 
    Limited to 5 visible characters, but allows colors 
    Useful to have your \nick shown instead of [longclantag] in
    team chat/overlay 
    Note: \nick is only used for team chat/overlay. \name is still
    used for anything else. 

ch_wstatsTime <seconds> (default = 10)
    How long the auto-wstats window stays up at the end of a game 

con_notifyTime <seconds> (default = 3)
    -1 uses the CPMA "Console" hud element instead of id's. 
    Doesn't affect the console *buffer*, just the text in the top left.


Crosshair Cvars
---------------
cg_crosshairHealth <0|1> (default = 0)
    Red crosshair when low on health - must be 0 or ch_crosshairColor
    will not work

cg_crosshairsize <value> (default = 24)
    Size of crosshair 

cg_drawcrosshair <0-9> (default = 8)
    Switch between different crosshairs 

ch_crosshairAlpha <0.0 to 1.0> (default = 0.8)
    Controls the transparency of the crosshair 

ch_crosshairColor <color> (default = y)
    CPMA_Colors 
    Important note: cg_crosshairHealth overrides this function,
    turn it off to use colored crosshairs 

ch_crosshairPulse <0|1> (default = 0)
    Controls crosshair size changes when picking up items 

ch_crosshairText <string> (default = "" disabled)
    Use any text sting as crosshair 
