Athan's Q3F Beta2 HUD Editting HOWTO

Introduction

The intent of this document is to give anyone with reasonable scripting skills enough knowledge to be able to get the Q3F Beta2 HUD to do anything they desire within the limits of the code.

Note that this document is only a HOWTO, and as such lists what settings are available, and with which values, it is NOT a full tutorial.

Many thanks go to the q3f dev team for coming up with such a customisable hud, especially djbob for letting me pester him lots about how things work, correcting me when I made false statements in these docs and enlightening me on how a few things actually work.

Definitions

You'll see 'MENU_TRUE' and 'MENU_FALSE' used a lot, especially following 'visible'. The 'MENU_' part is a red herring in a way, as these are literally just values for 'TRUE' and 'FALSE'.

Guidelines

First a few guidelines.

1. Rather than comment out an item it's often a lot easier to just change its 'visible MENU_TRUE' to 'visible MENU_FALSE'. This makes it a lot quicker to toggle something on or off. Also if you remove anything but the 'text' on an item you'll find it won't show up on /edithud, so keep borders etc around, just MENU_FALSE'd so you can turn them on if you WANT to use /edithud to move them.
2. You do NOT need a 'name' line in itemDef's, only on menuDef's. Use a comment on itemDef's instead.
3. On the HUD all itemDef's should have the 'decoration' keyword to indicate they're not selectable. In many cases this means you will not then need a 'type' keyword.
4. To comment something out just put "//" (without the quotes) at the beginning of the line (actually just before the bit you need to comment).
5. If you need to combine flags on something, an anchorx for instance, you'll need to use $evalint, i.e. anchorx $evalint(ANCHOR_AUTOSIZE_WIDTH + ANCHOR_CENTER)
6. All co-ordinates are given on a 640 x 480 grid, then scaled as necessary for your actual in-use screen resolution. 0,0 is top left, 639,0 top right, 0,639 bottom left and 639,479 bottom right.

Current HUD Items

I'll list the 'name' part of the menuDef's what they actually cause to be displayed on-screen. The itemDef's within each of these sections should be obvious enough as to what they control:

• assetGlobalDef - This sets up defaults to be used by all other items.
• playerstatus - The player's health/armor indicator.
• yellow_score - The score/teamping/teamcount box for yellow. Similarly for the other three teams (Red, Blue, Green).
• ammostatus - Display of your current ammo carried for all types, includes the in-clip count for the current weapon.
• systemstats - the FPS/ping/lag-o-meter display
• grenadestatus - Count of each type of grenade.
• sentrycam - The Auto-Sentry camera (Engineer only)
• sentrystatus - Current ammo and health of your AS if built (Engineer only)
• supstationstatus - Current SS health level if built (Engineer only)
• scanner - The scanner if you're a recon.
• chatbar - The display across the top of the screen (by default) that messagemode(1) chat goes to, along with messages like players joining and leaving the server.
• teamchatbar - Where the messagemode2_q3f messages go, aka say_team.
• centerprintbar - Things like when a player has taken the flag go here.
• crosshairinfobar - The name of a player you're looking directly at goes here.
• weaponswitchbar - When you switch weapons this is where the icons per weapon appear.
• agentstatus - For the agent this shows your current disguise class/colour status. Also invis status if applicable.
• q3fchatedit - Where the "Say: " and "SayTeam: "prompts appear when you use messagemode_q3f and messagemode2_q3f.
• grentimerbar - Bar-style grenade timer, turn on with cg_showGrenadeTimer1 1.
• grentimercrosshair - Crosshait 'clock'-style grenade timer, turn on with cg_showGrenadeTimer2 1.
• alerticonblob - The sound-triggered visual aids for those hard of hearing, turn on with cg_visualAids 1.
• hud_icons - This is where the flag status indicators get drawn if enabled on a map.

Structure of an Item

Any item starts with a menuDef, you then have a pair of braces {} around the content. For readability I suggest you stick to the format in the supplied menu files.

Within a menuDef you will have a few options, including its name and then a number of itemDefs which define what actually appears in the item. For readability I suggest you always keep the name entry first.

Per-menuDef & itemDef Options

