XML:TRAM

TRAM : Totoro 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 TRAC << Other file types >> TRAS switch to OBD page

Export

TRAM files can be extracted A) as pure XML files or B) as a pair of XML and DAE files. For editing the actual animation, you will want to use method B. While exporting an ONCC, you might see errors such as:

Cannot find instance 'TRAMKONCOMthrow_rev'
Cannot find instance 'TRAMKONCOMthrow_rev'
Cannot find instance 'TRAMKONRIFturn_right'
Cannot find instance 'TRAMKONOKOlev18_ZomStand'
Cannot find instance 'TRAMKONOKOcorner_hide'
Cannot find instance 'TRAMKONPIScorner_hide'

Ignore them, as those files doesn't exist. (Someday we should remove them from the TRACs.)

Via command line

To export a single TRAM:

onisplit -extract:xml output_path -anim-body:path_to\TRBS_or_ONCCname.oni path_to\TRAMname.oni

To export merged TRAMs:

onisplit -extract:xml output_path -anim-merge -anim-body:path_to\TRBS_or_ONCCname.oni path_to\TRAMname1.oni  path_to\TRAMnameN.oni

Via Vago

combined extraction of dae and xml

When you start Vago, the "General" tab should be open by default. If not, click on it. Then follow these five easy steps.

Step 1: Select "ONI" as input format ("From").

Step 2: Select "XML" as output format ("To").

Step 3: Check "Another TRAM" to chose a character animation file.

Step 4: Click "Add" button to choose an ONCC file.

Step 5: Click "Convert".

Via Simple OniSplit GUI

There was a long-standing problem with combined ONCC/TRAM files where the textures would be missing.

Simple OniSplit GUI post-edits the DAE to fix missing textures. The character-related .oni files must be all in one folder. Usually the level0_Final folder does the trick.

