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. Disclaimer

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. Acknowledgements and Credits

Vaejor (Vaejor the-litte-at-sign-thingy mail com) itemDef::special, noted that itemDef::decoration doesn't take a parameter, some test results of itemDef::style, itemDef::textScale. BeLaC Caught typos in the values for cgame ownerdraw. SweetnutZ (mercjohns@hotmail.com), designer for (Q3UT) 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 Mad Ad (m::::::@n::.n::.c::) Indirectly alerted me to lack of info on actually loading a custom HUD. dementor (dementor(at)comcast.net), coder for Terror Quake 3 (TQ3) 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 thnom (irc://irc.enterthegame.com/thnom) Info on itemDef::model_rotation, UI_MAPCINEMATIC, UI_PREVIEWCINEMATIC; verified CG_1STPLACE and CG_2NDPLACE. dairyman (rfactory.org) Many updates and additions: fonts info, colors, popup info, text alignments, many ui elements, ownerdraws, identification of disabled/unused commands. Background

With the release of &q3ta; (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. cgame ``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). game 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. ui ``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). Purpose

This document attempts to document the new menu scripting system of &q3ta;. 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 &wfa; 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. Feedback

If you find any mistrakes or discover new tidbits of information, you can e-mail the relevant information to 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. Latest Version

The canonical URL for this document is . 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. ChangeLog

2001.03.30 Initial release. 2001.04.21 Additions to itemDef:addColorRange. 2001.04.22 Touched up itemDef:textscale, *:border, menuDef:style, *:background. Added links for values for ownerdraw, style, textstyle, etc. 2001.04.23 Contributions by Vaejor: itemDef:special, itemDef:decoration, itemDef:style, itemDef:textscale. 2001.04.23 Additions to itemDef:cvar, itemDef::cvarFloat, itemDef::cvarStrList, itemDef::align, ITEM_TYPE_SLIDER. 2001.04.23 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!). 2001.04.25 Some typos fixed. Apparently all the values for ownerdrawflag were wrong, so the numbers are removed for now. 2001.05.19 Change of wordings. No new info added. 2001.06.09 Additions and verifications by SweetnutZ of Silicon Ice Development (Quake III realism modification Urban Terror). 2001.06.14 Added extensive, but by no means complete, cross-references. Preparing migration from LinxuDoc SGML DTD to DocBook SGML DTD by using m4 macro preprocessor. 2002.02.21 Added information on how to actually load a custom HUD. 2002.02.22 Added menuloader as another component of the menuing system. Added sections on the menuloader files. 2002.03.03 Added uiScript section. Thanks to . 2003.01.18 Added model_rotation information. Thanks to 2003.01.22 Added info on UI_MAPCINEMATIC and UI_PREVIEWCINEMATIC. Thanks to 2003.01.26 Expansions on cinematics-related entries. Rewordings in Background section. 2006.11.25 Numerous updates and edits from 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). The Q3TA Menu Documentation syntax

Items in plain font is a keyword.

Items within square brackets ([]) are required.

Items within angle brackets (<>) are optional.

