Oblivion XML Reference/Traits

Traits, known unofficially as properties, are specified as child elements of a tile, and their contents provide their values. If a tile has a trait specified more than once, the last definition is the one that will be used.

Due to a bug in Oblivion’s XML parser, all of a tile’s traits must precede its child tiles, or properties will malfunction unpredictably. (It appears to be possible to redefine a trait after defining child tiles if the trait was first defined before all child tiles, however.) The MenuQue mod purports to correct this bug.

Trait elements can only contain raw number values, raw string values, or operator child elements. Operators can be used to compute a trait's value dynamically.

Common

childcount

child_count

The executable sets every tile’s childcount trait to the number of direct child tiles.

id

The executable is hardcoded to provide input and values to tiles with specific ids within each menu, and occasionally to read values from them as well. Generally speaking, only one tile within a menu can use a given id, and all needed ids must be used, but there are exceptions.

To give an example of how this works: in the HUD (hud_main_menu.xml), the tile with id 1 will have its user0 trait set to the player’s current health as a percentage value, between 0 and 1. In the inventory menu (inventory_menu.xml), the tile with id 1 doesn’t receive any values, but clicking on it (if its target trait is true) will cause the menu to switch to the “All Items” tab.

user0

…

user20

These traits have context-dependent meanings, and are generally used to send/receive values to/from the executable on a per-menu basis.

_anyNamePrefixedWithAnUnderscore

Custom traits that can be used to hold whatever values you like. These can also be used to pass arguments to prefabs (since prefabs are spliced at run-time).

Box model

clips

If this trait is set to true and the tile has an ancestor whose clipwindow trait is true, then any part of this tile that lies outside of that ancestor’s bounds will be hidden.

Note that like visible, clips defaults to 0 (which is treated as false) rather than &false;; and unlike visible, clips does not propagate to descendant tiles. This means that if you want tiles to blindly copy the clips state of some ancestor (e.g. tiles in a prefab), you must use <clips><copy src=”parent()” trait=”clips” /><eq>&true;</eq></clips>.

Disassembly of the executable confirms that this trait is only valid for Image, Rect, and Text tiles.

clipwindow

If this trait is set to a non-zero value (i.e. &true; or &false;), then descendant tiles will be clipped if their clips trait is also true and if they lie outside of this tile’s bounds: that is, the descendants in question will be partially or fully hidden.

Disassembly of the executable confirms that this trait is only processed on Image and Rect tiles.

depth

The depth of the element: tiles with a higher depth will be drawn on top of tiles with a lower depth, and they can also block mouse interactions with target-able tiles beneath them. Note that this value is relative to the parent tile’s depth.

Menus are separated by two depth units. Specifically, when a menu is opened, its depth is set to 2.0 plus the highest depth among all other menus. (Whether “highest depth” refers to each menu’s own depth or the highest depth of any contained tile is unclear, and needs further investigation.)

Oblivion’s menus are rendered in 3D, and each unit of menu depth translates to -0.008 3D units. This means that depth values will offset tiles, even if only by unnoticeably small sub-pixel amounts in typical situations. Very large depth values (in excess of 1000) will start to cause noticeable deviations in a tile’s apparent position. Depth values in excess of 40000 will noticeably affect the menu cursor (presumably because Oblivion tries to keep the cursor tile’s own depth in front of everything else), enlarging and displacing it; the cursor will remain affected until the offending menu is closed and any menu is (re)opened.

depth3d

Oblivion renders its UI in 3D; most tiles are just flat shapes in a 3D scene. A NIF tile renders another 3D scene (defined in a NIF file) directly into the UI, where the tile would go. By default, the scene’s origin (0, 0, 0) is aligned with the tile’s own coordinates in the scene. The depth3d trait offsets the scene’s depth axis from the tile’s position. The value of the depth3d trait is a measurement in 3D units, not depth units; one depth unit represents -0.008 3D units. A depth3d of 500 produces exactly the same position and size change (due to perspective) as a depth of 62500.

listclip

This trait overrides visible. If set to &true;, the tile will be hidden even if its visible trait is &true;. Presumably it’s set by the executable in some cases in order to forcibly hide generated list items if they lie outside of their list’s visible region.

