XML:OBAN

OBAN : Object Animation	XML modding tips See HERE to start learning about XML modding. See HERE if you are searching for information on how to handle object coordinates. See HERE for some typical modding errors and their causes.
XML Mtrl << Other file types >> OBOA switch to OBD page

general information

The xml code on this page was tested with onisplit v0.9.61.0, v0.9.68.0, v0.9.82.0

with v0.9.82.0 you can also convert the OBAN into a dae file

"-extract:dae output src\OBANElevator.oni" exports the animation with a null node

in Mod Tool the null node is named "unique" and holds keyframes; it can be replicated with activesceneroot.AddModel , "unique"

"-extract:dae output src\OBANElevator.oni -geom:M3GMdebris.oni" exports animation with specified geometry

"-extract:dae output src\OBANElevator.oni -geom:camera" exports animation with camera

with v0.9.90.0 you can convert a camera dae to OBAN (a camera root is not supported)

"-create:oban output src\file.dae"

laser triggers and door files use global OBAN files
some cutscene TRAM, animated cutscene objects and camera shots/animations use level specific OBAN files
if you want to update level-specific OBANs used by ONLV, you must provide the ONLV along the OBANs in the package
trivia: also the dream lab images use OBANs
tutorial: making camera interpolations

BSL support

animate object	animate character	animate camera
env_setanim object_id oban_name	chr_animate ai_name anim_name [num_frames] [interp_frames] chr_animate script_id anim_name [num_frames] [interp_frames]	cm_anim [look\|move\|both] oban_name
animate object (range)	stop animated character	interpolat between current and new camera position
env_anim object_id [object_id]	chr_envanim_stop ai_name chr_envanim_stop script_id	cm_interpolate oban_name frame_number

XML

