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).
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:
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:
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.
The description of menus can lay across many files. In fact, the Quake III: Team Arena main menu is described across more than 30 files. There are three main components to the menu system:
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.
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" 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:
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" }
...
}
A menuDef is a grouping of itemDefs. The following describe keywords that are recognized in a menuDef body, but outside of any itemDef bodies.
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.
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: `itemDef::name', `itemDef::group', `script::open', `Script actions'.
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: `menuDef::fullscreen', `itemDef::rect', `script::transition'.
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: `menuDef::rect', `script::transition'.
Defines a window style for the menu.
See also: Values for ``style'', `itemDef::style', Values for ``style''.
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: `itemDef::visible', `script::show', `script::hide'.
Runs the provided script when the menu opens. When Quake III: Team Arena 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: `menuDef::onClose', `itemDef::leaveFocus', `script::open', `Script actions'.
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: `menuDef::onOpen', `menuDef::outOfBoundsClick', `script::close', `Script actions'.
Runs the provided script when the Escape key (ESC) is pressed. This action usually closes the menu (by opening another).
See also: `menuDef::outOfBoundsClick', `script::open', `Script actions'.
Sets a border type.
See also: Values for ``border'', `menuDef::bordersize', `menuDef::bordercolor', `itemDef::border'.
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: `menuDef::border', `menuDef::bordercolor', `itemDef::bordersize'.
Sets the menu background color. Only meaningful if the rect `style' is set to WINDOW_STYLE_FILLED.
See also: `menuDef::style', `menuDef::background', `menuDef::bordercolor', `menuDef::focuscolor', `menuDef::disablecolor', `itemDef::backcolor'.
Sets menu foreground color. Used as tint color for background shaders.
See also: `menuDef::style', `menuDef::backcolor', `menuDef::bordercolor', `menuDef::focuscolor', `menuDef::disablecolor', `itemDef::forecolor', `script::setitemcolor'.
Sets the border color.
See also: `menuDef::border', `menuDef::bordersize', `itemDef::bordercolor'.
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 disablecolor.
See also: `menuDef::disablecolor', `menuDef::backcolor', `itemDef::onFocus', `script::setfocus'.
Sets the text color of items when they are disabled. See also focuscolor, cvartest, disableCvar.
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: `menuDef::style', `itemDef::background'.
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: Values for cgame ``ownerdraw'', Values for ui ``ownerdraw'', `menuDef::style', `menuDef::ownerdrawflag', `itemDef::ownerdraw'.
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: Values for cgame ``ownerdrawflag''. Values for ui ``ownerdrawflag''. `menuDef::ownerdraw', `menuDef::ownerdrawflag'.
According to SweetnutZ, with this tag/flag in the menuDef, clicking outside the menu rectangle area causes the menu to close.
See also: `menuDef::onClose', `menuDef::onEsc'.
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: `script::play', `script::playerlooped'.
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: `menuDef::style', `itemDef::cinematic'.
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.
Along with fadeAmount and fadeCycle, implements a fade-in effect. Best advice so far: fiddle with it.
See also: `menuDef::fadeAmount', `menuDef::fadeClamp', `script::fadein', `script::fadeout'.
Along with fadeClamp and fadeCycle, implements a fade-in effect. Best advice so far: fiddle with it.
See also: menuDef::fadeCycle, menuDef::fadeClamp, `script::fadein', `script::fadeout'.
Along with fadeClamp and fadeAmount, implements a fade-in effect. Best advice so far: fiddle with it.
See also: menuDef::fadeCycle, menuDef::fadeAmount, `script::fadein', `script::fadeout'.
An itemDef describes on item member of a menu. The following keywords are recognized inside an itemDef:
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: `menuDef::name', `itemDef::group'.
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: `itemDef::textalign', `itemDef::textalignx', `itemDef::textaligny', `itemDef::textscale', `itemDef::textstyle'.
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: `itemDef::name', `menuDef::name'.
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: `itemDef::model_origin', `itemDef::model_fovx', `itemDef::model_fovy', `itemDef::model_rotation', `itemDef::model_angle'.
Apparently not used (ineffectual).
Apparently not used (ineffectual).
See also: `itemDef::asset_model', `itemDef::model_fovx', `itemDef::model_fovy', `itemDef::model_rotation', `itemDef::model_angle'.
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: `itemDef::asset_model', `itemDef::model_origin', `itemDef::model_fovy', `itemDef::model_rotation', `itemDef::model_angle'.
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: `itemDef::asset_model', `itemDef::model_origin', `itemDef::model_fovx', `itemDef::model_rotation', `itemDef::model_angle'.
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 thnom)
See also: `itemDef::asset_model', `itemDef::model_origin', `itemDef::model_fovx', `itemDef::model_fovy', `itemDef::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: `itemDef::asset_model', `itemDef::model_origin', `itemDef::model_fovx', `itemDef::model_fovy', `itemDef::model_rotation'.
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: `menuDef::fullscreen', `menuDef::rect'.
Fill style of the rect. Values are listed in Values for ``style''. Vaejor'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: Values for ``style'', `menuDef::style', `itemDef::cinematic', `menuDef::cinematic'.
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.
SweetnutZ points out that anything without this keyword will make mouseover sound and other assorted things.
Makes a List Box element unselectable. Used to make List Boxes display only.
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.
SweetnutZ 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: `itemDef::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: `itemDef::wrapped'.
Makes a List Box scroll horiziontally rather than vertically. Only applicable if the List Box is displaying graphical elements.
Sets the item type. If not specified, the default is ITEM_TYPE_TEXT. See also: Values for item ``type''.
Related to the width of elements inside an image listbox. SweetnutZ 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: `itemDef::elementheight', `itemDef::columns'.
As with `elementwidth', but with element height.
See also: `itemDef::elementwidth'.
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.
SweetnutZ 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: Values for ``feeder'', `itemDef::elementtype', `itemDef::columns'.
Specifies the type of element in a listbox, either text ("LISTBOX_TEXT", 0) or image ("LISTBOX_IMAGE", 1).
See also: `itemDef::elementheight', `itemDef::elementwidth', `itemDef::feeder'.
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:
See also: `itemDef::feeder', `itemDef::elementwidth', `itemDef::elementheight'.
Sets a border style for the item.
See also: `itemDef::borderSize', `itemDef::borderColor', menuDef::border'.
Sets the thickness of the border. The border is drawn on the inside of the item rect.
See also: `itemDef::border', `itemDef::borderColor', `menuDef::borderSize'.
Sets the visibility of the item. "0" prevents it from being drawn, "1" (or any other value) causes it to be drawn.
See also: `itemDef::cvartest', `itemDef::showCvar', `itemDef::hideCvar', `menuDef::visible', `script::show', `script::hide'.
Like the menu's ownerdraw, this statement makes a request to the Q3A engine to draw something within the item rect.
See also: Values for cgame ``ownerdraw'', Values for ui ``ownerdraw'', `itemDef::ownerdrawflag' `menuDef::ownerdraw'.
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: `itemDef::textalign'.
Determines where the horizontal alignment point is applied to text. Values are:
Left side of text.
Center of text.
Right side of text.
See also: `itemDef::text', `itemDef::textalignx', `itemDef::textaligny', `itemDef::textscale', `itemDef::textstyle'.
Horizontal text alignment in pixels (of 640 max) from left edge of rect to alignment point of text.
See also: `itemDef::text', `itemDef::textalign', `itemDef::textaligny', `itemDef::textscale', `itemDef::textstyle'.
Vertical text alignment in pixels (of 480 max) from top edge of rect to bottom of text.
See also: `itemDef::text', `itemDef::textalign', `itemDef::textalignx', `itemDef::textscale', `itemDef::textstyle'.
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:
128x48 box showing all available ammo types and counts
128x24 horizontal graphical bar indicating health level.
128x24 horizontal graphical bar indicating armor level.
See also: `itemDef::text', `itemDef::textalign', `itemDef::textalignx', `itemDef::textaligny', `itemDef::textstyle'.
Specifies a special effect to the text.
See also: Values for ``textstyle'', `itemDef::text', `itemDef::textalign', `itemDef::textalignx', `itemDef::textaligny', `itemDef::textscale',
Sets background color for the item when `style' is set to WINDOW_STYLE_FILLED.
See also: `itemDef::style', `itemDef::background', `itemDef::forecolor', `itemDef::bordercolor', `itemDef::outlinecolor'.
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: `itemDef::style', `itemDef::background', `itemDef::backcolor', `itemDef::bordercolor', `itemDef::outlinecolor'.
Sets border color.
See also: `itemDef::border', `itemDef::borderSize', `itemDef::forecolor', `itemDef::backcolor', `itemDef::outlinecolor', `menuDef::borderColor',
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: `ITEM_TYPE_LISTBOX', `itemDef::style', `itemDef::feeder', `itemDef::background', `itemDef::forecolor', `itemDef::backcolor', `itemDef::bordercolor', `itemDef::outlinecolor'.
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 menuDef background.
See also: `WINDOW_STYLE_SHADER', `itemDef::style', `itemDef::forecolor', `itemDef::backcolor'.
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: `itemDef::type', ITEM_TYPE_BUTTON, `itemDef::leaveFocus', `itemDef::forecolor', `menuDef::focusColor', `script::setfocus', Script actions.
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: `itemDef::type', ITEM_TYPE_BUTTON, `itemDef::onFocus', `menuDef::onClose', `menuDef::focuscolor', Script actions.
Runs the provided script when the mouse enter the item's rect.
See also: `itemDef::type', ITEM_TYPE_BUTTON, `itemDef::mouseExit', Script actiosn.
Runs the provided script when the mouse leaves the item's rect.
See also: `itemDef::type', ITEM_TYPE_BUTTON, `itemDef::mouseEnter', Script action.
Runs the provided script when the mouse touches text in item.
`itemDef::type', ITEM_TYPE_BUTTON, `itemDef::mouseExitText', `itemDef::mouseEnter', itemDef::mouseExit', Script actions.
Runs the provided script when the mouse leaves text in item.
See also: `itemDef::type', ITEM_TYPE_BUTTON, `itemDef::mouseEnterText', `itemDef::mouseEnter', itemDef::mouseExit', Script actions.
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: `itemDef::type', ITEM_TYPE_BUTTON, Script actions.
Used in the HUD to set spacing on powerup item display.
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: `itemDef::type', ITEM_TYPE_BIND, `itemDef::cvarFloat', `itemDef::cvarStrList',
Maximum number of characters in an editfield.
See also: `itemDef::type', ITEM_TYPE_EDITFIELD, `itemDef::maxPaintChars'.
Maximum number of characters to show in an editfield.
See also: `itemDef::type', ITEM_TYPE_EDITFIELD, `itemDef::maxChars'.
Sound to play when item receives focus.
See also: `itemDef::onFocus', `script::setfocus'.
Set a cvar to a float value. The values correspond to:
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: `itemDef::type', ITEM_TYPE_SLIDER, `itemDef::cvar'.
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: `itemDef::type', ITEM_TYPE_MULTI, `itemDef::cvar', `itemDef::cvarFloatList'.
Works on the same principle as cvarStrList, except it stores float values instead of strings.
See also: `itemDef::type', ITEM_TYPE_MULTI, `itemDef::cvar', `itemDef::cvarStrList'.
Values are:
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.
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 Values for cgame ``ownerdrawFlag''
See also: Values for cgame ``ownerdrawFlag'', Values for ui ``ownerdrawFlag'', `itemDef::ownerdraw', `menuDef::ownerdrawflag'.
Play a RoQ move file in the confines of the item rect. RoQ path name is indicated by the provided string.
See also: `menuDef::cinematic', `itemDef::type', WINDOW_STYLE_CINEMATIC.
Remembers this cvar's value for testing. Test actions are carried out by other statements, below.
See also: `itemDef::enableCvar', `itemDef::disableCvar', `itemDef::showCvar', `itemDef::hideCvar'.
If the cvar value of `cvartest' contains any of the listed values, the item is enabled (selectable).
See also: `itemDef::cvartest', `itemDef::disableCvar', `menuDef::disableColor'.
If the cvar value of `cvartest' contains any of the listed values, the item is disabled (unselectable).
See also: `itemDef::cvartest', `itemDef::enableCvar', `menuDef::disableColor'.
If the cvar value of `cvartest' contains any of the listed values, the item is made visible.
See also: `itemDef::cvartest', `itemDef::hideCvar', `script::show'.
If the cvar value of `cvartest' contains any of the listed values, the item is made invisible (not drawn at all).
See also: `itemDef::cvartest', `itemDef::showCvar', `script::hide'.
The Quake III: Team Arena menu language has a very basic scripting language to effect changes in other menus or items. Multiple statements are separated by semicolon (;).
Causes a fade-in effect for items/menus with names or groups matching the given string.
See also: `script::fadeout', `menuDef::fadeClamp', `menuDef::fadeAmount', `menuDef::fadeCycle', `script::transition'.
Causes a fade-out effect for items/menus with names or groups matching the given string. `script::fadein', `menuDef::fadeClamp', `menuDef::fadeAmount', `menuDef::fadeCycle', `script::transition'.
Turns on visibility for items/menus with names or groups matching the given string.
See also: `script::hide', `itemDef::cvartest', `itemDef::showcvar', `itemDef::hidecvar'.
Turns off visibility for items/menus with names or groups matching the given string.
See also: `script::show', `itemDef::cvartest', `itemDef::showcvar', `itemDef::hidecvar'.
Opens a menu with name matching the given string.
See also: `script::close', `menuDef::onOpen'.
Closes a menu with name matching the given string.
See also: `script::open', `menuDef::onClose', `menuDef::onEsc'.
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: `itemDef::asset_model', `itemDef::asset_shader'.
Set/change background to the given shader name or filename.
See also: `menuDef::style', `itemDef::style', WINDOW_STYLE_FILLED, `menuDef::background', `itemDef::background'.
Changes the teamcolor used by "style WINDOW_STYLE_TEAMCOLOR".
See also: `menuDef::style', `itemDef::style', WINDOW_STYLE_TEAMCOLOR.
See also: `itemDef::backcolor', `itemDef::forecolor', `itemDef::borderColor'.
Change focus to item/group with name matching the given string.
See also: `itemDef::onFocus',
The cvar "team_model" is set to the given string.
The cvar "team_headmodel" is set to the given string.
Simple animation effect by altering the rect dimensions.
See also: menuDef::fadeClamp, menuDef::fadeAmount, menuDef::fadeCycle.
First string is the name of the cvar to alter. Second string is the value to assign to the cvar.
See also: `itemDef::cvartest'.
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 the sound file or sound name indicated by the string.
See also: `script::playlooped', `menuDef::soundLoop'.
Starts playing the sound in an infinite loop. Use empty string ("") to stop loop.
See also: `script::play', `menuDef::soundLoop'.
Start an orbiting camera.
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 uiScript'
These values are for item `type' field.
Determines a partcular behavior for an item.
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: `itemDef::textscale', `itemDef::textalign', `itemDef::textalignx', `itemDef::textaligny', `itemDef::textstyle', `itemDef::forecolor', `itemDef::wrapped', `itemDef::autowrapped', `itemDef::decoration'.
A pushbutton widget. A mouse click inside of the item rect triggers the "action" script.
See also: `itemDef::type', `itemDef::action', `itemDef::onFocus', `itemDef::leaveFocus', `itemDef::mouseEnter', `itemDef::mouseExit', `itemDef::text', `itemDeF::forecolor', `itemDef::focuscolor', `itemDef::disablecolor'.
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: `itemDef::type', ITEM_TYPE_TEXT, `itemDef::cvar', `itemDef::group', `itemDef::onFocus', `itemDef::leaveFocus', `itemDef::mouseEnter', `itemDef::mouseExit', `itemDef::text', `itemDeF::forecolor', `itemDef::focuscolor', `itemDef::disablecolor'.
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: `itemDef::type', ITEM_TYPE_TEXT, `itemDef::cvar', `itemDef::group', `itemDef::onFocus', `itemDef::leaveFocus', `itemDef::mouseEnter', `itemDef::mouseExit', `itemDef::text', `itemDeF::forecolor', `itemDef::focuscolor', `itemDef::disablecolor'.
A text-entry widget. Value can be stored to a cvar with the `cvar' field.
See also: `itemDef::type', ITEM_TYPE_TEXT, `itemDef::cvar', `itemDef::maxChars', `itemDef::maxPaintChars', `itemDef::onFocus', `itemDef::leaveFocus', `itemDef::mouseEnter', `itemDef::mouseExit', `itemDef::text', `itemDeF::forecolor', `itemDef::focuscolor', `itemDef::disablecolor'.
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.
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: `itemDef::type', `itemDef::feeder', `itemDef::elementheight', `itemDef::elementwidth', `itemDef::columns', `itemDef::horizontalscroll', `itemDef::notselectable',
Draw a Q3A 3D model. Model name is provided in a `asset_model' field.
See also: `itemDef::type', `itemDef::asset_model', `script::setasset'.
Draw engine-supplied item (shader, model, health, flag status, etc.).
See also: `itemDef::type', Values for cgame ``ownerdraw'', Values for cgame ``ownerdraw'', Values for ui ``ownerdraw'', Values for ui ``ownerdrawflag''.
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: `itemDef::type', `itemDef::cvar', `itemDef::editField'.
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: `itemDef::type', `itemDef::cvar', `itemDef::cvarFloat'.
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: `itemDef::type', `itemDef::cvar'.
Multi-item widget. Coupled with "cvarStrList" or "cvarFloatList", clicking on the item rotates through the available values/strings.
See also: `itemDef::type', `itemDef::cvar', `itemDef::cvarStrList', `itemDef::cvarFloatList'.
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: `itemDef::type', `ITEM_TYPE_TEXT', `itemDef::cvar'.
These are the values that can be used for the menu `style' field or item `style' field. Either the numeric value or the name (without quotes) can be used.
Don't add anything special.
Solid fill with `backcolor', adding any fade effects parameterized in `fadeClamp', `fadeCycle', `fadeAmount'.
See also: `itemDef::backcolor', `menuDef::backcolor', `menuDef::fadeClamp', `menuDef::fadeAmount', `menuDef::fadeCycle'.
Gradient effect with `backcolor'.
Fill with shader indicated in `background'.
See also: `itemDef::background', `menuDef::background'.
Fill with team color at 33% alpha.
See also: `script::setteamcolor'.
Fill with cinematic (movie, RoQ format).
See also: `itemDef::cinematic'.
These values can be used for either the the menu `border' field or item `border' 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.
No border is drawn.
Borders are drawn along the top, bottom, left, and right edges.
Draw only along the top and bottom (horizontal) edges.
Draw only along the left and right (vertical) edges.
Draw only along the top and bottom edges with the KC (Kevin Cloud?) Gradient effect.
These values are used for the item `textstyle' field. Either the numeric or name value can be used.
Normal, solid text.
Fast blinking; roughly two cycles per second (2 Hz).
Not used.
Programmer's (mod) note: Not implemented? Slow blinking, pulsing effect; roughly two seconds per cycle (0.5 Hz).
Drop-shadow effect.
Not used.
Programmer's (mod) note: Not implemented yet. Outline effect.
Not used.
Programmer's (mod) note: Not implemented yet. Combined shadow and outline effect.
Not used.
Programmer's (mod) note: Not implemented yet. Extra shadow effect.
These values can be used for the item `feeder' 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.
List of Q3A head models used in the game. Can be texts or images.
List of names of available Q3A maps (levels) for single-player mode. Text-only.
See also: FEEDER_ALLMAPS
List of Q3A servers. Consists of the following columns:
(text)
See also: FEEDER_SERVERSTATUS, uiScript::RefreshServers
Not used.
List of all Q3A maps playable for an online game, according to gametype. Can be texts or images.
See also: FEEDER_MAPS, uiScript::loadArenas
Not used.
Programmer's (mod) note: Not implemented? Scores listing of red team. Consists of seven columns per player/line:
(text)
Not used.
Programmer's (mod) note: Not implemented? Scores listing of blue team. Consists of seven columns per player/line:
(text)
List of all players in the game. Text-only.
List of all teams in the game. Text-only.
List of available Q3A mods. Text-only.
See also: uiScript::LoadMods, uiScript::RunMod
List of available recorded demos (file names). Text-only.
See also: uiScript::LoadDemos, uiScript::RunSPDemo
Not used.
Programmer's (mod) note: Not implementd? Scoreboard listing (non-team game?) (text? mixed?)
List of all available Q3A head models. Can be text or image.
A listing showing the server's players over a remote query (out-of-game, as from server browser). Consists of the following columns:
(text)
See also: FEEDER_SERVERS, uiScript::ServerStatus, uiScript::FoundPlayerServerStatus
List of servers containing the player name for which you are searching. (text)
List of available cinematics (RoQ files). (text?) List is updated by uiScript ``LoadMovies''.
See also: uiScript::LoadMovies, uiScript::playMovie
These are the values for the menu `ownerdraw' or item `ownerdraw' field. This set of values is used in the cgame menu, aka Heads-Up Display (HUD).
ALL YOUR BASE ARE BELONG TO US.
Armor icon for the player (red or yellow), as image.
Armor value, as numeric text.
The player's head model, as 3D model.
The player's health, as numeric text.
Icon of the ammo currently being used (matched up to the weaon in hand), as image.
Ammo count, as numeric text.
Head model of the currently selected player, as 3D model.
Name as the currently selected player, as text.
Location of the currently selected player, as text.
Status (Attack, Defend, Escort, etc.) of currently selected player, as image.
Not used.
Programmer's (mod) note: Weapon wielded by currently selected player, as image.
Powerup held by currently selected player, as image.
Armor value of currently selected player, as numeric text.
Health value of currently selected player, as numeric text.
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.
Not used.
Programmer's (mod) note: Not implemented yet. Name of flag carrier, as text.
Not used.
Programmer's (mod) note: Not implemented yet. Location of flag carrier, as text.
Not used.
Programmer's (mod) note: Not implemented yet. Status of flag carrier, as image.
Not used.
Programmer's (mod) note: Not implemented yet. Weapon wielded by flag carrier, as image.
Not used.
Programmer's (mod) note: Not implemented yet. Powerup held by the flag carrier, as image.
Item currently held by player, as image.
Player's score, as numeric text.
Head model of red team member carrying the blue flag, as 3D model.
Status (Attack, Defend, Retrieve, etc.) of red team member carrying the blue flag, as image.
Name of red team member carrying the blue flag, as text.
Head model of the blue team member carrying the red flag, as image.
2D icon of the red flag's status, as image. Status is "at stand", "dropped", or "stolen".
Name of the blue team member carrying the red flag, as text.
Blue team's score, as numeric text.
Red team's score, as numeric text.
Red team's name (clan name), as text.
Blue team's name (clan name), as text.
Number of skulls collected in Harvester mode, as numeric text.
Status of the flag in one-flag mode (at stand, stolen, dropped), as image(?).
Location of player, as text.
Player's team color (e.g. for filling in a rect background color), as color.
Q3TA CTF persistent powerup held by player, as image.
Player's powerup in hand in CTF mode, as image.
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.
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.
Game type ("CTF", "One Flag", "Harvester", etc.), as text.
Player status (Attack, Defend, Escort, etc.), as image.
Not used.
Programmer's (mod) note: Not implemented yet (empty function). Probably the "You fragged ..." message, as text.
Quake III: Team Arena proximity mine message, as text.
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.
Not used.
Programmer's (mod) note: Not completed yet. All system (non-chat) messages?
Not used.
Programmer's (mod) note: Not completed yet. Global (non-team?) chat texts.
Not used.
Programmer's (mod) note: Not completed yet. Team-only chat texts.
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.
Name as text of the last player to kill you, as text.
Draw armor icon, as image. 2D image only.
Draw ammo icon for current weapon, as image. 2D image only.
Accuracy score, icon + text (e.g. "34%")
Assists score, icon + text (e.g. "12")
Defense score, icon + text (e.g. "8")
Excellents score, icon + text (e.g. "3")
Impressives score, icon + text (e.g. "2")
Perfects score, icon + text (e.g. "0")
Humiliations score, icon + text (e.g. "5")
Marquee-effect (scrolling-to-left text) of players in spectator mode, as (scrolling) text.
The Team Info Overlay display, as image + text combination.
Head model of the last player that sent a voice message, as image.
Name of the last player that sent a voice message, as text.
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.
The skulls icon, as image.
Either the frags limit or captures limit of the game, according to game type, as text.
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.
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.
Number of captures (icon + text) by player.
Specific to Weapons Factory Arena. Shows the class-specific special equipments in use, such as lasers, sentries, depots, and alarms.
Specific to Weapons Factory Arena. 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.
Specific to Weapons Factory Arena. Number of headshots (icon + text) by player.
These values can be used for the item `ownerdrawflag' field, to control the appearance of an `ownerdraw' 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 Heads-Up Display (HUD). 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.
... blue team has the red flag.
... red team has the blue flag.
... in a team-based game mode (TDM, 1CTF, 2CTF, etc.)
... in Harvester game mode only.
... in One-flag CTF game mode only.
... in Two-flag (traditional) CTF game mode only.
... in Obelisk (Overload?) game mode.
... health is critically low (<25). Default HUD uses this to make the health HUD flash on low health.
... in Single-Player game (as opposed to a networked game).
... in Tournament game mode only.
... a radio message comes in (Q3TA-style voice command/chat).
... player has the flag. This is useful for showing a special icon only when the player him/herself has the flag.
... in Networked game (as opposed to single-player or local multiplayer [bots]). The lagometer is an example of where this is meaningful.
... mine(s) has been placed (TA-style mines).
... health is OK, i.e. non-critical (>25).
... Team Info is being selected/shown (teammate is not selected).
XXX need section on selectedplayer information
... Team Info is not being selected/shown (teammate is selected).
XXX again, need section on selectedplayer
... other team has the/your flag (CTF, one-flag).
... your team as the/their flag (CTF, one-flag).
... in any non-team-based games (FFA, tournament, etc.).
... 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.
These are the values for the menu `ownerdraw' or item `ownerdraw' field. This set of values are used in the ui menu, aka "main menu" or "ESC menu".
??
Player's handicap, as text.
Player's effect (rail trail color), as slider.
Player's chosen Q3A character model (full model, as in the setup menu), as 3D model.
Player's clan name, as text.
Player's clanlogo, as image/shader.
The gametype, as text.
The map preview (that little screenshot), as image.
The bot skill level, as text. (Single-player mode only?)
The blue team name, as text.
The red team name, as text.
Blue team leader - for use in bots setup for server/network/local multiplayer game, as text.
Blue team member 2 - for use in bots setups for server/network/local multiplayer game, as text.
Blue team member 3 - for use in bots setups for server/network/local multiplayer game, as text.
Blue team member 4 - for use in bots setups for server/network/local multiplayer game, as text.
Blue team member 5 - for use in bots setups for server/network/local multiplayer game, as text.
Red team leader - for use in bots setups for server/network/local multiplayer game, as text.
Red team member 2 - for use in bots setups for server/network/local multiplayer game, as text.
Red team member 3 - for use in bots setups for server/network/local multiplayer game, as text.
Red team member 4 - for use in bots setups for server/network/local multiplayer game, as text.
Red team member 5 - for use in bots setups for server/network/local multiplayer game, as text.
Source of servers list: Local, Internet, MPlayer, Favorites, etc., as text.
The map preview (the little screenshot) on selected server, as image.
The name as text of the game-type filter on servers listing, as text.
Tier level, as text. Presumably only in single-player mode.
The opponent's model, as 3D model.
SweetnutZ explains: Some people (pro players) like to specify the model they play against, as they feel certain models are easier to see, hit, etc.
Not used.
Not used.
Not used.
Player's clan graphic, as image.
Opponent's clan graphic, as image.
Players's metal-theme clan logo, as image.
Opponent's metal-theme clan logo, as image.
Player's clan name graphic, as image.
Opponent's clan name graphic, as image.
The name of the current map in the current tier, as text.
The game type of the current map in the current tier, as text.
The name of the current net map, as text.
The contents of cvar "ui_opponentName", as text.
Not used.
Programmer's (mod) note: Not implemented? The kick-vote menu.
The name of the currently selected bot, as text.
The skill level of the currently selected bot, as text.
"Red" or "Blue" depending on which team the player is on, as text.
The crosshair, as image. Set `forecolor' to something noticeable to keep this from being invisible.
See also: `itemDef::forecolor',
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".
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 ( FEEDER_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:
Mod programmers can change the sequence and extensions used.
See also: `FEEDER_MAPS', `UI_NETMAPCINEMATIC'
The gametype on a network game, as text.
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 ( FEEDER_ALLMAPS). Acts just like UI_MAPCINEMATIC, except for the cvar and feeder sources used. (XXX: only applicable for starting server?)
See also: `FEEDER_ALLMAPS', `UI_MAPCINEMATIC'
Date of last servers listings update, as text.
Server MOTD ("Message Of The Day", which has historically devolved into actually meaning "a message you see when you connect/login"), as text.
Information about the active OpenGL rendering system, as multi-line text..
Message dependign on current status of binding a key, as text.
The RoQ movie where its name matches that of the player's team logo name (the cinematic version of the team logo), as cinematic.
The time to beat for this map in minutes and seconds, as text.
The game type of the selected game (network/multiplayer server), as text.
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 ( FEEDER_CINEMATICS).
See also: `menuDef::cinematic', `FEEDER_CINEMATICS', `FEEDER_MAPCINEMATIC', `FEEDER_NETMAPCINEMATIC'
The RoQ movie where its name matches that of the currently selected map (cinematic version of map preview), as cinematic.
The name of the current map, as text.
These values can be used for the item `ownerdrawflag' field, to control the appearance of an `ownerdraw' 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.
... 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.
... player is not the leader. This flag could be used to show a box indicating the team leader.
... on a favorite server. A favorite server is one in the "favorite servers" list.
... in any non-team-based games (FFA, tournament, etc.).
... in any team-based games (TDM, CTF, 1CTF, etc.).
... player got the newest high score. Only applicable to single-player game.
... a valid demo file exists (i.e. check if there's any demos available).
... player got the newest best time. Only applicable to single-player game.
... in a FFA (Free-For-All) game type.
... in a non-FFA game type.
... 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.
... in any non-team-based game on a network.
... player is on a not-favorite server (server is not on favorites list).
Many thanks to dementor for starting this section.
These values are used for uiScript. 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.
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: RefreshServers, itemDef::feeder, FEEDER_SERVERS
Loads a list of demos to be used with the demo feeder. This also updates the feeder source for FEEDER_DEMO.
See also: itemDef::feeder, FEEDER_DEMO, uiScript::RunSPDemo
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: itemDef::feeder, FEEDER_MODS, uiScript::RunMod
Starts playing the RoQ selected in the movies list. The movies list is any widget using a movie feeder.
See also: itemDef::feeder, FEEDER_CINEMATICS, uiScript::LoadMovies
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: getCDKey
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: uiScript::SkirmishStart
Update the Single Player menu based on latest achievements, such as after completing a [new] arena.
See also: uiScript::resetScores, uiScript::SkirmishStart
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: uiScript::glCustom
Retrieves the stored CD key from internal Quake 3 memory, and stores into 4-character pieces into cvars "cdkey1" through "cdkey4".
See also: verifyCDKey
Loads list of maps for starting server.
See also: uiScript::StartServer, uiScript::SkirmishStart, itemDef::feeder, FEEDER_ALLMAPS
Parses "gameinfo.txt" file. Also loads (single-player) best scores for each map.
See also: uiScript::resetScores
Resets best scores for each map.
See also: uiScript::loadGameInfo
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: uiScript::RefreshFilter, uiScript::ServerStatus, itemDef::feeder, FEEDER_SERVERS
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: uiScript::RefreshServers, itemDef::feeder, FEEDER_SERVERS
Plays back a demo. The demo to play is the one selected in the list that uses a demo feeder.
See also: uiScript::LoadDemos, itemDef::feeder, FEEDER_DEMOS
Load a list of movies.
See also: uiScript::playMovie, itemDef::feeder, FEEDER_CINEMATICS
Run mod selected in listbox. The mod to load is the one selected in the list using the mods feeder.
See also: uiScript::LoadMods, itemDef::feeder, FEEDER_MODS
Switch to baseq3 (the version without all the nifty new menu code).
See also: uiScript::Quit
If server list refresh is in progress, the refreshing is stopped.
See also: uiScript::RefreshServers
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: uiScript::RefreshServers, uiScript::FoundPlayerServerStatus, itemDef::feeder, FEEDER_SERVERS, FEEDER_SERVERSTATUS
Retrieves status of server. The selected server is the one selected in the list using the findplayer feeder. Updates the serverstatus feeder.
See also: uiScript::ServerStatus, itemDef::feeder, FEEDER_FINDPLAYER, FEEDER_SERVERSTATUS
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: FEEDER_FINDPLAYER
Join the game on the selected server. The server to join is the one selected in the list using the servers feeder.
See also: FEEDER_SERVERS, uiScript::RefreshServers
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: FEEDER_FINDPLAYER, uiScript::FindPlayer
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: uiScript::Leave, uiScript::Quake3
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: ITEM_TYPE_BIND
Quits from a game, but not Quake 3 entirely. Main menu is opened afterwards.
See also: uiScript::Quit, uiScript::Quake3
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: uiScript::RefreshServers, uiScript::RefreshFilter
Single-player game, go on to next round (as from the podiums display at the end of a round).
Start single-player game.
See also: uiScript::nextSkirmish
Set "Video Setting" label to "Custom" (out of "Low", "Medium", "High", "Custom").
See also: uiScript::resetDefaults
Commits the displayed bindings setup to actual binds for Quake 3.
See also: uiScript::loadControls
Retrieves key binds from Quake 3 to set up the displayed bindings.
See also: uiScript::saveControls
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.
Refresh the list of servers with the new selected filter. XXX: does this re-ping the servers?
Closes the in-game menu. The in-game menu is the menu usually bound to ESC.
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: itemDef::feeder, FEEDER_ALLMAPS
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: itemDef::feeder, FEEDER_PLAYER_LIST
Vote on gametype (FFA, TDM, CTF, etc.). (XXX: parameters?)
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: itemDef::feeder, FEEDER_TEAM_LIST
Adds a bot to the (online) game. The selected bot is the one selected in the listbox using the heads feeder.
See also: itemDef::feeder, FEEDER_HEADS
Add the currently joined server to the Favorite Servers list. (XXX: details... limits, time of saves, etc.)
Delete current server from Favorite Servers list. (XXX: same queestions as addFavorite)
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?
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.
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: uiScript::orders
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: uiScript::voiceOrdersTeam, uiScript::orders
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).
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".
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:
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.
In cookbook form:
{
loadmenu { "myhud.menu" }
loadmenu { "ui/score.menu" }
loadmenu { "ui/teamscore.menu" }
}
/set cg_hudFiles myhud.cfg
/loadhud
/set cg_hudFiles ui/hud.txt
/loadhud
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 http://www.gnu.org/copyleft/fdl.html
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.