Items are the building blocks of a menu. By combining a number of items together and placing them over the top of the menu background we create a functional menu.
Those sections of the definition that define the items are known as the itemDefs. Each itemDef must be inside the menuDef section of the script file for it to be included in the menu.:
#include "ui/menudef.h"
{
menuDef
{
itemDef
{
}
itemDef
{
}
}
}
There can be a maximum of 128 itemDefs in a menuDef. Everything inside the curly brackets of the itemDef is used to define that particular item.
NOTICE : items are draw to the screen in the order that they are defined in the menuDef, with the last item defined being on top. This is very important to remember when placing items in the menuDef, as it will affect the final result drawn to the screen.
Items can be thought of as windows that are placed on the menu background, with each window having its own features and area of operation. In order to allow the program to work with these item windows we need to supply some information about the window. This process is very similar to how we provided overall information about the menu itself. In fact, much of the same information is required about the item window as was required by the menu window.
Because of the nature of the Hud there are quite a few commands that can't be used in an item definition. Except for the special keys used to scroll the List Boxes, there is no control over the Hud items so any command that requires the item to gain the focus is unusable. In fact, the items we use to build the Hud consist of those displaying graphics or text and those that display information using the ownerdraw command. List boxes are used in the scoreboard but there are only three feeders and they all deal with scores.
Since the Hud is broken into two parts, the actual Hud and the scoreboard, we will look at the item commands we can use to build each part seperately.
The items used to build the actual Hud can be broken down into two groups, those that display graphics or text used as the background of the Hud and those that display graphics or text provided by an ownerdraw command. The first group is very similar to the Basic Items used in menu scripts but using a more limited array of commands. These commands are :
Item Name
One thing that is needed for an item is a name. We use the name command to set the item name like this
name <item name>
where <item name> is the name of the item. Unlike menu names, multiple items can share the same name.
Window Area
A item must also have a window area assigned to it so we know where to place it. We use the rect command for this :
rect x y width height
where x and y are the location of the upper left corner of the item window and width and height are its size. The x and y values are calculated relative to the upper left corner of the menu window. For example, if the menu window is defined by
rect 150 10 400 300
and the item window is defined by
rect 10 35 100 120
then the actual item location would be at x = 150+10 = 160 and y = 10+35 = 45.
This information gives us an item definition like :
itemDef
{
name singleBar
rect 349 54 256 30
}
This is an item named "singleBar" which covers an area 256x30 located at (349,54) from the upper left corner of the menu window.
Window Style
Next needed is the style of the window. An item window can have one of six different styles, which is set by the style command. The window styles you can use are :
- style WINDOW_STYLE_EMPTY - this is the default window style and nothing special is done with it.
- style WINDOW_STYLE_FILLED - fill the window with the background color. Also use the fade values to fade the menu in and out.
- style WINDOW_STYLE_GRADIENT - use the gradiant bar graphic, colored with the background color to fill the window. The graphic is stretched to fit the window size.
- style WINDOW_STYLE_SHADER - fill the window with the background graphic, tinting it with the foreground color if one has been defined.
- style WINDOW_STYLE_TEAMCOLOR - fill the window with the color of the team you are on. A Team Arena specific window style.
- style WINDOW_STYLE_CINEMATIC - fill the window with the movie defined by the cinematic command.
Visiblity
All items in a Hud menuDef must be visible when the menu is opened. This is done by including the following :
visible MENU_TRUE
The item's visiblity can be altered by ownerdrawflag commands but by default the item must be visible.
Background
An item can have a background graphic assigned to it that will be drawn in the window area if the window style is WINDOW_STYLE_SHADER. The background is assigned by the background command, used like so :
background <name>
where <name> is either the path and name of the graphic ( "textures/menu/julie_1.tga" ) or the name of the shader to use ( "menu/art/smoke" ).
Item Colors
Along with the background graphic, we can assign two colors to an item. These are the background color and the foreground color, which are set using the backcolor and forecolor commands respectively. These commands are used like :
backcolor red green blue alpha
forecolor red green blue alpha
where the range of the colors and alpha is 0 to 1. See here for more information on color values in Quake 3.
Borders
If desired it is possible to have borders drawn around the item window. There are five different border types you can choose from, set by the border command as follows :
- border WINDOW_BORDER_NONE - the default border type which draws nothing.
- border WINDOW_BORDER_FULL - draws a border on all four sides of the window.
- border WINDOW_BORDER_HORZ - draws a border on the top and bottom only.
- border WINDOW_BORDER_VERT - draws a border on the sides only.
- border WINDOW_BORDER_KCGRADIENT - draws a gradiant border on the top and bottom of the window using the gradiant bar graphic tinted by the border color.
The thickness of the border is set by the bordersize command and is used like :
bordersize <value>
where <value> is the thickness in pixels.
The color of the border is set by the bordercolor command as follows :
bordercolor red green blue alpha
where the range of the colors and alpha is 0 to 1. See here for more information on color values in Quake 3. If the window style is set to WINDOW_STYLE_TEAMCOLOR then the border color is ignored and the team color is used instead.
Item Text
A string of text can be assigned to an item and information about how it is to be displayed can be set using the text commands. The actual string of text is set using the text command like so :
text <string>
where <string> is a string of text enclosed in quotes (ie. "SINGLE PLAYER"). The text color is set by the item's foreground color ( as set by the forecolor command).
There are a number of commands that are used to tell the program how to display the text string inside the item window.
Alignment
A string of text can be aligned both horizontally and vertically. In the horizontal direction we have two commands to set the alignment. The first command is used to set the point in the text string that we use for the alignment. This is done with the textalign command and we have three points to choose from.
textalign ITEM_ALIGN_LEFT - set the point to the left side of the text
textalign ITEM_ALIGN_CENTER - set the point to the center of the text
textalign ITEM_ALIGN_RIGHT - set the point to the right side of the text
We then use the textalignx command to do the actual alignment. It is used like :
textalignx <distance>
where <distance> is the number of pixels from the left side of the item window to the alignment point in the text. For example :
textalign ITEM_ALIGN_CENTER
textalignx 80
will draw the text so that the center of the text string is 80 pixels from the left side of the item window. Additionally,
textalign ITEM_ALIGN_RIGHT
textalignx 120
will draw the text so that the right side of the text string is 120 pixels from the left side of the item window.
When aligning the text vertically we use the textaligny command as so :
textaligny <distance>
where <distance> is the number of pixels from the top of the item window to the bottom of the text.
Size
The size of the text is set using the textscale command like this :
textscale <scale>
where <scale> is the scale of the text. To figure out the actual point size of the text use this formula :
point size = 48.0 x <scale>
Style
The command textstyle applies certain special effects to the text when it is drawn. There are four different styles you can choose from :
- textstyle ITEM_TEXTSTYLE_NORMAL - normal solid text. This is the default text style.
- textstyle ITEM_TEXTSTYLE_BLINK - fast blinking text, about 2x per second.
- textstyle ITEM_TEXTSTYLE_SHADOWED - drop shadow effect.
- textstyle ITEM_TEXTSTYLE_SHADOWEDMORE - extra shadow effect.
Item Type
In the Hud the item type is confined to just one, type ITEM_TYPE_TEXT, which is the default type and therefore does not need to be explictly defined. In the scoreboard menus the type can also be type ITEM_TYPE_LISTBOX. We will look at that later.
Cvars
It is possible to assign a cvar to an item. The assignment is done by use of the cvar command used like :
cvar <cvar name>
where <cvar name> is the name of a cvar defined in the program. Only cvars defined in the program can be used, no creating new ones is allowed.
Show/Hide
You can also use a cvar to show or hide the item. The cvar used for this does not have to be assigned to the item and any cvar can be used. This first step in doing any of these is to test the value of the cvar. This is done with the cvartest command like :
cvartest <cvar name>
where <cvar name> is the name of a cvar defined in the program. The value of the cvar is remembered and used by other commands to do the actual show/hide. These commands are :
- showCvar { <string> ; ...... ; <string> ; }
- if any of the <string> values match the tested cvar value then make the item visible.
- hideCvar { <string> ; ...... ; <string> ; }
- if any of the <string> values match the tested cvar value then make the item not visible.
ownerdrawFlag
The ownerdrawflag command is used to make the item invisible under certain conditions. These conditions generally depend on the status of the player or the game type being played. Using this command you can make the Hud different for different game types or have it display information that changes during the game, such as when you have the flag in CTF. This command is described in full here. Multiple ownerdrawflag commands can be used in an itemDef and the flag results will be anded together to determine visibility.
The items that display information using the ownerdraw command can use the same array of commands as those described above but, obviously, also include an ownerdraw command. There are also a few special commands that are used with a specific ownerdraw command, CG_AREA_POWERUP, that we will examine later. The Hud ownerdraw commands are different from those used in menus and provide either text or graphics specific to a Hud. These commands are :
- ownerdraw CG_PLAYER_ARMOR_ICON - display the armor graphic or model.
- ownerdraw CG_PLAYER_ARMOR_VALUE - display the armor value as text.
- ownerdraw CG_PLAYER_HEAD - draw the player head graphic or model.
- ownerdraw CG_PLAYER_HEALTH - display the player's health value as text.
- ownerdraw CG_PLAYER_AMMO_ICON - display the ammo graphic or model for the current weapon.
- ownerdraw CG_PLAYER_AMMO_VALUE - display the ammo value as text.
- ownerdraw CG_PLAYER_SELECTEDPLAYER_HEAD - draw the selected player's head graphic or model.
- ownerdraw CG_PLAYER_SELECTEDPLAYER_NAME - display the selected player's name as text.
- ownerdraw CG_PLAYER_SELECTEDPLAYER_LOCATION - display the selected player's location as text.
- ownerdraw CG_PLAYER_SELECTEDPLAYER_STATUS - draw the selected player's status as a graphic. These are the graphics in the ui/assets/statusbar directory.
- ownerdraw CG_PLAYER_SELECTEDPLAYER_WEAPON - display the selected player's weapon as a graphic.
- ownerdraw CG_PLAYER_SELECTEDPLAYER_POWERUP - draw the selected player's powerup as a graphic.
- ownerdraw CG_PLAYER_SELECTEDPLAYER_ARMOR - display the selected player's armor value as text.
- ownerdraw CG_PLAYER_SELECTEDPLAYER_HEALTH - display the selected player's health value as text.
- ownerdraw CG_PLAYER_ITEM - draw the item that the player holds as a graphic.
- ownerdraw CG_PLAYER_SCORE - display the player's score as text.
- ownerdraw CG_BLUE_FLAGHEAD - draw the head graphic or model of the Red team player holding the Blue flag.
- ownerdraw CG_BLUE_FLAGSTATUS - draw the status graphic of the Red team player holding the Blue flag. These are the graphics in the ui/assets/statusbar directory.
- ownerdraw CG_BLUE_FLAGNAME - draw the name of the Red team player holding the Blue flag as text.
- ownerdraw CG_RED_FLAGHEAD - draw the head graphic or model of the Blue team player holding the Red flag.
- ownerdraw CG_RED_FLAGSTATUS - draw the status graphic of the Blue team player holding the Red flag. These are the graphics in the ui/assets/statusbar directory.
- ownerdraw CG_RED_FLAGNAME - draw the name of the Blue team player holding the Red flag as text.
- ownerdraw CG_BLUE_SCORE - display the Blue teams score as text.
- ownerdraw CG_RED_SCORE - display the Red teams score as text.
- ownerdraw CG_BLUE_NAME - display the Blue teams name as text.
- ownerdraw CG_RED_NAME - display the Red teams name as text.
- ownerdraw CG_ONEFLAG_STATUS - display the status of the flag as a graphic.
- ownerdraw CG_PLAYER_LOCATION - display the player's location as text.
- ownerdraw CG_TEAM_COLOR - fill the item window area with the player's team color.
- ownerdraw CG_AREA_POWERUP - display the powerups (and time remaining) that the player has in CTF as a graphic and text. This command uses some special commands for placement of the graphic. See below for details.
- ownerdraw CG_PLAYER_HASFLAG - draw the flag graphic or model if the player has the flag.
- ownerdraw CG_GAME_TYPE - display the game type as text.
- ownerdraw CG_PLAYER_STATUS - draw the status graphic of the player. These are the graphics in the ui/assets/statusbar directory.
- ownerdraw CG_GAME_STATUS - display the game status as text. In single player this is the ranking and in team mode it is the team rankings.
- ownerdraw CG_KILLER - display the name of the last player to kill you as text.
- ownerdraw CG_PLAYER_ARMOR_ICON2D - display the armor graphic.
- ownerdraw CG_PLAYER_AMMO_ICON2D - display the ammo graphic for the current weapon.
- ownerdraw CG_ACCURACY - display the accuracy score as text.
- ownerdraw CG_ASSISTS - display the assists score as text.
- ownerdraw CG_DEFEND - display the defense score as text.
- ownerdraw CG_EXELLENT - display the exellence score as text.
- ownerdraw CG_IMPRESSIVE - display the impressives score as text.
- ownerdraw CG_PERFECT - display the perfect score as text.
- ownerdraw CG_GAUNTLET - display the
humiliations
score as text.
- ownerdraw CG_CAPTURES - display the player captures as text.
- ownerdraw CG_SPECTATORS - display the names of the spectators as horizontally scrolling (
marquee-effect
) text.
- ownerdraw CG_TEAMINFO - display the team info as text and graphics.
- ownerdraw CG_PLAYER_HASFLAG2D - draw the flag graphic if the player has the flag.
- ownerdraw CG_CAPFRAGLIMIT - display either the frag limit or the capture limit as text, depending on game type.
- ownerdraw CG_1STPLACE - display for nonteam games the highest score. For team games the score of the Red team.
- ownerdraw CG_2NDPLACE - display for nonteam games the second highest score. For team games the score of the Blue team.
In these commands there are some that display either a graphic or a model. Which is displayed is determined by the value of the cg_draw3dIcons cvar. If this cvar is 0 then graphics are displayed. If it is 1 then models are used. By default this cvar is set to 1 and if you wish to change it's value it must be done from the menu script before the Hud is displayed. The other way to force these commands to display a graphic is to include the ownerdrawflag CG_SHOW_2DONLY command in the item definition.
When you are using the ownerdraw CG_AREA_POWERUP command in an item there are two commands that are used to do alignment of the graphic and text. Since this command draws more than one graphic/text combo you must tell the program if you want them aligned vertically or horizontally. The align command is used for this. Including an align HUD_VERTICAL command will align the graphic/text combos vertically, while an align HUD_HORIZONTAL command will align them horizontally. The special command is used to define how many pixels of space you want between the graphic/text combos. It is used like :
special <value>
where <value> is the number of pixels of space.
The only type of advanced item that is avalible for use in the Hud is List boxes. These are used in the scoreboard to list the team information for team based games and the scores of players in nonteam games. The item is made into a list box by setting the type to ITEM_TYPE_LISTBOX. A list box item can have a colored or graphic background and have borders if desired, just like any basic item.
Feeders
A list box can only show list information from a limited number of lists maintained by the program. You specify what list you are using by use of the feeder command. It is used as follows :
feeder <value>
where <value> determines which list you are specifying. The program itself maintains and updates the list so you don't have to it manually. The lists you can select by <value> are :
- FEEDER_REDTEAM_LIST
- FEEDER_BLUETEAM_LIST
- FEEDER_SCOREBOARD
- a list of the player scores in nonteam games. This feeder returns 7 columns of information for the item to display.
All of the above feeders return the same information about the players. It is as follows :
| Column # |
Information Returned |
1 |
The flag graphic if the player has the flag or the skill level of the bot or the players handicap. |
2 |
Team status graphic |
3 |
Player status as text |
4 |
Player name as text |
5 |
Player score as text |
6 |
Time of last score |
7 |
Ping |
Elements
Once you have decided on the feeder to use with the list box you must set the type of object (or element) shown in the list. A list can have either text elements or graphic elements and you set the type using the elementtype command. For Hud elements you use :
elementtype LISTBOX_TEXT
In many cases, the feeder will determine the element type, since most feeders return text information. There are feeders, however, that will return either a graphic or text to match the defined element type.
Next you have to define the width and height of each element in the list. If you have graphic elements then the image will be stretched/shrunk to fit the area you define. Text elements only use the element height to space each line in the list. The width and height of each element is set by :
elementwidth <width>
elementheight <height>
For text elements you must make sure that the height is great enough that the lines of text don't overlap. If you have text elements you must set the text size and style using the textscale and textstyle commands.
Selectablity
In the Hud you must make it so you can't select any elements in a list box, while still retaining the ability to scroll through the list. To do this include :
notselectable
in the item definition.
Columns
The Hud feeders return more than one piece of information in each line. To display this properly you must provide column information so that each piece of information is placed correctly on the line. This is done with the columns command use as so :
columns <number> <offset> <width> <max chars> ..... <offset> <width> <max chars>
where <number> is the number of columns being defined. Each column is defined using three values :
- <offset> - the number of pixels from the left side of the list box to the left side of the column.
- <width> - the width and height in pixels of the graphic that may be returned.
- <max chars> - the maximum number of characters to display in the column.
If <max chars> is set to 0 then the text in that column will not be displayed.
