Category:Oblivion XML

What is XML?

XML stands for eXtensible Markup Language, a generic syntax used to encode a series of parent-child relationships. An XML document contains a hierarchy of elements, each described by a set of traits. In Oblivion, XML is used to encode the user interface. Every button, box, piece of text, and colorful widget in a menu (or the HUD) is an element in that menus XML document. And each of these elements has child elements that describe it's color, size, graphical texture, location, etc.

General Syntax

XML syntax is largely based on HTML syntax. As in HTML, an XML element is defined by opening and closing tags, which are just the type of the element enclosed by angle brackets. For example, the following xml code defines a Text element:

<text> </text>

Note that the closing tag is denoted by slash.

Anything that appears between the opening and closing tags of an element is considered the contents of that element. This might be raw text or numbers, as in the case of a Text element:

<text> This is the actual text that will be displayed </text>

Or it might be another xml element:

<image> <text> </text> </image>

In this case, the "inner" element is the child of the outer element. An element can generally have more than one child elements, and those child elements might have children of their own, and so on. This is what creates the hierarchy that is characteristic of XML.

If an element has no children, like the first example above, then the opening/closing tag syntax can be abbreviated to:

<text />

Element traits are written as name/value pairs in the opening tag:

<image traitname="traitvalue"> </image>

Traits are an essential part of XML, in that they can refine & control elements, and differentiate elements of the same type from one another. Note, though, that Oblivion only recognizes a few traits, and instead prefers to refine & control elements using child elements. See the next section, on #Oblivion XML Schema for more details.

Comments can be added to the code by enclosing them with "<!--" and "-->":

<!-- this is a comment -->

To learn more about XML syntax, read the complete specification or one of the tutorials provided by the World Wide Web Consortium.

Oblivion XML Schema

XML is a general syntax - the meaning of specific elements depends entirely on the program parsing the file.

The elements recognized by the Oblivion parser can be divided into three basic categories. "Object" Elements define actual objects in the menu, such as buttons, text, images, etc. There are only a few different kinds of object elements, but they are used repeatedly to create the complex menu structures.

"Property" Elements are always children of Object Elements, defining things like the position, color, transparency, etc. of their parent. For example, an <image> object element might have <width> and <height> elements as children, which Oblivion will use to determine the size of the displayed image.

Property elements can have literal values, written directly into the xml code. They can also contain mathematical "formulas" - for example the <width> property of an <image> element might contain a formula to make the image twice as wide as it is tall. Then, if some code in the game engine (or a mod script) changes the height of the image, the game's parser will automatically use the formula to recalculate the width. These formulas are expressed as series of "Operator" Elements - most basic mathematical operators like +, - , *, FLOOR, AND, etc. have a corresponding Operator Element.

There are a few special elements that don't fit into a category. The most common is the Include Element. It's use is similar to the include statement in C-style programming language - it allows the menu designer to copy in bits of commonly used xml code from other files.

Elements that aren't part of the Oblivion XML schema are assumed to be Property Elements. They will be parsed by the game engine, can be referred to by name from Operator elements and OBSE script functions, and may contain Operator Elements as children. It is common to break up long formulas by inventing an unrecognized element to hold intermediate values.

Oblivion only recognizes three XML Traits: "name", "src", and "trait".

<!-- An example of an 'image' Object Element --> 
<image name="MyImage">     <!-- This image has it's 'name' trait set to 'MyImage', -->
   <height> 10 </height>   <!-- and it's 'height' property set to 10 pixels. -->
   <width>                 <!-- It's width is set to twice it's height -->
      <copy src="MyImage" trait="height" /> 
      <mul> 2 </mul>       <!-- using the 'copy' and 'mul' operators -->
   </width>
</image>

Oblivion Menu Files

Menu xml data is stored in the Oblivion\Data\Menus directory. Each menu is stored in it's own file. Oblivion reloads a menu from disk every time it is opened, so changes to the file can be seen by closing and re-opening the menu - a very useful trick for editing. Note, however, that some menus are never closed (e.g. the HUD). These menus can be reloaded in game using "Reload menuname" console function.