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. the value after evaluation of the previous operator, or the value from the previous update for the first operator). If the operator contains a literal number or string, that is used as the second operand. For example:

<image>
  <x>       
    <copy> 1 </copy>  <!-- Set the current x position to 1 -->
    <add> 5 </add>  <!-- Add 5 to current x position -->
  </x>
</image>

However, Operators can instead refer to properties for the value of their second operand, using the src and trait XML attributes. This include properties of other object elements. See the attributes page for details on this syntax. An example:

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

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

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

Operator Elements may contain other operator elements as children to make more complicated formulas or for when operator precedence is needed:

<image>
  <x>
    <!-- New X = 5 + (10 / 3) -->
    <copy> 5 </copy>
    <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 has a string as its second operand the result seems to be undefined. The Copy operator is a notable exception (see below).

Described below are some of the more common Operator elements.

Copy Operator

The only unary (single-operand) operator, and the only operator that will work with string values. The <copy> operator replaces the current property value:

<text>
  <x> <!-- Set the x position to be 50 pixels -->
     <Copy> 50 </Copy>
  </x>
  <y> <!-- Set the y position to match y position of "someimage" -->
     <Copy src="someimage" trait="y" />
  </y>
  <string> <!-- Set the text content to match the "user4" property -->
     <Copy src="Me()" trait="user4" />
  </string>
</text>

Copy has a special mechanic built in for "choosing" one of several source properties:

1. Define a "custom" property for each choice with names of the form _SomeName_#, where # is an integer greater than zero.
2. Set the value of the destination property to the integer corresponding to the desired choice.
3. Use <Copy> with trait="_CustomPropertyName_"

The engine will automatically append the current integer value to the end of the requested trait name, and copy the value of the resulting property. This is extremely useful for conditional formulas, as an alternative to loads of nested Onlyif blocks. For example:

<image>
   <user0> </user0> <!-- set by script or end user to 1,2, or 3 --> 
   <_srcfile_1> MyMod\apple.dds  </_srcfile_1> <!-- Custom properties ... -->
   <_srcfile_2> MyMod\pear.dds   </_srcfile_2>
   <_srcfile_3> MyMod\banana.dds </_srcfile_3>
   <filename> 
      <copy src="me()" trait="user0" /> <!-- current value set to the integer in "user0" --> 
      <copy src="me()" trait="_srcfile_"/> <!-- which determines which custom property --> 
   </filename>                             <!-- the filename is actually copied from --> 
</image>

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.
• And - The new property value is &true; if the contents of <and> and the current property value both evaluate to &true;, and &false; if at least one of them evaluates to &false;.
• Or - The new property value is &true; if the contens of <or> or the current property value (or both) evaluates to &true;, and &false; if both of them evaluate to &false;.
• Not - The new property value is &true; if the contents of <not> evaluate to &false;, and &false; if the contents evaluate to &true;.
• 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 new property value is the lesser of the current value and the contents of <min>, i.e. the minimum of the two values. Used to put an upper limit on the value of the property.
• Max - Similar to Min. The new property value is the greater of the current value and the contents of <max>.