Step 1: Drag and drop TRAM and ONCC into the big field. (One by one or simultaneously; the order doesn't matter.)

Step 2: Hit "Convert".

Editing the actual animation

You can load the DAE file into a compatible editor. So far, the community's favorite is (formerly "XSI") Mod Tool.

• For the correct Mod Tool settings, see HERE.
• Tutorial: Basics of Oni animation editing (to do)

Import

Revisited animations

http://oni.bungie.org/forum/viewtopic.php?id=1433

Condensed knowledge coming soon.

Totally new animations

Coming soon.

File structure

TRAM
  |
  +-- header: animation type, state, flags, particle, sounds, etc.
  +-- actual animation: heights, velocities, rotations
  +-- additional data: positions, throw adjustments, self-damage, attack parts, extents

List of tags, types, and flags

Use the search function of your web browser to quickly find a tag.

(work in progress)

tag	type	description
<Lookup>	parent tag
<Type>	flag	Look them up over HERE.
<AimingType>	flag	Look them up over HERE.
<FromState>	flag	Look them up over HERE. Sometimes FromState is set to "None"; in other scenarios, one FromState value is not enough. In those cases Shortcuts are used. They extend the number of states from which an animation can be played and under what conditions (replacing this atomic yes/no).
<ToState>	flag	Look them up over HERE.
<Varient>	flag	(misspelled because Oni misspells it) If unused, tag will be simply "<Varient />", such as for non-combat animations. Otherwise contains one of these values: Combat LeftPistol LeftRifle Panic RightPistol RightRifle Sprint
<FirstLevel>	int16	Number of first level in which move becomes available to the player ("0" to make it available from the start).
<Shortcuts>	parent tag
<Shortcut>	parent tag
<FromState>	flag	Look them up over HERE.
<Length>	int16
<ReplaceAtomic>	flag	yes no
<Flags>	flag	RuntimeLoaded (This bit is not stored on disk; it is used at runtime to mark that the animation was loaded.) Invulnerable While playing this animation, the player is invulnerable to melee damage and also cannot be thrown. Damage from particles and fall damage still hurt. BlockHigh While playing this animation, the player is invulnerable to high or undefined attacks within some arc in front of him. If you set this flag on an animation where the player character is spinning, then the character can still be kicked in the back or thrown. BlockLow Same as above, only it can block low or undefined attacks. Attack Animations with an attack part have this turned on. Uncertain what it does, but it may enable the melee soft-lock (where the character turns a bit during the animation to face a nearby enemy). DropWeapon If the player is armed, he drops his weapon when this animation plays. InAir Something to do with jumps; not investigated. Atomic The whole animation must be played; player cannot interrupt it once it starts. NoTurn Player cannot turn by mouse while performing this animation. AttackForward Unknown, but it looks like this is rough info for the AI about where an attack is aiming, from the player's point of view. AttackLeft Same as above. AttackRight Same as above. AttackBackward Same as above. Overlay Not a standalone animation; it just overwrites part of an already-playing one, e.g. the weapon-holstering animation. DontInterpolateVelocity Unknown, but maybe it has something to do with {x,y,z} velocities and the fact that directional jumps, for example, take information about their direction vector from the {x,z} velocity part of the TRAM (the vertical Y component is in the ONCC). ThrowSource Unknown, but throws use it. ThrowTarget Animation can hurt anybody with its attack part, including teammates. The player can even hurt himself with the TRAM's damage part (whereas a player cannot hurt himself with his own animation's attack part). It also allows two attack parts to be executed instead of only one (maybe a bug? more than two will result in a crash). If you set the first attack part to be able to deal damage from the 1st to the 100th frame of the TRAM, and the second attack part to deal damage within that range (e.g. from the 25th to the 41st frame), then the first attack part will deal damage from the 1st to the 100th frame (as usual), but even if it hits, that second attack part can the hurt enemy as well during frames 25–41. Note that the second attack part must be executed within the first attack part's active "window", otherwise it won't work. RealWorld It appears this flag was used to create a TRAM and an OBAN from one animation source. The OBAN is supposed to store pelvis rotations and positions, allowing a character to move over obstacles/gaps. The vast majority of them are used in cutscenes. DoAim Applies the aiming animation overlay (PIS/RIF) if the player has a weapon. DontAim An aiming overlay will not be applied. CanPickup Player can pick up an item during this animation if he intersects with one during his movement. Aim360 Unknown. DisableShield If the player has an active supershield (chr_super "name" 1), this forces him to disable it (chr_super "name" 0) NoAIPickup AIs are not permitted to pick up items with this animation.
<Atomic>	parent tag
<Start>	int16
<End>	int16
<Invulnerable>	parent tag
<Start>	int16
<End>	int16
<Overlay>	parent tag
<UsedBones>	flag	Simply contains "<UsedBones />" if no bones are involved, otherwise: Pelvis LeftThigh LeftCalf LeftFoot RightThigh RightCalf RightFoot Mid Chest Neck Head LeftShoulder LeftArm LeftWrist LeftFist RightShoulder RightArm RightFist
<ReplacedBones>	flag	"<ReplacedBones />" if unused, otherwise: Pelvis LeftThigh LeftCalf LeftFoot RightThigh RightCalf RightFoot Mid Chest Neck Head LeftShoulder LeftArm LeftWrist LeftFist RightShoulder RightArm RightFist
<DirectAnimations>
<Link>	link	First slot. "<Link />" if unused.
<Link>	link	Second slot. "<Link />" if unused.
<Pause>
<Hard>	int16
<Soft>	int16
<Interpolation>
<End>	int16
<Max>	int16
<FinalRotation>	float	Ending rotation in degrees.
<Direction>		None Forward Backward Left Right
<Vocalization>
<ActionFrame>
<Impact>	link	"<Impact />" if unused.
<Particles>	parent tag
<Particle>	parent tag
<Start>
<End>
<Bone>	flag
<Name>	link
<MotionBlur>	parent tag
<MotionBlur>	parent tag	sequence element
<Bones>	flag	Pelvis LeftThigh LeftCalf LeftFoot RightThigh RightCalf RightFoot Mid Chest Neck Head LeftShoulder LeftArm LeftWrist LeftFist RightShoulder RightArm RightFist
<Start>	int16
<End>	int16
<Lifetime>	int8
<Alpha>	int8
<Interval>	int8
<Footsteps>	parent tag
<Footstep>	parent tag
<Frame>	int16
<Type>	flag	Left Right
<Sounds>	parent tag	"<Sounds />" if unused.
<Sound>	parent tag
<Name>	char[32]	OSBDfile.imp.oni (don't use resource type's prefix or suffix)
<Start>	int16	The frame when the sound starts to play.
<Heights>
<Height>	float	Absolute position.
<Velocities>	parent tag
<Velocity>	2 x float	Relative positions.
<Rotations>	parent tag
<Bone>	parent tag	There are 19 bone tags, one for each body part.
<EKey>	int8 + 3 * float	For normal animations. The first value is the number of frames for which the rotation is maintained; the sum of all of these first EKey components always equals the total number of frames for the animation.
<QKey>	int8 + 4 * float	For overlay animations used by TRAS aiming screens. OniSplit v0.9.54.0 produces <QKey>s (quaternions) instead of <EKey>s (Euler rotations) for normal animations.
<PositionOffset>	parent tag	<PositionOffset> and <Positions> belong together. In the binaries, they are written in place.
<X>	int16
<Z>	int16
<Positions>	parent tag
<Position>	parent tag
<Height>	float	vertical extent
<YOffset>	float	y offset of the vertical extent from character location
<ThrowSource>	parent tag	"<ThrowSource />" if unused.
<TargetAdjustment>	parent tag
<Position>	3 * float
<Angle>	float
<Distance>	float
<TargetType>	flag	The flags are part of the animation type list. (static throws) Thrown1 = ###COMthrow_fw_p_tgt Thrown2 = ###COMthrow_fw_k_tgt Thrown3 = ###COMthrow_bk_p_tgt Thrown4 = ###COMthrow_bk_k_tgt (running throws) Thrown4 = ###COMrun_throw_fw_p_tgt Thrown6 = ###COMrun_throw_fw_p_tgt Thrown7 = ###COMrun_throw_bk_k_tgt Thrown8 = ###COMrun_throw_bk_k_tgt (not tested) (tackle throw = catching) Thrown9 = ###COMrun_tkl_fw_p_tgt (not tested) Thrown10 = ###COMrun_tkl_bk_p_tgt (pistol disarms) Thrown11 = ###PISthrow_fw_p_tgt Thrown12 = ###PISthrow_fw_k_tgt Thrown13 = ###PISthrow_bk_p_tgt (rifle disarm) Thrown14 = ###PISthrow_bk_k_tgt (not tested) Thrown15 = ###RIFthrow_fw_p_tgt Thrown16 = ###RIFthrow_bk_p_tgt Thrown17 = ###RIF? = (not tested) About the naming: "fw" = face-to-face throw "bk" = thrower is facing victim's back "throw" inside TRAM names is sometimes shortened to "thr" "p"/"k" = triggered by punch or kick button ("p" can also be omitted)
<SelfDamage>	parent tag	"<SelfDamage />" if unused.
<Damage>	parent tag	sequence element
<Points>	int16	Damage taken by character.
<Frame>	int16	Frame of the animation when damage is dealt.
<Attacks>	parent tag
<Attack>	parent tag	Only 2 attack parts per file are allowed. Normally the target gets only one hit. But if the attack frame ranges of both attack parts are overlapping, then the target can be hit by both of them.
<Start>	int16	First frame where damage can be inflicted on an opponent.
<End>	int16	Last frame where damage can be inflicted on an opponent.
<Bones>	flag	The bones which can inflict damage.
<Flags>	flag	Unblockable Low - Target of attack needs to crouch in order to block this attack. High - Blocker needs to stand; if Low and High are set then blocker can block from both standing and crouching positions. HalfDamage - Blocker receives half of the normal damage.
<Knockback>	float	Target gets "knockback"ed by this amount.
<HitPoints>	int16	Damage points inflicted by attack.
<HitType>	flag	Animation type for opponent's animation when the attack isn't blocked.
<HitLength>	int16	Number of frames for how long the target should remain in his "hit" animation state when he gets hit.
<StunLength>	int16	Number in frames for how long the target should remain in his blocking animation when he blocks the attack.
<StaggerLength>	int16	Number of frames for how long the target should perform his "stagger" animation after a successful block.
<Extents>	parent tag	Explained below. Automatically calculated by OniSplit if there's a DAE file referenced in XML.
<Extent>	parent tag	One tag per frame.
<Angle>	float	In degrees.
<Length>	float
<MinY>	float
<MaxY>	float
<AttackRing>	parent tag	Always contains 36 <Length> tags, explained below. Automatically calculated by OniSplit if there's a DAE file referenced in the XML. (AttackRing was formerly known as "horizontal extents" in older versions of OniSplit.)
<Length>	float	Horizontal extents, explained below. They create a "danger zone" around the attacker so that the AI has a chance to dodge an attack.

Extents and XML

Ever wondered how the AI can recognize incoming attacks and block or dodge them? Extents (found by geyser and fully uncovered by Neo) are the key. Imagine the character looked at from above, and visualize a circle with this character being at the center of the circle. Now divide this circle into 10° segments, and those are the 36 units of horizontal extents (that is, the lateral reach of the attack). The 0° point is directly in front of the character and 180° is behind the character. The segments run clockwise around the character. So the first Extent tag is the horizontal reach on the 0° line, the second tag is for the line 10° clockwise, and so on. Note that a frontal attack like a simple kick could hit a target not only if he's standing at 0° (directly in front), but also at 10° or 20° to the right, and also at 340° and 350° (a bit to the left). When setting these manually, you should guess the inner and outer ranges of the reach of the attacker's bones that have damage attached to them. Test these values with an AI that blocks often. If you did it right, your attack will often be blocked, but if the extent length is too high, the AIs will react when too far from you, which does not look good.

There are two types of extents:

• <Extents> stores this info:

<Angle> at which this extent radiates from the character.

<Length> of this extent.

<MinY> minimal height of this extent.

<MaxY> maximum height of this extent.

Length, MinY and MaxY serve to create an invisible area in space which is "dangerous to be in". If an AI intersects with this area and notices it (refer to the Notice field in MELE), it will attempt to block or dodge according to its modifiers in its MELE profile (again, see the MELE page).

The number of <Extent>s is equal to the number of attack frames: <End> minus <Start> plus one (because start frame counts too). For example, for TRAMKONCOMkick_low1: <End>30</End> minus <Start>22</Start> plus one = 9 <Extent>s.

These extents are pretty impossible to guess, so leave them alone until Neo comes up with extent computation (probably from attack bones and bone rotations). However, always add at least one set of component tags, because those Length, MinY and MaxY components will be taken as the longest extent, the highest Y value, and the lowest Y value. Without those, a character won't react to this attack.

• <HorizontalExtents> stores this info:

36 fields (exactly 36, otherwise it won't compile back into a .oni file), which correspond to areas in 10° intervals around the character as described above.

Adding colorful trails

Open the XML-accompanied TRAM, search for the "Particles" tag, and insert your markup.

First example: TRAMSTRCOMcomb_p_p.xml

       <Particles>
           <Particle>
               <StartFrame>0</StartFrame>
               <EndFrame>12</EndFrame>
               <Bone>LeftFist</Bone>
               <Name>contrail</Name>
           </Particle>
       </Particles>

"contrail" is looked up by the character class (ONCC) that emits the actual particle; here it is "h2h_strtrail_e01".

This second example is about creating two different contrails in a TRAM at the same time. The animation is "TRAMSTRCOMpunch_heavy.xml".

       <Particles>
           <Particle>
               <Start>0</Start>
               <End>54</End>
               <Bone>RightWrist</Bone>
               <Name>contrail</Name>
           </Particle>
           <Particle>
               <Start>0</Start>
               <End>54</End>
               <Bone>LeftWrist</Bone>
               <Name>contrail_2</Name>
           </Particle>
       </Particles>

Note that you need to register the second contrail in the ONCC as well. Using your own contrail particle is also possible; just insert its name between the <Type> tags.

           <ONCPParticle>
               <Name>contrail</Name>
               <Type>h2h_strtrail_e01</Type>
               <BodyPart>-1</BodyPart>
           </ONCPParticle>
           <ONCPParticle>
               <Name>contrail_2</Name>
               <Type>h2h_murtrail_e01</Type>
               <BodyPart>-1</BodyPart>
           </ONCPParticle>

Adding extents to an existing animation

Let's say that you want to convert a non-attack animation to a damage-dealing animation. Non-attack TRAMs do not have extents information used to notify the AIs about incoming attacks, so how do you generate this information from the animation?

1. Export the animation to XML with a body attached. If you extract using just "-extract:xml dest_folder TRAMsomething.oni", you'll get the 3D animation data inside the XML (namely, the tags Heights, Velocities, Rotations, PositionOffset, and Positions; for an attack animation, you'll also get Attacks and AttackRing, and inside Attacks' elements, each Attack element will have Extents at the end of it).

However, if you extract this same animation using "-extract:xml dest_folder TRAMsomething.oni -anim-body ONCCtramuser.oni", the animation data will be placed in a DAE file along with the character model geometry. Be sure to pick a body with a representative size for the character classes that will actually use this TRAM, because the extents will be calculated from it. The XML file will be very short without the 3D data in it. This is how we want the non-attack TRAM to look. We do not know the extents information that should go in Extents or AttackRing, so we just want to add the part that distinguishes a DAE-extracted attack TRAM XML from a DAE-extracted non-attack TRAM XML. That part is the Attacks section, without the Extents under each Attack.

2. First, consider whether the TRAM should have something added to its Flags section, like Attack or ThrowTarget.

3. Now add to the XML of the non-attack TRAM data in the following format (after the <SelfDamage /> section, typically):

       <Attacks>
           <Attack>
               <Start>1</Start>
               <End>10</End>
               <Bones>RightWrist RightFist</Bones>
               <Flags />
               <Knockback>4</Knockback>
               <HitPoints>10</HitPoints>
               <HitType>KnockdownHead</HitType>
               <HitLength>5</HitLength>
               <StunLength>8</StunLength>
               <StaggerLength>0</StaggerLength>
           </Attack>
       </Attacks>

Do not add an AttackRing section after Attacks.

4. Import this with "-create dest_folder TRAMsomething.xml". The Extents sections and the AttackRing will be calculated by OniSplit from the attached DAE.

5. If you need this information for a patch mod, run "-extract:xml" on the TRAMsomething.oni you've created, without using "-anim-body". Now you can copy the Extents and AttackRing data to your XML patch. For an example of how the patch should look, see the Domino Knockdowns mod.

Throws

Throw target animations are registered in the TRAC of the throw initiator (AKA the throw source). Target animations are forced onto the other character, removing the need to have that animation in the target's TRAC. Throw target (TRAM*tgt) animations can cover only up to 256 (0-255) frames.

Forward throws

Scenario: you load two characters into Mod Tool and rotate (+/-180°) the throw target character because you need them to stand face to face as you work on an animation. When you are done animating, the target animation would need to be reversed again. This means multiplying the velocities by -1; the rotation also needs correcting. So it looks like you need *(-1) for the x rotation and -/+180° (depending on your initial change) for the y rotation.

Excel macro to tweak forward throws

• Here's the macro (for all TRAMs except overlays). Demo vid here. Usage:
• Put your files into the "input_and_output" folder.
• Disable macro security if you don't want to have to click on the macro options button every time.
• Close other worksheets before you run the macro.
• If you are not afraid of VBA code, you can enter the dev environment by hitting Alt+F11. If you want to extend the attack library with more screenshots and settings, search for: "LibraryThrows", " LibraryAttack", "Picture", and "CBAttackHelp.AddItem".

Run animations

Here's a breakdown of the Striker's run animations, meant as an illustration for what would be needed to make new run TRAMs.

Run cancel:

• STRIKEidle1 / another idle animation
• STRIKErun1stepa
• STRIKErun1stepb
• STRIKEidle1 / another idle animation

Run – a minimal cycle:

• STRIKEidle1 / another idle animation
• STRIKErun1stepa
• STRIKErunstart
• STRIKErun_rt
• STRIKErun_lt (optional)
• STRIKErunstop
• STRIKEidle1 / another idle animation

Follow the images below from right to left.

• 

  STRIKErunstop

• 

  STRIKErun_lt

• 

  STRIKErun_rt

• 

  STRIKErunstart

• 

  STRIKErun1stepa

List of unused animations

Here are all the known unused animations. These could be reintegrated/recycled/whatever....

From the original game

• KONOKOconsole_punch: what the name says (the engine can use that animation depending on the console's configuration, see CONS)
• KONOKOlev3_intro: looks like she was placing something (bomb?) and then running away
• KONOKOlev4_undress: from an aborted clothes-changing cutscene
• KONOKOlev16_bomb: planting a bomb
• KONCOMsuper_kick: now used in OTA scripts (mod) as spawn event
• KONCOMsuper_punch: KONCOMpunch_heavy but without the shouted attack name, has HalfDamage flag, and does 10 less damage in its first attack part
• COMPISidle_special1: Comguy checking environment and his gun (meant for a feature that would visually depict an elevation in the AI's level of alertness after, say, hearing a noise)
• STRPISidle_special1: Striker checking his his gun and communicating with an ally (another unused alertness animation)
• THUGlev1_direct: Thug probably directing a truck driver

From modders

The following files are available in DAE (and maybe .oni format).

charA and charB performing stun animations

• Fury double flip (.dae)
• Konoko enters prone mode (.dae + .oni)
• Konoko leaves prone mode (.dae)
  • These are artifacts of Paradox's work on his Prone Mode mod.
• Female stun (throw pair) (.dae)
  • Needs to be slowed down by adding more frames.

Speeding up existing animations

s10k has created a XmlTools patch that allow the speedup of any existing TRAM. More information and download here.