Copyright (c) 2003 PhaethonH
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
The original author is known as PhaethonH (phaethon@linux.ucla.edu). Sections or paragraphs may be copyrighted by different authors. This document is released under the Free Documentation License (FDL) to protect the public's right to copying.
This document is provided in the hopes of being useful. There is no guarantee to the accuracy of the information contained within, although best-effort attempts are made at accuracy and completion. Use this information at your own risk. Although this information is unlikely to destroy a monitor, blow fuses, or cause the universe to cave in on itself, anything can go wrong (see Finagle's Law and Murphy's Law). Furthermore, I (PhaethonH) don't get paid writing this in the first place.
itemDef::special, noted that itemDef::decoration doesn't take a parameter, some test results of itemDef::style, itemDef::textScale.
Caught typos in the values for cgame ownerdraw.
Having worked on the UI of Q3UT for Q3 1.27, provided plenty of updates and verifications, with special thanks on menuDef::focuscolor, menuDef::disablecolor, menuDef::outOfBoundsClick, itemDef::asset_shader, itemDef::decoration, itemDef::wrapped, itemDef::type, itemDef::elementwidth, itemDef::elementheight, itemDef::elementtype, itemDef::outlineColor, ITEM_TYPE_MODEL, UI_*TEAM_LEADER/MEMBER*, and UI_OPPONENTMODEL
Indirectly alerted me to lack of info on actually loading a custom HUD.
Introduced me to uiScript, and provided much of the initial material: stopRefresh, LoadDemos, LoadMods, playMovie, verifyCDKey, StartServer,updateSPMenu, resetDefaults, getCDKey, loadArenas, loadGameInfo, resetScores, RefreshServers, RefreshFilter, RunSPDemo, LoadMovies, RunMod, Quake3, closeJoin, ServerStatus, FoundServerStatus, FindPlayer, JoinServer, FoundPlayerJoinServer, Quit, Controls, ServerSort, nextSkirmish, glCustom
Info on itemDef::model_rotation, UI_MAPCINEMATIC, UI_PREVIEWCINEMATIC; verified CG_1STPLACE and CG_2NDPLACE.
Many updates and additions: fonts info, colors, popup info, text alignments, many ui elements, ownerdraws, identification of disabled/unused commands.
With the release of Quake III: Team Arena (Quake3 point release 1.27), Id Software introduced a new method of creating menus. Instead of creating the menus in the C code of a QVM, menus can be described in menu description files, in a sort of menu-scripting language. These are plaintext files that are more flexible and customizable than C-based menus.
For further customizations, these files can be read off the user's filesystem, outside of pak (pk3) files. As a result, a customized menu can be used regardless of whether the server is in pure mode or not. (XXX: Describe pure mode.) The restriction, though, is that the filename must end with ``.menu'' or ``.cfg''. Only then may Q3A (and mods based on it) be able to read from the filesystem instead of only from a pak (pk3) file.
The Quake 3 game is broken into three ``modules'': cgame, game, ui.
``Client Game'', this modules render the graphics, plays sounds, handles player control, and does other stuff to make the game interactive. Some code is duplicated between cgame and game for purposes of prediction (compensate for net lag).
On the server side, this module lays out and tracks the actual gameplay. A dedicated server requires only this module. Inactive on client side, with the exception of single-player mode.
``User Interface'', this module presents the main menu (on startup), and the in-game ESC menu. This module is always active on client-side, but suspends (sleeps) during gameplay, until reactivated (woken up, e.g. pressing ESC key).
The HUD is now a special case of the menu code. The menu code, however, is in the domain of the ``ui'' module. As a result, much code criss-crosses between ``cgame'' and ``ui'' so that ``cgame'' may parse and handle menus (i.e. HUD elements).
This document attempts to document the new menu scripting system of Quake III: Team Arena. There is no other known publicly-available documentation on the new menu system. The original author is also not aware of any privately-available documentation. As such, this document is a continual work-in-progress, as new information is discovered and added. Many pieces of this document are left empty or partially described. They may be filled in at a later date (no guarantees).
The information collected on the menu system was collected while modifying the HUD for Weapons Factory Arena pre-3.0 betas. Therefore, there is a particular bias of concentration towards HUD development for that mod.
This document is more of a reference document, not a guide or a HOWTO, so expect much dry reading.
If you find any mistrakes or discover new tidbits of information, you can e-mail the relevant information to phaethon@linux.ucla.edu Depending on schoolwork load, time of day, mood, mailbox size, and phase of the moon, I may or may not respond and/or include submissions. As a last resort, the copyright allows anyone else to take over the document management in the event of excessive negligence.
The canonical URL for this document is http://www.linux.ucla.edu/~phaethon/q3tamenu/q3tamenu.html. This might change in the future, but seems unlikely. Updates (to the document, and to the location) will be provided at the indicated URL. The latest version of this document is determined by the document's date.
Initial release.
Additions to itemDef:addColorRange.
Touched up itemDef:textscale, *:border, menuDef:style, *:background. Added links for values for ownerdraw, style, textstyle, etc.
Contributions by Vaejor: itemDef:special, itemDef:decoration, itemDef:style, itemDef:textscale.
Additions to itemDef:cvar, itemDef::cvarFloat, itemDef::cvarStrList, itemDef::align, ITEM_TYPE_SLIDER.
Redid cgame and ui ownerdrawFlag descriptions in a more patterned manner. Fixed error where half the values for cgame ownerdraw didn't match up with menudef.h (eek!).
Some typos fixed. Apparently all the values for ownerdrawflag were wrong, so the numbers are removed for now.
Change of wordings. No new info added.
Additions and verifications by SweetnutZ of Silicon Ice Development (Quake III realism modification Urban Terror).
Added extensive, but by no means complete, cross-references. Preparing migration from LinxuDoc SGML DTD to DocBook SGML DTD by using m4 macro preprocessor.
Added information on how to actually load a custom HUD.
Added menuloader as another component of the menuing system. Added sections on the menuloader files.
Added uiScript section. Thanks to dementor.
Added model_rotation information. Thanks to thnom
Added info on UI_MAPCINEMATIC and UI_PREVIEWCINEMATIC. Thanks to thnom
Expansions on cinematics-related entries. Rewordings in Background section.
Numerous updates and edits from The Reaction Factory 2006.03.17 edition, particularly on UI elements. Started split of descriptions targeted for designers (things that do work) and for developers/programmers (things that should work/are broken).