Note that input-handling and keyboard navigation code pays attention to visible, but not to listclip. Tiles hidden with listclip can still be targets for keyboard navigation.

locus

Boolean. Tiles are positioned relative to the nearest ancestor tile whose locus trait is true. Such an ancestor shall be referred to in this document as the locus ancestor.

This trait is forced to &true; for all NIF tiles that specify valid 3D models.

height

width

The dimensions of the tile in pixels.

Note that these traits cannot be set on Text tiles; instead, the executable sets them to the size of the displayed text if the text is visible.

x

The position of the tile’s left edge, relative to the left edge of the tile’s locus ancestor.

y

The position of the tile’s top edge, relative to the top edge of the tile’s locus ancestor.

visible

A Boolean trait indicating whether the tile will be displayed. Note that hidden tiles cannot be clicked or receive mouseover status even if their target trait is true. If a tile is set to not be visible, then all of its descendant tiles will also be hidden.

Note that this trait defaults to 0, and 0 is treated as unspecified (i.e. true). In practice, this means that onlyif and similar operators treat an unspecified visible trait as false even though it behaves as true.

When working with tiles that have ids, it’s somewhat common for the executable to force visible to a particular value even when there’s no real need or reason to do so.

Color

All tiles with graphical content are rendered as 3D polygons. The color traits modify the vertex colors for these polygons: they can be used to dim a color component on a rendered texture (including text), but do not affect child or descendant tiles.

alpha

A numeric value between 0 and 255, inclusive, indicating how opaque the tile is. Note that even fully transparent tiles can still respond to mouse clicks and other interactions if their target trait is true.

Note that if you try to query the alpha of a trait that doesn’t define alpha, you will retrieve 0, not 255. This means that child tiles that try to "inherit" their parent’s unset alpha via <alpha><copy src="parent()" trait="alpha" /></alpha> will become fully transparent even though the parent is opaque.

Note that in some cases, setting an alpha on a Rect can cause the Rect to actually become a visible, solid box of color – typically white, if no other color traits have been set. The exact circumstances needed to trigger this behavior are not known; it only occurs if something causes the Rect to generate a rendered 3D node, but although that’s clearly intended to happen, Oblivion’s code doesn’t appear to reliably ensure that it happens.

red

green

blue

A numeric value between 0 and 255, inclusive.

For text tiles, these values indicate the color of the text: font files define typefaces in white, and the RGB components of each pixel are reduced if they are greater than these values.

For image tiles, these values work similarly, capping each color channel in the rendered texture. The exact mechanics here are unclear. In theory, an all-white texture with these values set to 140 should present with a color (140, 140, 140). In practice, it seems that one must use 0.55 (140 / 255).

Image

cropX

cropY

cropoffsetX

cropoffsetY

The texture file will be cropped from the left and top edges by these amounts of pixels, such that the pixel at (cropX, cropY) in the texture is aligned at the top-left corner of the tile. Note that this value is applied after the zoom trait, so you should pre-multiply it by the zoom trait (if it’s not -1) for consistent results.

The “crop offset” traits are just aliases of the “crop” traits.

filename

The path to the texture file that the image tile should display. This path is case-sensitive (unless MenuQue is installed) and is relative to Data\Textures; however, textures outside of Data\Textures\Menus will not work.

The game will automatically choose between textures in Data\Textures\Menus, Data\Textures\Menus80, and Data\Textures\Menus50 depending on the texture quality that the user has selected. If the game can’t find one of your textures (because it’s not in the folder the game is looking in), corrupted graphics will appear in its place.

filewidth

fileheight

These traits are computed by the game engine and set on your tiles automatically. They indicate the width and height of the loaded texture file, in pixels, after zoom has been applied but before any cropping has been applied.

Note that if the filename trait has been copied from “too far away,” the filewidth and fileheight traits will not be updated properly when the image is loaded; this bug has been observed to lead to too small a fileheight (8 in testing, when dealing with a 16px-tall image). The precise operational definition of “too far away” has yet to be determined.

tile

A Boolean trait indicating whether the texture should be tiled across the tile (oh dear, that’s confusing), if the tile’s width and height exceed (zoom × filewidth - cropX) or (zoom × fileheight - cropY), respectively. Tiling is based on the dimensions of the texture; the game engine will not check and “compensate” for fully-transparent areas at the texture’s edges.

