Operator Element

Overview

Operator Elements are a subgroup of the elements in the Oblivion XML schema, always found as children of Property Elements. They are used to create mathematical formulas, which the game engine evaluates in real time to get the property value.

There is pretty much an Operator Element for every basic mathematical operator - at least every operator that takes two operands. The first operand is always the current value of the property (i.e. whatever the value was the previous frame). If the operator contains a literal number or string, that is used as the second operand. For example:

<image>
  <x>       
    <add> 1 </add>  <!-- Add 1 to current x position -->
  </x>
</image>

However, Operators can instead refer to other properties for the value of their second operand, or even properties of other Object elements. For example:

<image name="example_image>
  <y> 5 </y>  
  <x>  <!--Add the value of the y coordinate (5) to the current x position -->
    <add src="example_image" trait="y"/> 
  </x>
</image>

Here src and trait are XML traits indicating the Object & Property, respectively, to get the value from. Don't be confused: The XML trait called trait here actually refers to a Property Element, not another XML trait. It seems Bethesda used the word differently than the XML community at large.

A property element may contain more than one Operator, evaluating them in order:

<image>
  <x>
    <!-- New X = (X + 10) * 2 -->
    <add> 10 </add>
    <mult> 2 </mult> 
  </x>
</image>

Operator Elements may contain other operator elements as children to make more complicated formulas:

<image>
  <x>
    <!-- New X = X + (10 / 3) -->
    <add> 
      <copy> 10 </copy>
      <div> 3 </div>
    </add>
  </x>
</image>

Note that numerical operators (which is most of them) aren't intended for use with string-type properties. If a numerical operator is used in a string-type property or specifies a string as its second operand the result seems to be undefined. The Copy operator, however, can still be used with strings.

Described below are some of the more common Operator elements.

Copy Operator

The only unary (single-operand) operator. The <copy> operator replaces the current property value with its contents:

<image>
  <x> <!-- Set the new x position to be 50 pixels -->
     <Copy> 50 </Copy>
  </x>
  <y> <!-- Set the new y position to match y position of "otherimage" -->
     <Copy src="otherimage" trait="y" />
  </y>
</image>

There is a special mechanic built in for copying values from 'custom' property elements that have types of the form _CustomPropertyName_#, where # is an integer greater than zero. In this case, it is possible to set the 'trait' to just _CustomPropertyName_ and the engine will automatically append the current value of the property to the end. For example:

<image>
   <user0> </user0> <!-- set by script or end user to 1,2, or 3 --> 
   <_srcfile_1> MyMod\apple.dds  </_srcfile_1>
   <_srcfile_2> MyMod\pear.dds   </_srcfile_2>
   <_srcfile_3> MyMod\banana.dds </_srcfile_3>
   <filename> 
      <copy src="me()" trait="user0" /> <!-- current value set to user selection --> 
      <copy src="me()" trait="_srcfile_"/> <!-- which then determines which file --> 
   </filename>                             <!-- path is actually copied --> 
</image>

As implied by the example above, the Copy operator is the only operator that will work with string values, both as literals and copied from other string-type properties.

Algebraic Operators

Add - Addition
Sub - Subtraction
Mult/Mul - Multiplication (different elements, but both perform exactly the same function)
Div - Floating point division
Mod - Modulus (the remainder of the current value / contents of <mod>)
Rand - Random number (between 0 and the contents of <rand>).

Boolean Operators

With these operators the numerical value of 'true' is encoded as the XML entity "&true;", or the literal number 2. The standard numerical value of 'false' is "&false;", or 1, but any number other than 2 will be considered false.

Onlyif - The new property value is the current property value if the contents of <onlyif> evaluate to &true;, and zero if the contents evaluate to &false;.
Onlyifnot - Similar to <onlyif>, but with the opposite pairing.
Lt - The new property value is &true; if the current value is less than the contents of <lt>, and &false; otherwise.
Lte - Similar to <lt>, but the current value can be lesser than or equal to the contents of <lte>.
Gt - Similar to <lt>, but the current value must be greater than the contents of <gt>.
Gte - Similar to <gt>, but the current value can be greater than or equal to the contents of <gte>.
Eq - The new property value is &true; if the current value is equal to the contents of <eq>, and &false; otherwise.
Neq - Similar to <eq>, but the current value must be unequal to the contents of <neq>.

Comparative Operators

Min - The current value greater than the value of <min>, it is set to that value.
Max - If current value is less than the value of <max>, it is set to that value.