A ``string'' type can be optionally enclosed in double-quotes ("). This use of double-quotes is required if the string contains a space. Highly recommended to always use double-quotes for strings, if for no other reason than style consistency.

A ``int'' type is an integer number, negative or not, with no fractional (decimal) portion.

A ``float'' type is a floating point number, negative or not, with or without a fractional (decimal) portion.

A ``color'' type is four sequential floats, indicating a RGBA value. Each float corresponds to: Red component Green component Blue component Alpha component

Each component is given a value from zero (none) to one (full). Zero alpha is full transparency (invisible), with one being full opacity. Partial values are fractional numbers between 0 and 1 (e.g. "0.58").

A ``rect'' type is four sequential ints. The four numbers correspond to: Horizontal (X) position of the rectangle's upper-left corner Vertical (Y) position of the rectangle's upper-left corner Width of the rectangle Height of the rectangle

The coordinates are scaled to a 640x480 screen: horizontal values range from 0 to 640, vertical values range from 0 to 480. So even if the screen resolution is 1600x1200, "(320, 240)" (half of 640, half of 480) still means the center of the screen. "0 0 640 480" is full-screen.

The special marker XXX indicates meta-notes/hints about incompleteness in some form. Menu Layout

The description of menus can lay across many files. In fact, the &q3ta; main menu is described across more than 30 files. There are three main components to the menu system: menuloader menu definition (menuDef) item definition (itemDef)

Items are the individual parts of a menu that actually carry out actions. Menus are logical (and physical) groupings of items. Submenus are possible, but not directly (i.e. no defining a menu inside a menu); instead, an item may open another menu, then re-open the previous menu upon closing, creating a submenu effect. Menuloader lists menus to prepare for display, and, in a sense, groups menus. Menu Format

The format is loosely based on the programming language C. `menuDef' and `itemDef' describe groupings that can be compared to C function or structs. These two define their bodies within curly braces ({}). Both `menuDef' and `itemDef' are composed of ``statements'' that end with a semicolon. An `itemDef' can only be nested inside a `menuDef'. This means no nesting an `itemDef' inside another `itemDef'. `menuDef' cannot be nested inside anything else. Menuloader

"Menuloader" is a fabricated word to describe the file. Relevant variables in the game source use the name "menuFile", but I feel that name would be confusing with "menuDef". So far, only one keyword is recognized: ``loadmenu''.

A menuloader groups menus into functionally related groups. Q3TA has three such main groups: ui/hud.txt - cgame module ui/ingame.txt - ui module ui/menus.txt - ui module

Frequently, the menuloader file has the extension ".txt". In the case of user-customized menus, the user would need to use the extension ".cfg" instead (".menu" is also valid, but not recommended for sake of clarity). The content is often: { loadmenu { "somefile.menu" } loadmenu { "someotherfile.menu" } loadmenu { "morefile.menu" } ... } Where each string indicates a .menu file to load and prepare. menuDef { ... }

A menuDef is a grouping of itemDefs. The following describe keywords that are recognized in a menuDef body, but outside of any itemDef bodies. font &string;

The given string is interpreted as a font name. The default is ``default''. This command should not be used as it only defines one of the three required font sizes that Team Aren uses. name &string;

Sets a name for the menu. This keyword is primarily useful when opening the menu as a submenu, where an item in another menu can open this menu by name.

See also: , , , . rect ▭

Define a rectangle on the screen for the menu to occupy. Menu rectangles may overlap; the last rect defined sits on top. Nested items are offset from this rect's left and top edges (meaning this rect acts as a new "mini-screen" for coordinates for the items inside).

See also: , , . fullscreen ∫

A method of setting up a rectangle on the screen for the menu to occupy that covers the entire screen and to tell the program that nothing else is being rendered underneath this menu. This command must be used in place of the 'rect' command for the bottom menu.

See also: , . style ∫

Defines a window style for the menu.

See also: , , . visible ∫

Sets visibility of this menu, whether it gets drawn or not. The visibility of a menu can be changed by an item, in conjunction with the menu name.

See also: , , . onOpen { &script; }

Runs the provided script when the menu opens. When &q3ta; start up, the main menu runs this script (because it just opened). This action also occurs when the menu is opened as a submenu.

See also: , , , . onClose { &script; }

Runs the provided script when the menu closes. This action can be used for a limited amount of cleanup work and to mimick submenuing effects.

See also: , , , . onESC { &script; }

Runs the provided script when the Escape key (ESC) is pressed. This action usually closes the menu (by opening another).

See also: , , . border ∫

Sets a border type.

See also: , , , . borderSize &float;

Sets the border thickness. The border is drawn inside of the menu rect. The origin coordinates for nested items is shifted, meaning that "0, 0" for itemDefs changes accordingly to avoid the border.

See also: , , . backcolor &color;

Sets the menu background color. Only meaningful if the rect `style' is set to WINDOW_STYLE_FILLED.

See also: , , , , , . forecolor &color;

Sets menu foreground color. Used as tint color for background shaders.

See also: , , , , , , . bordercolor &color;

Sets the border color.

See also: , , . focuscolor &color;

Sets the text color of items when they are focused -- that is, when the item is enabled and has the mouse cursor over it. See also .

See also: , , , . disablecolor &color;

Sets the text color of items when they are disabled. See also , , . background &string;

The provided string is interpreted as a Q3A shader or an image (JPG or TGA) to display in the rect background. Images are stretched to fit the rect, ignoring aspect ratios. Shaders can have their own instructions on how to fill the rect.

See also: , . ownerdraw ∫

Causes the Q3A engine to draw something within the confines of the menu rect. Primary use is in HUDs (such as showing health).

See also: , , , , . ownerdrawflag ∫

The menu asks the Q3A engine for a certain value; this value determines whether the menu (along with its items) gets drawn or not. If the menu was already invisible, nothing is drawn regardless of this flag value.

See also: . . , . outOfBoundsClick

According to , with this tag/flag in the menuDef, clicking outside the menu rectangle area causes the menu to close.

See also: , . soundLoop &string;

The given string is interpreted as a sound name (filename for the most part) to play in a loop. The loop is stopped by providing an empty string (soundLoop "").

See also: , . cinematic &string;

Plays a cinematic (RoQ file) within the menu rect. The RoQ path name is provided in the string; the path name is as stored in the pk3 file. RoQs can be created from AVIs by tools provided by Id Software. AVIs can be created from multiple TGAs (or most any other image files) by various free/freeware/shareware/not-so-free tools.

See also: , . popup

Causes the menu to be drawn overtop of the calling menu. Only items in this menu can gain the focus, even though items in the underlying menu can be seen. fadeClamp &float;

Along with and , implements a fade-in effect. Best advice so far: fiddle with it.

See also: , , , . fadeAmount &float;

Along with and , implements a fade-in effect. Best advice so far: fiddle with it.

See also: , , , . fadeCycle &float;

Along with and , implements a fade-in effect. Best advice so far: fiddle with it.

See also: , , , . itemDef { ... }

An itemDef describes on item member of a menu. The following keywords are recognized inside an itemDef: name &string;

Sets a name for the item. Manipulation of an item is done through its name. Names can correspond with a menu name, but since actions are carried out based on matching names, this could be used to create both awesome effects and terrible side-effects.

See also: , . text &string;

Use the provided string as a text to display

Programmer's (mod) note: This item largely corresponds to "label" items of other GUIs).

See also: , , , , . group &string;

Sets a group name for the item. This grouping also allows the manipulation of many items simultaneously (such as hiding the radio buttons together).

Programmer's (mod) note: Primary use is in implementing radio buttons (where selecting one button in the group deselects all others in the same group).

See also: , . asset_model &string;

Displays a Q3A model. The provided string indicates the path name of a model to display. View the pk3s to see the expected path names.

See also: , , , , . asset_shader &string;

Apparently not used (ineffectual). model_origin &float; &float; &float;

Apparently not used (ineffectual).

See also: , , , , . model_fovx &float;

Field-Of-Vision along the screen's X (horizontal) axis. Affects horizontal (left-right) "stretchiness". Units are degress, 90 is "normal", lesser values cause "stretching out", greater values cause "shrinking". Most monitors have an aspect ratio of 4:3, so this value should be 3/4 of model_fovy (3 * fovx == 4 * fovy).

See also: , , , , . model_fovy &float;

Field-Of-Vision along the screen's Y (vertical) axis. Affects vertical (up-down) "stretchiness". Units are degress, 90 is "normal", lesser values cause "stretching out", greater values cause "shrinking".. Most monitors have an aspect ratio of 4:3, so this value should be 4/3 of model_fovx (3 * fovx = 4 * fovy).

See also: , , , , . model_rotation ∫

Model rotation rate. Units is number of milliseconds to wait before rotating model by 1 degree (i.e. milliseconds per degree). Value of zero disables rotation. (thanks )

See also: , , , , . model_angle ∫

View model from a fixed angle (angle around Z-axis, i.e. on X-Y plane). If model_rotation is non-zero, this value acts as the base (starting) angle for rotation. XXX: what does 0 mean? head-on?

See also: , , , , . rect ▭

Defines a rectangular area within a menu. The item's rect is positioned relative to the menu's rect; i.e. the menu's rect acts as a "mini-screen" for the coordinates of item rect. This shifting eases the relocating of menus; menus can be moved without having to recalculate the positions of its items. The size of a "unit" is the same as that used by the menu; i.e. no squishing-into-the-rect. x = 640 still means move 640 "pixels" over to the right, even if off-screen.

See also: , . style ∫

Fill style of the rect. Values are listed in . 's earlier tests had Q3 crashing when the value was 5 (WINDOW_STYLE_CINEMATIC); the reason was that no RoQ file was provided in a `cinematic' field.

See also: , , , . decoration

Presence of this keyword declares whether this item is a decoration item or not. Non-decoration items would be hotspots, buttons, sliders, etc., items that cause actions to happen. Decoration items would be menu border graphics, logos, animation boxes, etc.

points out that anything without this keyword will make mouseover sound and other assorted things. notselectable ∫

Makes a List Box element unselectable. Used to make List Boxes display only. wrapped

Enforces manual text wrapping of the text provided in the `text' field. The two-character sequence ``\r'' (backslash, r) causes a manual and forced wrap (newline) in texts.

provides an example: autowrapped text "here is line one of the text\r" "here is line two of text\r" "here is line three, etc etc etc"

See also: . autowrapped

Enforces auto-wrapping of the text provided by the `text' field. This keyword causes the text to automatically wrap to fit within the rect.

See also: . horizontalscroll

Makes a List Box scroll horiziontally rather than vertically. Only applicable if the List Box is displaying graphical elements. type ∫

Sets the item type. If not specified, the default is . See also: . elementwidth &float;

Related to the width of elements inside an image listbox. points out that Q3 head icons are 32 pixels wide, so ``elementwidth 32;'' would be used for an image listbox of Q3 head icons.

See also: , . elementheight &float;

As with , but with element height.

See also: . feeder &float;

The game builds many types of lists internally (so that it may be re-updated, sorted, modified, etc.). Feeders provide a hook to this internal list for the menu system. Items that use feeders have a list that reflect this internal list. The specific internal list to use is indicated by the given parameter.

Items that use a feeder are specially flagged to follow their selection. That is to say, when you select an object in the list, the internal list "learns" which item you have just selected. This maintains the parallel of states between the internal list and the list presented by the menu system.

verifies the linking into the game code for listbox data, but I'm still stumped on the use of a float, instead of int.

See also: , , . elementtype ∫

Specifies the type of element in a listbox, either text ("LISTBOX_TEXT", 0) or image ("LISTBOX_IMAGE", 1).

See also: , , . columns ∫ ∫ ...

First integer is the number of columns. Following that are sets of three integers, one set for each column just mentioned. Each set of three integers consists of the following: offset from the left of the item rect in pixels. width of graphic if not text context (use 0 otherwise). Used only in HUD. maximum number of characters to display at a time.

See also: , , . border ∫

Sets a border style for the item.

See also: , , . borderSize &float;

Sets the thickness of the border. The border is drawn on the inside of the item rect.

See also: , , . visible ∫

Sets the visibility of the item. "0" prevents it from being drawn, "1" (or any other value) causes it to be drawn.

See also: , , , , , . ownderdraw ∫

Like the menu's ownerdraw, this statement makes a request to the Q3A engine to draw something within the item rect.

See also: , , . align ∫

The only uses found for this have been in the default HUDs, in conjunction with the CG_AREA_POWERUP ownerdraw. The two known values are 0 (HUD_VERTICAL) and 1 (HUD_HORIZONTAL). These affect the way multiple powerups are drawn, whether vertically (aligned to the bottom, sorted in sequence of remaining times) or horizontally (from left to right?).

See also: . textalign ∫

Determines where the horizontal alignment point is applied to text. Values are: 0 ITEM_ALIGN_LEFT Left side of text. 1 ITEM_ALIGN_CENTER Center of text. 2 ITEM_ALIGN_RIGHT Right side of text.

See also: , , , , . textalignx &float;

Horizontal text alignment in pixels (of 640 max) from left edge of rect to alignment point of text.

See also: , , , , . textaligny &float;

Vertical text alignment in pixels (of 480 max) from top edge of rect to bottom of text.

See also: , , , , . textscale &float;

Scale the text size. A scale of 1.0 is 48 pixels tall (1.0 = 48, 0.5 = 24, 0.25 = 12, 0.2 = 10; textscale = height / 48).

This statement has special effects on certain ownerdraws. The known ones with such special effects are CG_PLAYER_AMMO_VALUE, CG_PLAYER_HEALTH, and CG_PLAYER_ARMOR_VALUE. Each of these show a plain number if textScale is less than 0.75. Otherwise, they show a "full-size" element of a fixed size: CG_PLAYER_AMMO_VALUE 128x48 box showing all available ammo types and counts CG_PLAYER_HEALTH 128x24 horizontal graphical bar indicating health level. CG_PLAYER_ARMOR_VALUE 128x24 horizontal graphical bar indicating armor level.

See also: , , , , . textstyle ∫

Specifies a special effect to the text.

See also: , , , , , , backcolor &color;

Sets background color for the item when `style' is set to WINDOW_STYLE_FILLED.

See also: , , , , . forecolor &color;

Sets foreground color for the item. Most prominent use is setting text color, although it also influences the color of any alpha-valued images.

See also: , , , , . bordercolor &color;

Sets border color.

See also: , , , , , , outlinecolor &color;

This keyword works with text listbox. The selected text is highlighted with the given color. However, the outlining is done by drawing a box over the selection with the given color, so the best course of action is to use a very transparent color, such as "1 0 0 0.25".

See also: , , , , , , , . background &string;

Provided string is taken as a shader name or image file to display as the item's background, confined within the item rect.

Rect's `style' has to be set to WINDOW_STYLE_SHADER. The background image is scaled, ignoring aspect ratios, to fill the rect. In other words, the image is distorted as needed to fill the rect completely. See also .

See also: , , , . onFocus { &script; }

The given script is run when the item gets focus. This happens when the mouse rolls over it, the keyboard is used to move over to it (arrow keys), or focus is forcefully thrust upon it by another script.

See also: , , , , , , . leaveFocus { &script; }

The provided script is run when the item loses focus. Note that when a menu closes, its last focused item runs its `leaveFocus'.

See also: , , , , , . mouseEnter { &script; }

Runs the provided script when the mouse enter the item's rect.

See also: , , , . mouseExit { &script; }

Runs the provided script when the mouse leaves the item's rect.

See also: , , , . mouseEnterText { &script; }

Runs the provided script when the mouse touches text in item.

, , , , , . mouseExitText { &script; }

Runs the provided script when the mouse leaves text in item.

See also: , , , , , . action { &script; }

Runs the provided script when the mouse clicks in/on the item rect or when the Enter key is pressed while item has focus.

See also: , , . special &float;

Used in the HUD to set spacing on powerup item display. cvar &string;

This keyword indicates a cvar to alter, with the various ways of altering indicated in other statements (e.g. cvarFloat, cvarStrList, cvarFloatList, etc.)

For use in assigning keybinds, `type' has to be set to ITEM_TYPE_BIND, the `text' field holds the prompt (e.g. "Move forward:"), and `cvar' is the command to assign (e.g. "+forward").

See also: , , , , maxChars ∫

Maximum number of characters in an editfield.

See also: , , . maxPaintChars ∫

Maximum number of characters to show in an editfield.

See also: , , . focusSound &string;

Sound to play when item receives focus.

See also: , . cvarFloat &string; &float; &float; &float;

Set a cvar to a float value. The values correspond to: Cvar name Default value Minimum value Maximum value

This has commonly appeared in association with slider bars ("type ITEM_TYPE_SLIDER"). Best guess is that the lesser (left) extreme of the slider is assocated with ``minimum'', the greater (right) extreme associated with ``maximum'', and the starting position of the slider at ``default''.

See also: , , . cvarStrList { &string; &string; < &string; &string; < &string; &string; ... > > }

Used in Multi item (ITEM_TYPE_MULTI) to rotate through a list of values. Rotation occurs when the item is clicked (i.e. selecting). The strings are provided in pairs. The first of the pair is the string to display in the item when the pair is selected. The second of the pair is the string to store in the cvar.

The cvar specified by `cvar' is used to store the second value of the selected pair.

Example: cvarStrList { "Lightmap", "0", "Vertex Lighing", "1" }

This example would rotate between two values. The strings "Lightmap" and "Vertex Lighting" are shown, while the actual values "0" and "1" are assigned.

See also: , , , . cvarFloatList { &string;

Works on the same principle as cvarStrList, except it stores float values instead of strings.

See also: , , , . addColorRange &float; &float; &color;

Values are: Low High Color value (RGBA)

Applies to ownerdraw elements that have an ``obvious'' numerical value, such as health, armor, and scores. This keyword allows the ownerdraw element to be displayed in different colors depending on its numerical value. If the numerical value falls within ``low'' and ``high'' (inclusive), the item uses the (foreground) color that is listed. There can be as many uses of this statement as needed to cover the appropriate range of values, up to a hard limit of 10. After 10, additional uses are ignored. Note that this hardlimit can be changed in mods by mod authors. If any ranges overlap, the range listed later takes precedence.

Usage is best described by an example. itemDef { ownerdraw CG_PLAYER_HEALTH; addColorRange -999 24 1 0 0 1 //Red addColorRange 25 100 0 1 0 1 //Green addColorRange 101 999 1 1 1 1 //White }

The above draws the player's health. If the health value is within -999 to 24 (inclusive), the health value shows in red. If the health value is within 25 to 100 (inclusive), the health value shows in green. 101 and above (and up to 999), the health value shows in white. ownerdrawFlag ∫

Asks for a flag value (true/false) from the Q3A engine, and shows (on "true") or hides (on "false") the item based on the value. If the item was already invisible ("visible 0"), this item is not drawn regardless of ownerdrawFlag. Values for ownerdrawFlag are listed in

See also: , , , . cinematic &string;

Play a RoQ move file in the confines of the item rect. RoQ path name is indicated by the provided string.

See also: , , . cvartest &string;

Remembers this cvar's value for testing. Test actions are carried out by other statements, below.

See also: , , , . enableCvar { &string; <; &string; <; &string; ... > > }

If the cvar value of `cvartest' contains any of the listed values, the item is enabled (selectable).

See also: , , . disableCvar { &string; <; &string; <; &string; ... > > }

If the cvar value of `cvartest' contains any of the listed values, the item is disabled (unselectable).

See also: , , . showCvar { &string; <; &string; <; &string; ... > > }

If the cvar value of `cvartest' contains any of the listed values, the item is made visible.

See also: , , . hideCvar { &string; <; &string; <; &string; ... > > }

If the cvar value of `cvartest' contains any of the listed values, the item is made invisible (not drawn at all).

See also: , , . Script actions

The &q3ta; menu language has a very basic scripting language to effect changes in other menus or items. Multiple statements are separated by semicolon (;). fadein &string;

Causes a fade-in effect for items/menus with names or groups matching the given string.

See also: , , , , . fadeout &string;

Causes a fade-out effect for items/menus with names or groups matching the given string. , , , , . show &string;

Turns on visibility for items/menus with names or groups matching the given string.

See also: , , , . hide &string;

Turns off visibility for items/menus with names or groups matching the given string.

See also: , , , . open &string;

Opens a menu with name matching the given string.

See also: , . close &string;

Closes a menu with name matching the given string.

See also: , , . setasset &string;

Not used (ineffectual).

Programmer's (mod) note: Supposedly use asset with the given name, but the source code has as a no-op (empty function).

See also: , . setbackground &string;

Set/change background to the given shader name or filename.

See also: , , , , . setteamcolor &color;

Changes the teamcolor used by "style WINDOW_STYLE_TEAMCOLOR".

See also: , , . setitemcolor &string; &string; &color;

Item name to affect. The string "backcolor"

See also: , , . setfocus &string;

Change focus to item/group with name matching the given string.

See also: , setplayermodel &string;

The cvar "team_model" is set to the given string. setplayerhead &string;

The cvar "team_headmodel" is set to the given string. transition &string; ▭ ▭ ∫ &float;

Simple animation effect by altering the rect dimensions. item/group name to affect. starting dimensions. ending dimensions. lifetime of animation

See also: , , . setcvar &string; &string;

First string is the name of the cvar to alter. Second string is the value to assign to the cvar.

See also: . exec &string;

Execute a string as a console command. Note this is NOT the same "exec" to load a .cfg file. To load a .cfg file in a menu script action, you can use: exec "exec foo.cfg" play &string;

Play the sound file or sound name indicated by the string.

See also: , . playlooped &string;

Starts playing the sound in an infinite loop. Use empty string ("") to stop loop.

See also: , . orbit &string; &float; &float; &float; ∫

Start an orbiting camera. item to orbit (around(?))? Start angle? Delta (amount to change per step) angle? Number of seconds to spend orbiting? The angle values are assumed to be radian polar coordinates (distance, angle), as this makes the most sense in a rotation context that uses radian trigonometric functions. For quick reference, 0 rad is 0 degress, 1.5707963267 is 90 degress, 3.1415926535 is 180 degress, 6.2431853070 is 360 degress. uiScript &string;

Activates mod-specific actions based on string. This action is a means to trigger activity coded in the C portion of the mod. Valid parameters are mod-dependent, but those in the baseq3/q3ta source tree is provided.

See also: Values for item ``type''

These values are for field.

Determines a partcular behavior for an item. 0 ITEM_TYPE_TEXT

Text label widget (this item type is everywhere). Just displays a text string with no special action. This type is also the default if a particular type isn't explicitly set.

See also: , , , , , , , , . 1 ITEM_TYPE_BUTTON

A pushbutton widget. A mouse click inside of the item rect triggers the "action" script.

See also: , , , , , , , , , . 2 ITEM_TYPE_RADIOBUTTON

Not used.

Programmer's (mod) note: Not implemented yet. Radio button widget. Radio buttons are linked by their "group" name. Only one button of a radio button group may be selected. Selecting one radio button in a group causes all other buttons in the same group to deselect.

See also: , , , , , , , , , , , . 3 ITEM_TYPE_CHECKBOX

Not used.

Programmer's (mod) note: Checkbox widget. The traditional "yes/no" marker. Values can be stored in a cvar with the `cvar' field: "1" is assigned on a "yes" mark, "0" is assigned on a "no" mark.

See also: , , , , , , , , , , , . 4 ITEM_TYPE_EDITFIELD

A text-entry widget. Value can be stored to a cvar with the `cvar' field.

See also: , , , , , , , , , , , , . 5 ITEM_TYPE_COMBO

Not used.

Programmer's (mod) note: Not implemented yet. A combo box is also known as a drop-down list or pop-up list. The combo box normally appears as a single-line text. Clicking on the combo box shows/opens a list from which an item can be selected. The list disppears/closes to show the new item in the original rect. Combo boxes may optionally allow the text to be edited, thereby relegating the list to a a base/shortcut/common-case selector. 6 ITEM_TYPE_LISTBOX

Listbox widget. Creates a box with many items listed inside. Multiple items can be selected. Source of items to list is indicated by "feeder" statement.

See also: , , , , , , , 7 ITEM_TYPE_MODEL

Draw a Q3A 3D model. Model name is provided in a field.

See also: , , . 8 ITEM_TYPE_OWNERDRAW

Draw engine-supplied item (shader, model, health, flag status, etc.).

See also: , , , , . 9 ITEM_TYPE_NUMERICFIELD

Text-entry widget restricted to only numerical characters. An example cvar where this type is attached to is sv_maxClients (the maximal number of players allowed to connect simultaneously).

See also: , , . 10 ITEM_TYPE_SLIDER

A slider widget, such as for volume. The minimum and maximum values, along with starting slider value, are provided in a `cvarFloat' statement.

See also: , , . 11 ITEM_TYPE_YESNO

Pre-packaged dialog box that has a "Yes" and a "No" button. Relieves the burden of having to specify all other elements to create a simple yes/no dialog window. Result is stored in the cvar indicated by the `cvar' field, 1 for yes, 0 for no. XXX: verify

See also: , . 12 ITEM_TYPE_MULTI

Multi-item widget. Coupled with "cvarStrList" or "cvarFloatList", clicking on the item rotates through the available values/strings.

See also: , , , . 13 ITEM_TYPE_BIND

When the item is selected, Q3A enters a special state that traps keystrokes in order to bind it. The action to bind to the key is indicated by the `cvar' field (e.g. cvar "+forward"). The `text' field provides the prompt (e.g. text "Move forward:").

See also: , , . Values for ``style''

These are the values that can be used for the field or field. Either the numeric value or the name (without quotes) can be used. 0 WINDOW_STYLE_EMPTY

Don't add anything special. 1 WINDOW_STYLE_FILLED

Solid fill with `backcolor', adding any fade effects parameterized in `fadeClamp', `fadeCycle', `fadeAmount'.

See also: , , , , . 2 WINDOW_STYLE_GRADIENT

Gradient effect with `backcolor'. 3 WINDOW_STYLE_SHADER

Fill with shader indicated in `background'.

See also: , . 4 WINDOW_STYLE_TEAMCOLOR

Fill with team color at 33% alpha.

See also: . 5 WINDOW_STYLE_CINEMATIC

Fill with cinematic (movie, RoQ format).

See also: . Values for ``border''

These values can be used for either the the field or field. You can use either the numeric value or the name (without quotes). Borders are drawn within the boundaries of a menu/item, and the available space within shrinks according to the border size. 0 WINDOW_BORDER_NONE

No border is drawn. 1 WINDOW_BORDER_FULL

Borders are drawn along the top, bottom, left, and right edges. 2 WINDOW_BORDER_HORZ

Draw only along the top and bottom (horizontal) edges. 3 WINDOW_BORDER_VERT

Draw only along the left and right (vertical) edges. 4 WINDOW_BORDER_KCGRADIENT

Draw only along the top and bottom edges with the KC (Kevin Cloud?) Gradient effect. Values for ``textstyle''

These values are used for the field. Either the numeric or name value can be used. 0 ITEM_TEXTSTYLE_NORMAL

Normal, solid text. 1 ITEM_TEXTSTYLE_BLINK

Fast blinking; roughly two cycles per second (2 Hz). 2 ITEM_TEXTSTYLE_PULSE

Not used.

Programmer's (mod) note: Not implemented? Slow blinking, pulsing effect; roughly two seconds per cycle (0.5 Hz). 3 ITEM_TEXTSTYLE_SHADOWED

Drop-shadow effect. 4 ITEM_TEXTSTYLE_OUTLINED

Not used.

Programmer's (mod) note: Not implemented yet. Outline effect. 5 ITEM_TEXTSTYLE_OUTLINESHADOWED

Not used.

Programmer's (mod) note: Not implemented yet. Combined shadow and outline effect. 6 ITEM_TEXTSTYLE_SHADOWEDMORE

Not used.

Programmer's (mod) note: Not implemented yet. Extra shadow effect. Values for ``feeder''

These values can be used for the field, used to fill up a listbox item. Most feeders supply one item per line. Some are multi-columned, such as in-game players listing. For the most part, you can safely assume a feeder is single-columned (one item per line), unless otherwise indicated. 0 FEEDER_HEADS

List of Q3A head models used in the game. Can be texts or images. 1 FEEDER_MAPS

List of names of available Q3A maps (levels) for single-player mode. Text-only.

See also: 2 FEEDER_SERVERS

List of Q3A servers. Consists of the following columns: Host name Map name Number of clients connected Gametype Ping

(text)

See also: , 3 FEEDER_CLANS

Not used. 4 FEEDER_ALLMAPS

List of all Q3A maps playable for an online game, according to gametype. Can be texts or images.

See also: , 5 FEEDER_REDTEAM_LIST

Not used.

Programmer's (mod) note: Not implemented? Scores listing of red team. Consists of seven columns per player/line: Player's handicap value if any, flag (red, blue, white) instead if have flag. Team Leader icon (an "L") if player is team leader. "Ready" indicator at intermission; wins/losses in tournament mode; "Spectator" if spectating; "Leader" string. Player's name Player's score Player's time spent playing in minutes. ping time, or "connecting" string.

(text) 6 FEEDER_BLUETEAM_LIST

Not used.

Programmer's (mod) note: Not implemented? Scores listing of blue team. Consists of seven columns per player/line: Player's handicap value if any, flag (red, blue, white) instead if have flag. Team Leader icon (an "L") if player is team leader. "Ready" indicator at intermission; wins/losses in tournament mode; "Spectator" if spectating; "Leader" string. Player's name Player's score Player's time spent playing in minutes. ping time, or "connecting" string.

(text) 7 FEEDER_PLAYER_LIST

List of all players in the game. Text-only. 8 FEEDER_TEAM_LIST

List of all teams in the game. Text-only. 9 FEEDER_MODS

List of available Q3A mods. Text-only.

See also: , 10 FEEDER_DEMOS

List of available recorded demos (file names). Text-only.

See also: , 11 FEEDER_SCOREBOARD

Not used.

Programmer's (mod) note: Not implementd? Scoreboard listing (non-team game?) (text? mixed?) 12 FEEDER_Q3HEAD

List of all available Q3A head models. Can be text or image. 13 FEEDER_SERVERSTATUS

A listing showing the server's players over a remote query (out-of-game, as from server browser). Consists of the following columns: client number client score client ping client name

(text)

See also: , , 14 FEEDER_FINDPLAYER

List of servers containing the player name for which you are searching. (text) 15 FEEDER_CINEMATICS

List of available cinematics (RoQ files). (text?) List is updated by uiScript ``LoadMovies''.

See also: , Values for cgame ``ownerdraw''

These are the values for the or field. This set of values is used in the cgame menu, aka . 0 CG_OWNERDRAW_BASE

ALL YOUR BASE ARE BELONG TO US. 1 CG_PLAYER_ARMOR_ICON

Armor icon for the player (red or yellow), as image. 2 CG_PLAYER_ARMOR_VALUE

Armor value, as numeric text. 3 CG_PLAYER_HEAD

The player's head model, as 3D model. 4 CG_PLAYER_HEALTH

The player's health, as numeric text. 5 CG_PLAYER_AMMO_ICON

Icon of the ammo currently being used (matched up to the weaon in hand), as image. 6 CG_PLAYER_AMMO_VALUE

Ammo count, as numeric text. 7 CG_SELECTEDPLAYER_HEAD

Head model of the currently selected player, as 3D model. 8 CG_SELECTEDPLAYER_NAME

Name as the currently selected player, as text. 9 CG_SELECTEDPLAYER_LOCATION

Location of the currently selected player, as text. 10 CG_SELECTEDPLAYER_STATUS

Status (Attack, Defend, Escort, etc.) of currently selected player, as image. 11 CG_SELECTEDPLAYER_WEAPON

Not used.

Programmer's (mod) note: Weapon wielded by currently selected player, as image. 12 CG_SELECTEDPLAYER_POWERUP

Powerup held by currently selected player, as image. 40 CG_SELECTEDPLAYER_ARMOR

Armor value of currently selected player, as numeric text. 41 CG_SELECTEDPLAYER_HEALTH

Health value of currently selected player, as numeric text. 13 CG_FLAGCARRIER_HEAD

Not used.

Programmer's (mod) note: Not implemented yet. Head model of flag carrier, as 3D model. Note that flag carrier means "whoever on your own team that has stolen the/a flag", and not that of the other team's. 14 CG_FLAGCARRIER_NAME

Not used.

Programmer's (mod) note: Not implemented yet. Name of flag carrier, as text. 15 CG_FLAGCARRIER_LOCATION

Not used.

Programmer's (mod) note: Not implemented yet. Location of flag carrier, as text. 16 CG_FLAGCARRIER_STATUS

Not used.

Programmer's (mod) note: Not implemented yet. Status of flag carrier, as image. 17 CG_FLAGCARRIER_WEAPON

Not used.

Programmer's (mod) note: Not implemented yet. Weapon wielded by flag carrier, as image. 18 CG_FLAGCARRIER_POWERUP

Not used.

Programmer's (mod) note: Not implemented yet. Powerup held by the flag carrier, as image. 19 CG_PLAYER_ITEM

Item currently held by player, as image. 20 CG_PLAYER_SCORE

Player's score, as numeric text. 21 CG_BLUE_FLAGHEAD

Head model of red team member carrying the blue flag, as 3D model. 22 CG_BLUE_FLAGSTATUS

Status (Attack, Defend, Retrieve, etc.) of red team member carrying the blue flag, as image. 23 CG_BLUE_FLAGNAME

Name of red team member carrying the blue flag, as text. 24 CG_RED_FLAGHEAD

Head model of the blue team member carrying the red flag, as image. 25 CG_RED_FLAGSTATUS

2D icon of the red flag's status, as image. Status is "at stand", "dropped", or "stolen". 26 CG_RED_FLAGNAME

Name of the blue team member carrying the red flag, as text. 27 CG_BLUE_SCORE

Blue team's score, as numeric text. 28 CG_RED_SCORE

Red team's score, as numeric text. 29 CG_RED_NAME

Red team's name (clan name), as text. 30 CG_BLUE_NAME

Blue team's name (clan name), as text. 31 CG_HARVESTER_SKULLS

Number of skulls collected in Harvester mode, as numeric text. 32 CG_ONEFLAG_STATUS

Status of the flag in one-flag mode (at stand, stolen, dropped), as image(?). 33 CG_PLAYER_LOCATION

Location of player, as text. 34 CG_TEAM_COLOR

Player's team color (e.g. for filling in a rect background color), as color. 35 CG_CTF_POWERUP

Q3TA CTF persistent powerup held by player, as image. 36 CG_AREA_POWERUP

Player's powerup in hand in CTF mode, as image. 37 CG_AREA_LAGOMETER

Not used.

Programmer's (mod) note: Not implemented yet. Draw lagometer, as (animated) image. The current lagometer uses the old drawing functions, drawn at a fixed location. 38 CG_PLAYER_HASFLAG

Draws the flag if the player has it, as image. For the old-timers, this correlates to the flag icon appearing when you steal the flag With simpleItems, this draws the 2D flag icon. Otherwise it draws the rotating 3D model of the flag. 39 CG_GAME_TYPE

Game type ("CTF", "One Flag", "Harvester", etc.), as text. 42 CG_PLAYER_STATUS

Player status (Attack, Defend, Escort, etc.), as image. 43 CG_FRAGGED_MSG

Not used.

Programmer's (mod) note: Not implemented yet (empty function). Probably the "You fragged ..." message, as text. 44 CG_PROXMINED_MSG

&q3ta; proximity mine message, as text. 45 CG_AREA_FPSINFO

Not used.

Programmer's (mod) note: Not implemented yet. FPS info ("## fps"), as text. The current FPS info display uses the old draw functions, drawn at a fixed location. 46 CG_AREA_SYSTEMCHAT

Not used.

Programmer's (mod) note: Not completed yet. All system (non-chat) messages? 47 CG_AREA_CHAT

Not used.

Programmer's (mod) note: Not completed yet. Global (non-team?) chat texts. 48 CG_AREA_TEAMCHAT

Not used.

Programmer's (mod) note: Not completed yet. Team-only chat texts. 49 CG_GAME_STATUS

In single player mode, ranking information (e.g. "5th place with -4 frags"), as text. In team game, team rankings (e.g. "Red leads Blue, 42 to 17"), as text. 50 CG_KILLER

Name as text of the last player to kill you, as text. 51 CG_PLAYER_ARMOR_ICON2D

Draw armor icon, as image. 2D image only. 52 CG_PLAYER_AMMO_ICON2D

Draw ammo icon for current weapon, as image. 2D image only. 53 CG_ACCURACY

Accuracy score, icon + text (e.g. "34%") 54 CG_ASSISTS

Assists score, icon + text (e.g. "12") 55 CG_DEFEND

Defense score, icon + text (e.g. "8") 56 CG_EXCELLENT

Excellents score, icon + text (e.g. "3") 57 CG_IMPRESSIVE

Impressives score, icon + text (e.g. "2") 58 CG_PERFECT

Perfects score, icon + text (e.g. "0") 59 CG_GAUNTLET

Humiliations score, icon + text (e.g. "5") 60 CG_SPECTATORS

Marquee-effect (scrolling-to-left text) of players in spectator mode, as (scrolling) text. 61 CG_TEAMINFO

The Team Info Overlay display, as image + text combination. 62 CG_VOICE_HEAD

Head model of the last player that sent a voice message, as image. 63 CG_VOICE_NAME

Name of the last player that sent a voice message, as text. 64 CG_PLAYER_HASFLAG2D

Flag icon when the player has the flag, as image. With simpleItems, this draws the flat 2D icon of the flag. Otherwise, it draws the rotating 3D flag model. For the time being, this is does the exact same thing as CG_PLAYER_HASFLAG. Presumably the two will either merge or take separate meanings in the future. 65 CG_HARVESTER_SKULLS2D

The skulls icon, as image. 66 CG_CAPFRAGLIMIT

Either the frags limit or captures limit of the game, according to game type, as text. 67 CG_1STPLACE

For individuals-based gametypes (Free-For-All, Tournament), the highest score, as numeric text. For team games (TDM, CTF), score of red team, as numeric text. Nothing/blank in single-player mode. 68 CG_2NDPLACE

For individuals-based gametypes (Free-For-All, Tournament), the second-highest score, as text. For team games (TDM, CTF), score of blue team, as text. Nothing/blank in single-player mode. 69 CG_CAPTURES

Number of captures (icon + text) by player. 70 CG_EXTRA

Specific to &wfa;. Shows the class-specific special equipments in use, such as lasers, sentries, depots, and alarms. 71 CG_POINTSTATUS

Specific to &wfa;. Draws the status of the command points in Command Point gametype. Command Point involves at least three control points that must be conquered and held by a team. A team gains some a score point per second per command point in its control. Game ends when a team reaches the score limit. 72 CG_HEADSHOTS

Specific to &wfa;. Number of headshots (icon + text) by player. Values for cgame ``ownerdrawflag''

These values can be used for the field, to control the appearance of an content depending on an engine-dependent value. A ``false'' result causes the item to remain invisible, while a ``true'' result procedes with drawing the content. These ownerdrawFlag values are used for the cgame menu, aka . For convenience, the condition for a true result is listed, while false is assumed if the listed condition is not met. The description can be prefixed with ``Draw this when/if...'' to help clear up confusion. CG_SHOW_BLUE_TEAM_HAS_REDFLAG

... blue team has the red flag. CG_SHOW_RED_TEAM_HAS_BLUEFLAG

... red team has the blue flag. CG_SHOW_ANYTEAMGAME

... in a team-based game mode (TDM, 1CTF, 2CTF, etc.) CG_SHOW_HARVESTER

... in Harvester game mode only. CG_SHOW_ONEFLAG

... in One-flag CTF game mode only. CG_SHOW_CTF

... in Two-flag (traditional) CTF game mode only. CG_SHOW_OBELISK

... in Obelisk (Overload?) game mode. CG_SHOW_HEALTHCRITICAL

... health is critically low (<25). Default HUD uses this to make the health HUD flash on low health. CG_SHOW_SINGLEPLAYER

... in Single-Player game (as opposed to a networked game). CG_SHOW_TOURNAMENT

... in Tournament game mode only. CG_SHOW_DURINGINCOMINGVOICE

... a radio message comes in (Q3TA-style voice command/chat). CG_SHOW_IF_PLAYER_HAS_FLAG

... player has the flag. This is useful for showing a special icon only when the player him/herself has the flag. CG_SHOW_LANPLAYONLY

... in Networked game (as opposed to single-player or local multiplayer [bots]). The lagometer is an example of where this is meaningful. CG_SHOW_MINED

... mine(s) has been placed (TA-style mines). CG_SHOW_HEALTHOK

... health is OK, i.e. non-critical (>25). CG_SHOW_TEAMINFO

... Team Info is being selected/shown (teammate is not selected). XXX need section on selectedplayer information CG_SHOW_NOTEAMINFO

... Team Info is not being selected/shown (teammate is selected). XXX again, need section on selectedplayer CG_SHOW_OTHERTEAMHASFLAG

... other team has the/your flag (CTF, one-flag). CG_SHOW_YOURTEAMHASENEMYFLAG

... your team as the/their flag (CTF, one-flag). CG_SHOW_ANYNONTEAMGAME

... in any non-team-based games (FFA, tournament, etc.). CG_SHOW_2DONLY

... this flag is something of an anomaly, since it instructs the menu system to do something, rather than requesting a value. It causes the ownerdraw item to be drawn in 2D form, instead of 3D, as if simpleItems were turned on. Multiple ownerdrawFlags may be listed, with the effects being combined inclusively (boolean "OR" operation). XXX need example. Values for ui ``ownerdraw''

These are the values for the or field. This set of values are used in the ui menu, aka "main menu" or "ESC menu". 0 UI_OWNERDRAW_BASE

?? 1 UI_HANDICAP

Player's handicap, as text. 2 UI_EFFECTS

Player's effect (rail trail color), as slider. 3 UI_PLAYERMODEL

Player's chosen Q3A character model (full model, as in the setup menu), as 3D model. 4 UI_CLANNAME

Player's clan name, as text. 5 UI_CLANLOGO

Player's clanlogo, as image/shader. 6 UI_GAMETYPE

The gametype, as text. 7 UI_MAPPREVIEW

The map preview (that little screenshot), as image. 8 UI_SKILL

The bot skill level, as text. (Single-player mode only?) 9 UI_BLUETEAMNAME

The blue team name, as text. 10 UI_REDTEAMNAME

The red team name, as text. 11 UI_BLUETEAM1

Blue team leader - for use in bots setup for server/network/local multiplayer game, as text. 12 UI_BLUETEAM2

Blue team member 2 - for use in bots setups for server/network/local multiplayer game, as text. 13 UI_BLUETEAM3

Blue team member 3 - for use in bots setups for server/network/local multiplayer game, as text. 14 UI_BLUETEAM4

Blue team member 4 - for use in bots setups for server/network/local multiplayer game, as text. 15 UI_BLUETEAM5

Blue team member 5 - for use in bots setups for server/network/local multiplayer game, as text. 16 UI_REDTEAM1

Red team leader - for use in bots setups for server/network/local multiplayer game, as text. 17 UI_REDTEAM2

Red team member 2 - for use in bots setups for server/network/local multiplayer game, as text. 18 UI_REDTEAM3

Red team member 3 - for use in bots setups for server/network/local multiplayer game, as text. 19 UI_REDTEAM4

Red team member 4 - for use in bots setups for server/network/local multiplayer game, as text. 20 UI_REDTEAM5

Red team member 5 - for use in bots setups for server/network/local multiplayer game, as text. 21 UI_NETSOURCE

Source of servers list: Local, Internet, MPlayer, Favorites, etc., as text. 22 UI_NETMAPPREVIEW

The map preview (the little screenshot) on selected server, as image. 23 UI_NETFILTER

The name as text of the game-type filter on servers listing, as text. 24 UI_TIER

Tier level, as text. Presumably only in single-player mode. 25 UI_OPPONENTMODEL

The opponent's model, as 3D model.

explains: Some people (pro players) like to specify the model they play against, as they feel certain models are easier to see, hit, etc. 26 UI_TIERMAP1

Not used. 27 UI_TIERMAP2

Not used. 28 UI_TIERMAP3

Not used. 29 UI_PLAYERLOGO

Player's clan graphic, as image. 30 UI_OPPONENTLOGO

Opponent's clan graphic, as image. 31 UI_PLAYERLOGO_METAL

Players's metal-theme clan logo, as image. 32 UI_OPPONENTLOGO_METAL

Opponent's metal-theme clan logo, as image. 33 UI_PLAYERLOGO_NAME

Player's clan name graphic, as image. 34 UI_OPPONENTLOGO_NAME

Opponent's clan name graphic, as image. 35 UI_TIER_MAPNAME

The name of the current map in the current tier, as text. 36 UI_TIER_GAMETYPE

The game type of the current map in the current tier, as text. 37 UI_ALLMAPS_SELECTION

The name of the current net map, as text. 38 UI_OPPONENT_NAME

The contents of cvar "ui_opponentName", as text. 39 UI_VOTE_KICK

Not used.

Programmer's (mod) note: Not implemented? The kick-vote menu. 40 UI_BOTNAME

The name of the currently selected bot, as text. 41 UI_BOTSKILL

The skill level of the currently selected bot, as text. 42 UI_REDBLUE

"Red" or "Blue" depending on which team the player is on, as text. 43 UI_CROSSHAIR

The crosshair, as image. Set `forecolor' to something noticeable to keep this from being invisible.

See also: , 44 UI_SELECTEDPLAYER

Selected player name, as text. If you are the team leader draw, the contents of cvar "cg_selectedPlayerName". Otherwise, the contents of the cvar "name". 45 UI_MAPCINEMATIC

Map preview (single-player), as cinematic. Map selection is stored in cvar ``ui_currentMap'' and used as an integer index into the list of available single-player maps () (starting with 0); other parts of the ui modify the cvar accordingly. For a given map named ``mapname'', attempts to use the first matching file name in the sequence of: "levelshots/mapname_small.roq" "levelshots/mapname_small.tga" "levelshots/mapname_small.jpg" "menu/art/unknown.jpg" Mod programmers can change the sequence and extensions used.

See also: , 46 UI_NETGAMETYPE

The gametype on a network game, as text. 47 UI_NETMAPCINEMATIC

Preview of a map in a networked game, as cinematic. Map selection is stored in ``ui_currentNetMap'' and used as an integer index into the list of all available maps (). Acts just like , except for the cvar and feeder sources used. (XXX: only applicable for starting server?)

See also: , 48 UI_SERVERREFRESHDATE

Date of last servers listings update, as text. 49 UI_SERVERMOTD

Server MOTD ("Message Of The Day", which has historically devolved into actually meaning "a message you see when you connect/login"), as text. 50 UI_GLINFO

Information about the active OpenGL rendering system, as multi-line text.. 51 UI_KEYBINDSTATUS

Message dependign on current status of binding a key, as text. If not waiting for a key to bind: "Press ENTER or CLICK to change. Press BACKSPACE to clear." If waiting for a key to bind: "Waiting for new key... Press ESCAPE to cancel." 52 UI_CLANCINEMATIC

The RoQ movie where its name matches that of the player's team logo name (the cinematic version of the team logo), as cinematic. 53 UI_MAP_TIMETOBEAT

The time to beat for this map in minutes and seconds, as text. 54 UI_JOINGAMETYPE

The game type of the selected game (network/multiplayer server), as text. 55 UI_PREVIEWCINEMATIC

Play a cinematic. Cinematic to play is started with the console command "cinematic MOVIE.roq" or the uiScript command "playMovie n", where 'n' is an integer index into the list of all available movie files ().

See also: , , , 56 UI_STARTMAPCINEMATIC

The RoQ movie where its name matches that of the currently selected map (cinematic version of map preview), as cinematic. 57 UI_MAPS_SELECTION

The name of the current map, as text. Values for ui ``ownerdrawflag''

These values can be used for the field, to control the appearance of an content depending on an engine-dependent value. These values are used for the ui menu, aka "main menu" or "ESC menu". Condition for a ``true'' result is listed; ``false'' if the condition(s) is/are not met. The phrase "Draw this when/if..." may be prefixed to the description to help clarify confusion. UI_SHOW_LEADER

... player is the team leader. This flag can be used to show a team-leader-only commands submenu (such as relinquishing leadership). Team leader is indicated by an "L" icon in the scores listing. UI_SHOW_NOTLEADER

... player is not the leader. This flag could be used to show a box indicating the team leader. UI_SHOW_FAVORITESERVERS

... on a favorite server. A favorite server is one in the "favorite servers" list. UI_SHOW_ANYNONTEAMGAME

... in any non-team-based games (FFA, tournament, etc.). UI_SHOW_ANYTEAMGAME

... in any team-based games (TDM, CTF, 1CTF, etc.). UI_SHOW_NEWHIGHSCORE

... player got the newest high score. Only applicable to single-player game. UI_SHOW_DEMOAVAILABLE

... a valid demo file exists (i.e. check if there's any demos available). UI_SHOW_NEWBESTTIME

... player got the newest best time. Only applicable to single-player game. UI_SHOW_FFA

... in a FFA (Free-For-All) game type. UI_SHOW_NOTFFA

... in a non-FFA game type. UI_SHOW_NETANYNONTEAMGAME

... in any team-based game on a network.

Useful for showing a menu item to save current server to favorite's list. Saving a single-player server (local machine) to the list is pointless. UI_SHOW_NETANYTEAMGAME

... in any non-team-based game on a network. UI_SHOW_NOTFAVORITESERVERS

... player is on a not-favorite server (server is not on favorites list). Values for ``uiScript''

Many thanks to for starting this section.

These values are used for . These are game-specific internal actions that cannot be effected by .menu text alone. These are actions carried out in the mod's C code, but triggered from the menus. In a way, they are like hooks for actions into the mod from the menus. Mod makers can create their own uiScript components; the pattern is in ui/ui_main.c, UI_RunMenuScript().

The listed values here appear in the source for Q3[T]A 1.27. Values are case-insensitive, but I still preserve the capitalization as it appears in the source text. stopRefresh

Stops the updating of servers list (when you try to join an online game). In other words, queries to the master server and servers are terminated.

See also: , , LoadDemos

Loads a list of demos to be used with the demo feeder. This also updates the feeder source for FEEDER_DEMO.

See also: , , LoadMods

Loads a list of demos to be used with the mods feeder. This also updates the feeder source for FEEDER_MODS. If a file named `description.txt' exists in a mod directory, the first line of that file is used as the mod's name in the feeder list. If no such file exists, the name of the directory itself is used.

See also: , , playMovie

Starts playing the RoQ selected in the movies list. The movies list is any widget using a movie feeder.

See also: , , verifyCDKey

Combines the cvars "cdkey1" through "cdkey4" into a single cvar "cdkey", which is then passed through the Quake3 internal cdkey verification function. After verification is complete, the cvar "ui_cdkeyvalid" contains a message indicating the result.

See also: StartServer

Starts a server, and the associated online game (instead of just joining). Initialized values include dedicated setting, gametype, number of available spots (maxClients), number of bots, bot names (if any).

See also: updateSPMenu

Update the Single Player menu based on latest achievements, such as after completing a [new] arena.

See also: , resetDefaults

Resets many settings to default: video, sound, game, input, keys. Many of the default settings are set by running the script named 'default.cfg'. This should be packaged in pak0.pk3.

See also: getCDKey

Retrieves the stored CD key from internal Quake 3 memory, and stores into 4-character pieces into cvars "cdkey1" through "cdkey4".

See also: loadArenas

Loads list of maps for starting server.

See also: , , , loadGameInfo

Parses "gameinfo.txt" file. Also loads (single-player) best scores for each map.

See also: resetScores

Resets best scores for each map.

See also: RefreshServers

Refresh the list of servers (when you want to play online). This clears the list, queries the master servers for list of servers, then pings each of the servers.

See also: , , , RefreshFilter

Refresh list of servers according to filter. This doesn't clear the list of servers, but still (re-)pings the servers in the list.

See also: , , RunSPDemo

Plays back a demo. The demo to play is the one selected in the list that uses a demo feeder.

See also: , , LoadMovies

Load a list of movies.

See also: , , RunMod

Run mod selected in listbox. The mod to load is the one selected in the list using the mods feeder.

See also: , , Quake3

Switch to baseq3 (the version without all the nifty new menu code).

See also: closeJoin

If server list refresh is in progress, the refreshing is stopped.

See also: ServerStatus

Retrieve status of selected server (server cvars, player list, etc.). The selected server is the one selected in the list using the servers feeder. Updates the serverstatus feeder.

See also: , , , , FoundPlayerServerStatus

Retrieves status of server. The selected server is the one selected in the list using the findplayer feeder. Updates the serverstatus feeder.

See also: , , , FindPlayer

Search for a player's name in the list of servers. Player name to find is stored in the car ``ui_findPlayer''. Color codes are stripped during search (i.e. color codes don't matter). The specified name is searched as a substring (i.e. it can be a short piece found inside a longer name, and exact matches also show up). Updates the findplayer feeder with the list of server names.

See also: JoinServer

Join the game on the selected server. The server to join is the one selected in the list using the servers feeder.

See also: , FoundPlayerJoinServer

Joins the server with the player for whom you were searching, if found. The server to join is the one selected in the list using the findplayer feeder.

See also: , Quit

Quits Quake 3 as a program entirely. The cvar "ui_singlePlayerActive" is set to 0 on quitting. (XXX: cvar ui_singlePlayerActive is used to determine if, on error condition, an error message popup window should be used (1) or not (0). Find a better place to put this info.)

See also: , Controls

Pauses the game (in a manner), ui module takes control of the keyboard, then menu "setup_menu2" is opened. Basically, prepares Quake 3 for the player to set key bindings.

See also: Leave

Quits from a game, but not Quake 3 entirely. Main menu is opened afterwards.

See also: , ServerSort ∫

Sort the list of servers (when you want to join online game). The parameter indicates which column to sort. If a new column is selected, the list is sorted in ascending order. If specified again for the second time in a row, the sort direction is reversed. Each time the column is re-selected without a new column selected (i.e. clicking on the same column again and again), the sort direction is sorted in the other order (i.e. sort order keeps switching).

See also: , nextSkirmish

Single-player game, go on to next round (as from the podiums display at the end of a round). SkirmishStart

Start single-player game.

See also: glCustom

Set "Video Setting" label to "Custom" (out of "Low", "Medium", "High", "Custom").

See also: saveControls

Commits the displayed bindings setup to actual binds for Quake 3.

See also: loadControls

Retrieves key binds from Quake 3 to set up the displayed bindings.

See also: clearError

Sets the cvar ``com_errorMessage'' to an empty string. This, in effect, clears the stored error message. The cvar ``com_errorMessage'' is set upon any error condition by the Quake 3 engine. This is sort of like a bridge for error messages between the Quake 3 engine and the mod space. UpdateFilter

Refresh the list of servers with the new selected filter. XXX: does this re-ping the servers? closeingame

Closes the in-game menu. The in-game menu is the menu usually bound to ESC. voteMap

Call a vote to switch to the selected map. The selected map is the one selected in the listbox using the allmaps feeder.

See also: , voteKick

Call a vote to kick the selected player. The selected player is the one selected in the listbox using the player_list feeder.

See also: , voteGame

Vote on gametype (FFA, TDM, CTF, etc.). (XXX: parameters?) voteLeader

Call a vote to make the selected player the team leader. Selected player is the one selected in the listbox using the team_list feeder.

See also: , addBot

Adds a bot to the (online) game. The selected bot is the one selected in the listbox using the heads feeder.

See also: , addFavorite

Add the currently joined server to the Favorite Servers list. (XXX: details... limits, time of saves, etc.) deleteFavorite

Delete current server from Favorite Servers list. (XXX: same queestions as addFavorite) createFavorite

Add to Favorite Servers list the server specified by the cvars ``ui_favoriteName'' and ``ui_favoriteAddress''. XXX: cvars set by user in a menu beforehand? orders &string;

Canned action after selecting an order (bot directive) from in-game menu. These orders help direct the actions of the game bots. The string is executed as a console command and menus are closed (to resume gameplay). If a teammate is selected with the cvar ``cg_selectedPlayer'', the order is sent to the teammate. Otherwise, the order is sent to the entire team. voiceOrdersTeam &string;

Canned action after selecting a team order from in-game menus. The strig is exected as a console command, and the menus closed (resuming gameplay). The order is implied to be applied to the team as a whole, so if a teammate is selected (cg_selectedPlayer), nothing is run.

See also: voiceOrders &string;

Canned action after selecting a bot order from in-game menus. The string is executed as a command, and menus closed (resuming gameplay). The order is implied to be applied only to a single player, so if a teammate is NOT selected, nothing is run.

See also: , update

Synchronize cvars. Cvars set in the menus are used to modify a set of other associated cvars. For example, reading cvar ``ui_glCustom'' (modified by the menus) to set the values of r_vertexLight, r_mode, cg_shadows, etc (modified with uiScript update). Heads-Up Display

The HUD is so named because it overlays information over the visual field. This is in contrast to "looking down" at a dashboard of instruments; a HUD provides critical information while the head is still "up". HUD components

The Q3TA HUD is a special case of the menus. It is the menu interpreter embedded in cgame (client game). Each HUD ``block'' is a menuDef, containing itemDefs that define the HUD contents. The complete HUD description is actually composed of three parts: The regular in-game HUD A non-team-game scoreboard A team-game scoreboard

Each may be individually customized. In fact, all three can be combined into one single file, however unwieldy that may be. The non-team-game scoreboard is one large menuDef that must be named (the `name' field) ``score_menu''. The team-game scoreboard is one large menuDef that must be named ``teamscore_menu''. When the player wants to see the scoreboard, Q3TA hides the entire HUD, and then display only one of the scoreboards by name depending on gametype.

The regular in-game HUD to use is determined by the contents of the cvar ``cg_hudFiles''. This value names a file that lists the in-game HUD menu files to use. This file may not exceed 4096 bytes in size. Default value for ``cg_hudFiles'' in Q3TA is "ui/hud.txt", the content of which is: { loadmenu { "ui/hud.menu" } loadmenu { "ui/score.menu" } loadmenu { "ui/teamscore.menu" } }

The keyword ``loadmenu'' indicate the menu file to load and parse. Multiple uses indicate multiple files to combine together. Each of the .menu has a filesize limit of 65536 bytes (XXX: verify).

The default descriptions for the menus `score_menu' and `teamscore_menu' are defined in ui/score.menu and ui/teamscore.menu, respectively.

The command ``loadhud'' enacts the actual change of HUD.

In the event of errors, the game may crash or quit. In the extreme case, you may have to set ``cg_hudFiles'' back to "ui/hud.txt" by some other means -- in the startup menus with "/set cg_hudFiles ui/hud.txt", or by manually editing q3config.cfg. Loading Custom HUD

In cookbook form: The file ``myhud.cfg'': { loadmenu { "myhud.menu" } loadmenu { "ui/score.menu" } loadmenu { "ui/teamscore.menu" } } The file ``myhud.menu'' describing the actual HUD (like ui/hud.menu) Commands to run in Q3 console: /set cg_hudFiles myhud.cfg /loadhud Restoring the default HUD: /set cg_hudFiles ui/hud.txt /loadhud GNU Free Documentation License

This document is distributed under the terms of the GNU Free Documentation License, a copy of which follows. Other copies and forms of the following is available on the World Wide Web at

GNU Free Documentation License Version 1.1, March 2000 Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five). C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H. Include an unaltered copy of this License. I. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version. N. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements." 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. ADDENDUM: How to use this License for your documents To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: Copyright (c) YEAR YOUR NAME. 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 the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled "GNU Free Documentation License". If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise for Back-Cover Texts. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.