The engine behaves differently if this trait’s value is lower than -1.0 versus if it’s higher or equal, but that behavior hasn't been decoded yet.

zoom

The texture file will be scaled by (zoom ÷ 100) before being displayed within the tile. If the zoom value is -1, the texture file will be stretched or shrunk to fill the tile’s width and height (non-uniform scaling is supported in this case).

This trait is valid on one specific Text tile in the vanilla MainMenu, but is not valid on other Text tiles. Presumably the MainMenu class tampers with that one tile’s rendered NiNode.

Menu

class

Associates the menu’s root tile with a specific internal class, identified numerically. All vanilla menus have XML entities defined and available for use as shortcuts.

disablefade

Boolean. If set to true, it appears to prevent the menu from being faded in some or all cases; it will simply appear or disappear instead.

explorefade

This value is sometimes(?) used in place of menufade, if menufade is set to a negative or zero value. The precise difference is not clear; explorefade is used even outside of gameplay settings (e.g. on the options menus, when they’re opened from the game’s main menu).

menufade

Time in seconds that it takes for the menu to fade in or out.

stackingtype

To be documented.

NIF

animation

The name of an animation (specifically a NiControllerSequence) within the NIF file.

To be determined: if this computes to a non-existent animation, does the NIF tile simply display without animating?

filename

The filename of the NIF file to display. If the path does not start with Data\ (the use of a backslash matters), then it is relative to Data\Meshes\Menus.

Text

font

An integer between 1 and 5 indicating which font to use. The Oblivion.ini file associates each number with a font file. Numbers outside of this range will cause crashes.

isHTML

If this value is non-zero, the string is parsed as HTML before being displayed. However, this only works when the tile’s string is supplied by the executable. HTML tags placed inside of the string trait are misinterpreted (as if they were invalid operators) and cause the value to compute to zero or blank; escaping these tags with the < and &rt; entities doesn’t work either, because the parser doesn't understand those entities.

justify

Species how the text is positioned relative to the element’s X-coordinate. The values &left;, &center;, and &right; indicate which edge of the text will align with the X-coordinate.

pagecount

HTML-formatted text can be broken into “pages” using the HR element. In these cases, the executable automatically sets the pagecount trait to the number of pages available.

pagenum

HTML-formatted text can be broken into “pages” using the HR element. In these cases, this trait indicates which zero-indexed “page” to display.

string

The text that the tile will display. Raw numeric values are supported, as are numeric values copied from other traits; however, displayed floats will be rounded down to the nearest whole number (they're stringified using the format string %.0f).

wraplimit

If word-wrapping is enabled on the tile, its text will be limited to this many lines, and extra lines of text will not be displayed.

wraplines

To be determined. Based on its usage in vanilla, it appears to be an alias for wraplimit.

wrapwidth

If this trait is set, the text in the tile will word-wrap to avoid exceeding this width in pixels.

When it comes time to render text, this value is rounded down to the nearest integer. If it is lower than 1, then the (normalized) width of the screen is used instead.

Executable-only

These tag IDs do not have defined names, and therefore cannot be used in Oblivion XML. The tag IDs are used directly by Oblivion’s internals, so OBSE plug-in authors wishing to add new traits should avoid using them.

0x1771

Used on the menu root (screen()). It is only ever set to the ID of one of the “big four” menus; it is initialized to 0x3EB (the ID of StatsMenu) when the menu root is created. It may refer to the current "Big Four" menu being displayed, but this is unverified.

0x1772

Boolean. Set on menus’ root tiles in some cases. Purpose unknown. It gets set to true when a menu is closing (and some menus will even do this multiple times redundantly).

These traits are set on tiles that only the executable is allowed to directly read or modify:

user0

Set on the menu root (screen()). Boolean. Related to debugging and the console. Purpose unknown.

Unused

Disassembly of the executable confirms that these traits are considered valid, but are never actually used by the executable.

clickedfunc

linecount

repeathorizontal

repeatvertical

returnvalue

The executable registers these traits, but nothing in the executable ever actually uses them or acts on them.