• name "text" - Label for this item.
• fullScreen MENU_FALSE/TRUE - Is this item to be drawn over entire screen?
• rect x y w h - Where and what size to draw this item. x and y define the top left corner, then w the width from there, and h the height.
• visible MENU_FALSE/TRUE - Whether this item is drawn or not
• font <fontpath/file> size - Define the font used for this item.
• smallfont <fontpath/file> size - Define the smallfont used for this item.
• bigfont <fontpath/file> size - Define the bigfont used for this item.
• itemDef {} - Declare an actual item within a menuDef object.
• decoration - Indicates an item is 'non-functional' in that it can't be clicked to any effect.
• forecolor r g b a - Foreground colour, red/green/blue and alpha (transparency).
• backcolor r g b a - Background colour.
• textscale <number> - Scaling of text (size).
• textalign <value> - How to align the text relative to the x,y of its itemDef's rect not WITHIN the box defined by its itemDef's 'rect'. This may be modified by textalignx/y (see below). See Appendix H for possible values.
• textalignx/y - Used to offset the origin x,y of text in the itemDef relative to the itemDef's rect
• anchorx/y <number> - Where this item is anchored within its parent. See Appendix Afor possible values.
• textstyle <style> - Style of the text, see Appendix B for possible values.
• text "<text>" - Force the text contents of this item to the given value. Useful for testing.
• background "<path to graphics/file>" - Graphic to be used for the background of this item.
• ownerDraw <drawing owner/code> - Special label to say which bit of the HUD code is responsible for drawing this item. Necessary on non-static items like ammo acounts and fps display. See Appendix C.
• ownerDrawFlag <flag> - Only draw this item if requisite condition is met. i.e. only draw Supply Station status if you have one built. See Appendix D.
• useAssetFont - Use the assetGlobal font.
• Q3F_ITEM_BORDER_FILLED - Actually a macro to make borders quicker to define. See menudef.h for how this and others are defined.
• loadborderbitmap <number> "<path to graphic/file>" - Defines the graphics used for the various portions of borders around items, including the 'filling in'. You can comment these out to cause that part of the border to not appear.
  • 0 - Top Left
  • 1 - Left Edge
  • 2 - Bottom Left
  • 3 - Top Edge
  • 4 - Centre Fill
  • 5 - Bottom Edge
  • 6 - Top Right
  • 7 - Right Edge
  • 8 - Bottom Right

• style <style> - Define the style of this item. Controls how graphics/text in the item are blended together. See Appendix E.
• type <item type> - Indicate what type this item is. i.e. border. See Appendix F.
• special <number> - A catchall 'special' value, used in various instances to indicate necessary parameters to the code. Yes it is that vague. Specific uses of it will be defined below. See Appendix G.
• nonSticky - This item is not sticky. Default is sticky.
• border <border style> - Put a border of style <border style > around this object, as per the rect line. See Appendix I for possible values.
• bordersize <x> - The border will be <x> pixels wide, at 640x480, scaled to current resolution.
• bordercolor r g b a - Set the colour of a border as defined above.

Using The Contents of a Variable

You can have the text of an item be set by the contants of a q3 client variable:

• cvar "cvarname"
• type ITEM_TYPE_TEXT
• textalign/scale etc as per any other text

Hiding/Showing An Item On The Fly

If there is some area of the HUD that you want to toggle on/off with your game config, rather than by editting the hud file or using multiple versions you can do this!

Simply make an alias that does 'hudscript hide <name of menuDef>' to turn that menuDef off temporarily, and another with 'hudscript show <name of menuDef>' to turn it back on again.

Using Custom Graphics

In theory this should be possible just by renaming an appropriate-format TGA file to <whatever>.cfg and then referencing it. As of build23 this wasn't working. As of RC1 I've been told this now won't be possible due to how the pure system works.

How To Actually Define Your Own HUD

A few simple steps will get you up and running. First go into your q3f (beta2) directory. Now extract the ui/ directory from <q3f_core_200.pk3> (q3f_core_200_rc2.pk3 in RC2). Rename this to custom_ui/. You actually only need the following:

	custom_ui/hud/hud.menu
	custom_ui/hud.cfg (renamed from hud.txt)
	

	custom_ui/ingame.txt
	custom_ui/menudef.h
	custom_ui/menus.txt
	

Edit the hud.cfg (renamed from hud.txt) file so that the line:

	loadMenu { "ui/hud/hud.menu" }
	

becomes

	loadMenu { "custom_ui/hud/hud.menu" }
	

You can leave the other lines pointing to "ui/..." so that they still use the default ones and you don't have to worry about extracting new versions if they're changed in new releases.

Now to edit the hud you just make changes to the custom_ui/hud/hud.menu file. To make the game use your changes you'll need to set/change the following variables in your q3config.cfg for q3f:

	seta cg_hudFiles "custom_ui/hud.cfg"
	seta cg_userHud "-1"
	

The latter is necessary so that the positions you define in hud.menu are actually used. Otherwise the file ui/userhud<x>.cfg is used, for <x> being the value of the cg_userHud variable. Note that id you use the /edithud command this variable WILL be changed again and you'll have to re-set it to -1 if you want the position values in hud.menu to take effect again.

If you make changes to your hud and want to test the changes without restarting q3(f) simply use the /loadhud command in the console.