tag	type	description
<Flags>	flag	NormalLoop BackToBackLoop RandomStartFrame Autostart autostart animation (after an animated object is created ZAxisUp 3DSMax generated animation (has Z axis pointing up), all original door OBANs seem to have this flag
<InitialTransform>	matrix4x3	Initial position transform matrix, last 3 values are X, Y, Z position values. X, Y, Z seem to be always 0 (or nearly 0) in door OBAN files. That would make sense because of their global use.
<BaseTransform>	matrix4x3	fixed transform matrix
<FrameLength>	int16	the value must be equal to the last value plus 1 because 0 is also a frame; Oni crashes if you use a wrong value for <FrameLength>
<FrameCount>	int16	fubared animation frame length (in 1/60 seconds); does not work
<HalfStopFrame>	int16	stop frame for the first "half" of the animation; used by door animations to distinguish between open and close sequences
<KeyFrames>		holds <OBANKeyFrame> tags
<Rotation>	quaternion	object rotation, can harvested from TRAM files
<Translation>	vector3	x y z object position
	int32	elapsed time in frames, use short intervals for smooth animations

Transform matrices

Like all matrices in Oni, they are composed of 3 vectors defining rotation/scaling/shearing and a 4th vector defining a translation.

In the above table the 4 vectors are presented as rows (Direct 3D convention), although OpenGL and Oni use them as columns.

Affine transformations use a 4x4 matrix with 4 extra coefficients (in the presentation above, one would add one column on the right):

three projection transform coefficients (all of them are zero here); one final coefficient (always 1.0 for an affine transform matrix).

Alternatively, one can think of the 3x4 matrix as a 3x3 rotation/scaling matrix and a position vector

Let X=(x, y, z) be the position of a vertex in the M3GM
Let M=(m11, m21, m31; m12, m22, m32; m13, m23, m33) be the 3x3 matrix
Let R=(m14, m24, m34) be the translation vector

Then the absolute position of the vertex in the 3D world will be: X M + R

(left multiplication is used because of the row-major notation above)

Initial transform matrix: It is used to position the object in the environment before the animation is played.; When the animation is played, they use the fixed transform matrix and a quaternion.
Fixed transform matrix: This transformation is applied before the quaternion+position transform at every keyframe.; The only transform that can't be handled by the quaternion+position is scaling/mirroring.; Thus, the fixed transform is a scaling matrix most of the time (no rotation or translation).; On the hex page, the fixed transform scales the van up by 1.82 (along all three axes).
Quaternions: Those are used in Oni whenever interpolation of 3D rotation is involved (e.g., TRAM rotation); In this case, rotation at intermediate frames is interpolated from the keyframe quaternions.

code sample

[...] means other code blocks of <OBANKeyFrame>...</OBANKeyFrame>

<?xml version="1.0" encoding="utf-8"?>
<Oni>
   <OBAN id="0">
       <Flags></Flags>
       <InitialTransform>1 0 0 0 1 0 0 0 1 -225 9.3 -778.5</InitialTransform>
       <BaseTransform>-1 0 0 0 -1 0 0 0 1 0 0 0</BaseTransform>
       <FrameLength>80</FrameLength>
       <FrameCount>71</FrameCount>
       <HalfStopFrame>0</HalfStopFrame>
       <KeyFrames>
           <OBANKeyFrame>
               <Rotation>1 1 1 1</Rotation>
               <Translation>-225 9.3 -778.5</Translation>
               0
           </OBANKeyFrame>
           [...]
           <OBANKeyFrame>
               <Rotation>1 1 1 1</Rotation>
               <Translation>-217 34.5 -778.5</Translation>
               70
           </OBANKeyFrame>
       </KeyFrames>
   </OBAN>
</Oni>

data harvest from TRAM files

It's possible to create animations in Mod Tool and making TRAM files out of them. Then you can extract the quaternions and rotations with onisplit v0.9.54.0 and use them for OBANs.

HERE's an excel macro to harvest such data for camera animations.

wish list

TRAM import: dae + xml
- the dae section in the xml file should have an option to create a pelvis OBAN along with the TRAM (see XML:TRAM, RealWorld flag for details)
dae to oni creation should also allow for OBANs (currently OBANs can only be imported via level master xml file)
- this would be very useful for editing/creating single OBAN files if the rest of the level don't need changes

calculating a transform matrix

In some scenarios we need to build a new transform matrix, e.g. when making a new weapon particle emitter.

Those commands can be used to examine OniSplit's matrix calculation.

onisplit -create:oban OBAN OBAN/file.dae
onisplit -extract:xml OBAN OBAN/OBANfile.oni

Let's test some values.

xyz = 0

<InitialTransform>1 0 0 0 1 0 0 0 1 0 0 0</InitialTransform>

This doesn't tell us very much, at least we know that the last 3 value are positions.

This formula is involved in building such matrix.

So the first 9 values have to contain the rotation.

x = 60

<InitialTransform>1 0 0 0 0.5    0.8660254 0 -0.8660254 0.5    0 0 0</InitialTransform>
                  1 0 0 0 cos(x) sin(x)    0 -sin(x)    cos(x)

y = 60

<InitialTransform>0.5    0 -0.8660254 0 1 0 0.8660254 0 0.5    0 0 0</InitialTransform>
                  cos(y) 0 -sin(y)    0 1 0 sin(y)    0 cos(y)

z = 60

<InitialTransform>0.5    0.8660254 0 -0.8660254 0.5    0 0 0 1 0 0 0</InitialTransform>
                  cos(z) sin(z)    0 -sin(z)    cos(z) 0 0 0 1

x = 60; y = 40

<InitialTransform>0.7660444 0.5566704       -0.321393818   0 0.5     0.8660254 0.6427877 -0.663413942   0.3830222     0 0 0</InitialTransform>
                  cos(y)    sin(x)*sin(y)   -cos(x)*sin(y) 0 cos(x)  sin(x)    sin(y)    -sin(x)*cos(y) cos(x)*cos(y)
                  cos(y)    -sin(x)*-sin(y) -cos(x)*sin(y) 0 cos(x)  sin(x)    sin(y)    -sin(x)*cos(y) cos(x)*cos(y)

x = 60; z = 40

<InitialTransform>0.7660444 0.321393818   0.5566704       -0.6427877 0.3830222        0.663413942   0 -0.8660254  0.5    0 0 0</InitialTransform>
                  cos(z)    cos(x)*sin(z) sin(x)*sin(z)   -sin(z)    cos(x)*cos(z)    sin(x)*cos(z) 0 -sin(x)     cos(x)
                  cos(z)    cos(x)*sin(z) -sin(x)*-sin(z) -sin(z)    cos(x)*cos(z)    sin(x)*cos(z) 0 -sin(x)     cos(x)

y = 60; z = 40

<InitialTransform>0.3830222     0.6427877 -0.663413942   -0.321393818   0.7660444 0.5566704       0.8660254 0 0.5    0 0 0</InitialTransform>
                  cos(y)*cos(z) sin(z)    -sin(y)*cos(z) cos(y)*-sin(z) cos(z)    sin(y)*sin(z)   sin(y)    0 cos(y)
                  cos(x)*cos(z) sin(z)    -sin(y)*cos(z) cos(y)*-sin(z) cos(z)    -sin(y)*-sin(z) sin(y)    0 cos(y)

x = 60; y = 40; z = 20

<InitialTransform>0.719846249   0.6941092 -0.005813241 -0.262002677 0.279453874 0.9237208 0.642787635 -0.6634138 0.3830223     0 0 0</InitialTransform>
                  cos(y)*cos(z)                                                                                  cos(x)*cos(y)

By now it gets clear that the other values are made of various operations and so far it worked only because not all rotations were used (2 values at most at a time).

The complex calculations (matrix multiplications) needed for this were baked into a program by Neo, it can be downloaded HERE. Later OniSplit might be able to do this to, and/or display the values in a different way.

The source can be accessed over HERE; Mod Tool vbs adaption (rotations only) over HERE.

XML:OBAN

Contents

general information

BSL support

XML

code sample

data harvest from TRAM files

wish list

calculating a transform matrix

Navigation menu

XML:OBAN

general information

BSL support

XML

code sample

data harvest from TRAM files

wish list

calculating a transform matrix

Navigation menu

Search