A Hud script is pretty much identical to a menu script but with a more limited set of commands. Like the menu scripts, you must include the following line at the top of the file in order to use the defines that it contains :
#include "ui/menudef.h"
In a Hud script there can be two parts, an optional Global Asset Definition and the Menu Definition. The Global Asset Definition part is used to load those assets and set those values that will be used by every menu definition. It needs to be defined only once, in any Hud script file that is loaded by the program and is usually defined in the main script. The Menu Definition part is used to define the actual Hud.
#include "ui/menudef.h"
{
assetGlobalDef
{
}
menuDef
{
}
menuDef
{
}
......
}
As you can see from the above, unlike menu scripts, it is deemed okay to include more than one Menu Definition in a script file. This is because most Hud menu definitions are quite small and would require a lrage number of files if they were placed one per file.
The assetGlobalDef Section
Since Hud scripts are not part of the menu scripts, they require their own assetGlobalDef section. This can be placed in any Hud script file which is loaded by the program. Everything between the curly braces after assetGlobalDef will define assets and values which apply to all menus. It is in this section that we define such things as the font used for text. Certain things must be defined in this section or the menu system will not work correctly.
Fonts
If you plan to use any text in the Hud, which almost always happens, you must specify the font used to draw this text. This is a somewhat confusing procedure since you must define three different sizes of the font, each with its own data. Go to Using Q3Font to see how to generate the font data required. The data for each font size consists of a fontimage_xx.dat file and one or more fontimage_n_xx.tga files, where the xx is the point size of the font and n is 0, 1, .. . These files must be placed in the fonts directory.
When you use text in a menu you specify a scale for the text. This scale roughly translates to the following point sizes :
- a scale of 1.0 is about a 48 pt font
- a scale of 0.4 is about a 20 pt font
- a scale of 0.25 is about a 12 pt font
The menu system requires you to define three different size versions of the same font. These are called smallFont, font and bigFont. If the text scale is 0.25 or less then the data from the smallFont is used to generate the text in the correct size. If the text scale is 0.4 or greater the bigFont data is used to generate the text. Otherwise the font data is used. This ensures that the text looks correct since it is generated from font data that is close to the actual text size. If only one set of font data was used then the large and small scales would be distorted by the extreme stretching and shrinking required. Team Arena uses font sizes of 12, 16 and 20 for the three different sizes. If you were using mostly larger text sizes then you may want to use something like 20, 26 and 34. A little experimentation will show which font sizes result in the best looking text. The actual definition of the fonts looks like this :
smallFont "fonts/smallfont" 12
font "fonts/font" 16
bigFont "fonts/bigfont" 20
The name in between the quotes is not used (it is part of the unused builtin font generation code) but must be present. The number at the end is the font point size you used when generating the data in Q3Font. It corresponds to the xx in the name of the font data files.
If you already use the scripted menus then these files will be present and you do not need to create them. However, they still must be defined using the above commands.
Gradient Bar
When a menu item's window style is set to WINDOW_STYLE_GRADIENT the program uses a special graphic and the item's background color to draw a gradiant effect. This graphic is defined as ui\assets\gradiantbar2.tga by default and an attempt is made to load the graphic when the program initalizes. If you wish to use a different graphic for the gradiant you can specify it using the gradientBar command. The definition looks like this :
gradientBar <name>
where <name> is either the path and name of the graphic ( "ui/assets/gradientbar2.tga" ) or the name of the shader to use ( "gradiantbar" ).
If have used this command in your menu script to alter the gradientBar graphic then you must use it in the Hud script to also alter its graphic or problems may arise.
Scrollbars
The graphics used and size of scrollbars is set by default when the program initalizes but this can be changed if desired. By default the width (vertical) or height (horizontal) of the scrollbar is set to 16. If you wish to make the bar narrower or wider use the scrollbarSize command like this :
scrollbarSize 20 - to make it wider (20 pixels wide)
scrollbarSize 12 - to make it narrower (12 pixels wide)
The graphics used to make the scrollbar can also be changed and you can assign different graphics for the background used by horizontal and vertical bars, something not done by default.
The background used by the scrollbar is assigned by the scrollBarHorz (for horizontal scrollbars) and scrollBarVert (for vertical scrollbars) commands, which are used like this :
scrollBarHorz <name>
scrollBarVert <name>
where <name> is either the path and name of the graphic ( "ui/assets/scrollbar.tga" ) or the name of the shader to use ( "scrollbar" ). The rest of the graphics used by the scrollbar (left arrow, right arrow, up arrow, down arrow and bar thumb ) can be changed in a similar way by using these commands :
scrollBarArrowLeft <name>
scrollBarArrowRight <name>
scrollBarArrowUp <name>
scrollBarArrowDown <name>
scrollBarThumb <name>
where again <name> is either the path and name of the graphic or the name of the shader.
Scrollbars are used when displaying the scoreboard. If have used these commands in your menu script to alter the scrollbar graphics then you must use them in the Hud script to also alter its graphics or problems may arise.
If you used the graphics loaded by default when the program loaded you would still have to load the text fonts in the assetGlobalDef section, in order for the Hud to work correctly. The script file would look like this :
#include "ui/menudef.h"
{
assetGlobalDef
{
smallFont "fonts/smallfont" 12
font "fonts/font" 16
bigFont "fonts/bigfont" 20
}
}
MenuDef Information
Unlike the non-ingame menu system, which has a main menu, and the ingame menu system, which has the ingame menu, the Hud system does not have a specific menu definition that is run first. Instead all the menu definitions are run and displayed whenever the Hud is active. This works quite well, since we have almost no control over the Hud when we are ingame. None of the menu items can gain the focus so we don't have buttons, Editfields, etc.
In order to have any control over the Hud at all, especially the List boxes used for displaying the scoreboard, we have to bind keys to five cvars. This must be done in our menu script in the Controls section. The cvars used are :
- +scores - used to hide the Hud and show the scoreboard.
- scoresUp - scroll the scoreboard list box up.
- scoresDown - scroll the scoreboard list box down.
- nextTeamMember - advance to next selected team member. Last entry in list is the team info.
- prevTeamMember - advance to previous selected team member. Last entry in list is the team info.
Without these cvars bound to keys we will not be able to display the scoreboard, scroll through the list of scores it contains or select another team member.
The Hud requires two menu definitions with specific names, which are hard coded into the program. These are score_menu and teamscore_menu. These menus will only appear under special circumstances and they must be made invisible by default, using the visible MENU_FALSE command in the Overall Menu Information section. This is critical. If this command is not included in these menus they will be displayed along with the rest of the Hud and make a total mess of things.
The score_menu menu is opened when the user holds down the key bound to the +scores cvar in a nonteam game. The rest of the Hud menus are not displayed while this key is held down. When the menu is opened it is automatically made visible so it can be seen.
The teamscore_menu menu is opened when the user holds down the key bound to the +scores cvar in a team game. The rest of the Hud menus are not displayed while this key is held down. When the menu is opened it is automatically made visible so it can be seen.
Other than these named menus, the menuDefs can be named pretty much anything. Since there are no script commands like onOpen or onEsc, you can not reference menus by their name, so what you use really doesn't matter.
Like any other menu definition, you must define the window area of the menu using the rect command. Hud menu definitions can not be fullscreen (what would be the point?) so you must use the rect command to set the window area. It is used as :
rect x y width height
where x and y are the upper left corner locations and width and height is the area size.
While it is possible to use other commands in the Menu Definition section to set things such as the background and window style, it is better to use itemDefs
to provide the look of the menu. And the script commands we normally use in the Menu Definition section, OnOpen, onClose and onEsc, are not functional in the Hud scripts. Therefore, we won't be looking at the rest of the Menu Definition commands except for one.
Because all menuDefs are displayed when the Hud is drawn, and because we can not use script commands to alter the visibility of a menu by name, we must find another way to make a menuDef invisible when it is not needed. For this we turn to the ownerdrawflag command. If this command is placed in the Menu Definition section of a menuDef containing a visible MENU_TRUE command then it will control the visiblity of the menuDef.
The ownerdrawflag command is used to determine if the item or menu should be drawn, based on the status of a program supplied flag. If the flag provided by the program is true then the item or menu is drawn. If the flag is false then it isn't drawn. The flags for this command, as used in the Hud, are :
- ownerdrawflag CG_SHOW_BLUE_TEAM_HAS_REDFLAG - true if Blue team has the Red flag.
- ownerdrawflag CG_SHOW_RED_TEAM_HAS_BLUEFLAG - true if Red team has the Blue flag.
- ownerdrawflag CG_SHOW_IF_PLAYER_HAS_FLAG - true if player has the flag.
- ownerdrawflag CG_SHOW_OTHERTEAMHASFLAG - true if other team has your flag.
- ownerdrawflag CG_SHOW_YOURTEAMHASENEMYFLAG - true if your team has the other team's flag.
- ownerdrawflag CG_SHOW_ANYTEAMGAME - true if game is team based.
- ownerdrawflag CG_SHOW_ANYNONTEAMGAME - true if game type is not team based.
- ownerdrawflag CG_SHOW_HARVESTER - true if game type is Harvester.
- ownerdrawflag CG_SHOW_ONEFLAG - true if game type is 1 Flag CTF.
- ownerdrawflag CG_SHOW_CTF - true if game type is CTF.
- ownerdrawflag CG_SHOW_OBELISK - true if game type is Obelisk or Overload.
- ownerdrawflag CG_SHOW_TOURNAMENT - true if game type is Tournament.
- ownerdrawflag CG_SHOW_SINGLEPLAYER - true if game is single player and not on network.
- ownerdrawflag CG_SHOW_HEALTHOK - true if health greater than 25.
- ownerdrawflag CG_SHOW_HEALTHCRITICAL - true if health is less than 25.
- ownerdrawflag CG_SHOW_TEAMINFO - true if team info is selected.
- ownerdrawflag CG_SHOW_NOTEAMINFO - true if teammate is selected.
- ownerdrawflag CG_SHOW_2DONLY - this is not quite the same as the rest of the ownerdrawflag flags. If this is included in an item that draws a graphic or model then what is drawn is a 2D icon rather than a 3D model. This flag doesn't affect visibility but does affect certain ownerdraw commands.
This command can also be applied to items in the menu to control their visiblity as well. Multiple ownerdrawflag commands can be used in a menuDef or an itemDef and the flag results will be anded together to determine visibility.
#include "ui/menudef.h"
{
menuDef
{
name "playerarea"
visible MENU_TRUE
rect 570 220 50 100
ownerdrawflag CG_SHOW_ANYTEAMGAME
itemDef
{
}
}
}
This is a Menu Definition that will only be visible if we are playing a team based game.
An important decision we must make with regard to the Hud scripts is how many menuDefs we will be using. It is possible to place the entire Hud into one menuDef, plus the two hardcoded named menuDefs described above. Team Arena chose not to do this and created the Hud using many menuDefs, all placed into one file. Either method can be used without problems so the decision should be based on the layout of the Hud. If your Hud is scattered over the entire screen then using multiple menuDefs is probably the better method as it is easier to get the correct locations for each Hud part. If your Hud is compact and confined to a small area then using one menuDef is the best, allow you to do the layout using relative offsets for items rather than absolute screen locations. The choice is yours.
