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 combined B) as xml and dae files.

For editing the actual animation you will want to use method B.

While doing the export with 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, those files doesn't exist.

(Someday we should remove them from TRAC.)

Via command line

for single file export

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

for merged file export

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

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

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

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

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

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

Step 5: Click on "Convert".

Via Simple OniSplit GUI

There was a long standing problem with ONCC-TRAM-combined files whereby the textures will be missing.
With an older method you couldn't export non-native TRAM which meant to the TRAM had to be registered in the TRAC the ONCC is using.

Simple OniSplit GUI post-edits the dae to fix the missing textures. The character related oni files must be all in one folder. Usually 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 an compatible editor. So far the community's favorite is Mod Tool.

• For correct Mod Tool settings look HERE
• Tutorial: basics of Oni animation editing (todo)

Import

Revisited animations

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

Condensed knowledge coming soon.

Total 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, selfdamage, 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. Somtimes FromState is set to None; in another scenarios one FromState possibility is not enough. In those cases Shortcuts are used. They extent the number from what state the animation can be played and under what conditions (replace atomic yes/no).
<ToState>	flag	Look them up over HERE.
<Varient>	flag	"<Varient />" if unused. E.g. that's the case for non-combat animations. Combat LeftPistol LeftRifle Panic RightPistol RightRifle Sprint
<FirstLevel>	int16
<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 animation related, it is used at runtime to mark that the animation was loaded) Invulnerable while playing this animation user is invulnerable to melee damage AND cannot be thrown, PAR3/height still hurts him BlockHigh if set then while playing this animation user can block high or undefined attacks within some arc which is before him, so if you set this to some animation where user spins, then he can still be legaly kicked to the @$$ and he can be thrown BlockLow same as before only it can block low or undefined attacks Attack animations with attack part have it, unknown what it does, IMO it turns on soft lock (characters turns with animation a bit in order to hit nearby enemy), but didn't checked DropWeapon if user is armed, he drops weapon when he plays this animation InAir something with jumps, didn't checked Atomic whole animation must be played, user cannot interrupt it once it starts NoTurn cannot turn by mouse while performing this animation AttackForward unknown, looks like this is rough info for AI2 about where attack aims from user's point of view -Loser AttackLeft same as above AttackRight same as above AttackBackward Overlay these are not standalone animations, they just overwrite part of already playing one, for example holstering weapon is such an animation DontInterpolateVelocity unknown, but maybe it has something to do with X,Y,Z velocities and fact that for example directional jumps take info about direction vector from X-Z velocity part of TRAM (Y vector is in ONCC) ThrowSource unknown, throws use it ThrowTarget if set, then animation can hurt anybody, with its attack part, including teammates. User of TRAM can even hurt himself with "damage part" (user cannot hurt himself with own attack parts). It also allows two (try more, get crash ^_^) attack parts to be executed instead of only one (maybe bug?). -If you set first attack part to be able to deal damage from 1st to 100th frame of TRAM, and second attack part to deal damage within that limit (e.g. from 25th to 41st frame, it can be again from 1 to 100), than first attack part an hurt from 1st to 100th (as usual), but even if it hits, that second one attack part (25th to 41st) can hurt enemy as well during "its lifetime". So two attack parts are allowed to execute. Note that second attack part MUST be executed while first attack part has active "window", otherwise it won't work. RealWorld It appears this flag was used to create TRAM and OBAN from one animation source. The OBAN is supposed to store pelvis rotations and positions because that way a character can move over obstacles/gaps. The very most of them are used in cutscenes. DoAim forces aim animation (PIS/RIF) if user has weapon (used PIS/RIF animation and prone) DontAim forces not to aim CanPickup can pickup items in this animations, not like it plays pickup one, but like it "takes" the item if you have this animation on and you collide with item. Aim360 unknown DisableShield if user had active supershield (chr_super "name" 1), this forces him to disable it (chr_super "name" 0) -Loser NoAIPickup AI2 are not permitted to pick up items with this animations
<Atomic>	parent tag
<Start>	int16
<End>	int16
<Invulnerable>	parent tag
<Start>	int16
<End>	int16
<Overlay>	parent tag
<UsedBones>	flag	"<UsedBones />" if unsued. Pelvis LeftThigh LeftCalf LeftFoot RightThigh RightCalf RightFoot Mid Chest Neck Head LeftShoulder LeftArm LeftWrist LeftFist RightShoulder RightArm RightFist
<ReplacedBones>	flag	"<ReplacedBones />" if unused. 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	final rotation in degrees
<Direction>		None Forward Backward Left Right
<Vocalization>
<ActionFrame>
<Impact>	link	"<Impact />" if unsued.
<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 file prefix/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 specifies the frames number for which the rotation applies, the sum of all of these first numbers for all the EKey elements always equals to the total number of frames for the animation.
<QKey>	int8 + 4 * float	for overlay animations used by TRAS onisplit v0.9.54.0 produces <QKeys> (quaternions) instead of (euler rotations) <EKey> for normal animations
<PositionOffset>	parent tag	<PositionOffset> and <Positions> belong together. In the binaries they are written in the 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 are sometimes shortened with "thr" "p" can also be missing
<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 frames 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 to an opponent.
<End>	int16	Last frame where damage can be inflicted to an opponent.
<Bones>	flag	Set here the bones that can inflict damage.
<Flags>	flag	Unblockable Low - blocker needs to crouch High - blocker needs to stand; if Low and High are set then blocker can block from stand and crouch HalfDamage - the blocker gets half of the damage
<Knockback>	float	Target gets knockbacked by this amount.
<HitPoints>	int16	damage points
<HitType>	flag	Animation type for opponent's animation when attack isn't blocked.
<HitLength>	int16	Number of frames for how long should blocking char remain in hit anim when he gots hit.
<StunLength>	int16	Number in frames for how long should blocking char remain in blocking animation.
<StaggerLength>	int16	Number of frames for how long should blocking char perform stagger anim after sucessful block.
<Extents>	parent tag	Gets calculated by onisplit if there's a dae file referenced in xml.
<Extent>	parent tag	One tag per frame. In numbers: attack end - attack start + 1. (E.g. start=5; end=6; it makes 2 involved frames.)
<Angle>	float	In degree.
<Length>	float
<MinY>	float
<MaxY>	float
<AttackRing>	parent tag	Contains always 36 <Length> tags, no more, no less. Gets calculated by onisplit if there's a dae file referenced in xml. (The AttackRing was formerly know as horizontal extents.)
<Length>	float	Horizontal extents in 10° intervals. They make a zone of danger so the AI knows that the animation is harmful there. (It give them the chance to dogde an attack.)

Extents and XML

Ever wondered how comes Artificial Intelligence can recognize incoming attack and block or dodge? Extents ( found out by Geyser and fully uncovered by Neo ) are the key.

There are two types of extents -

• <Extents>, its packages store this info:

<Angle> at which is this extent radiated from character. 0° is in front of character, 180° is in the back

<Length> of this extent,

<MinY> minimal height of this extent

<MaxY> maximal height of this extent

Length, MinY and MaxY serve for creating invisible area in space which is "dangerous to be in". If AI collides and notices it (refer to notice field in MELE), it will attempt to block or dodge according to its modifiers in given MELE profile. Again, see fields in MELE.

Number of <Extent> is equal to attack frames: <End> minus <Start> plus one (because start frame counts too).

(e.g. TRAMKONCOMkick_low1: <End>30</End> minus <Start>22</Start> plus one = nine <Extent>.)

These extents are pretty impossible to guess, so leave them until Neo comes up with extent computation ( probably from attack bones and bonetrack rotations ).

BUT

Always add at least one package, because its Length, MinY and MaxY will be taken as the longest extent, the most maximal Y and the most minimal Y vales. Those are needed, otherwise character won't react to this attack.

• <HorizontalExtents>, its packages store this info:

36 fields (exactly 36, no more, no less, otherwise it won't compile back into .oni file), which correspond to areas in 10° intervals around character ( so overall 360°, full horizontal circle around character).

Imagine character. Look at it from above. Make a circle with this character being center of this circle. Now divide this circle with lines after each 10°; and those are horizontal extent lines used by packages ^_^.

Once more 0° is in front of the character, 180° is behind character. Intervals go clockwise. So first package is horizontal extent for 0° line, second package is for horizontal line which is 10° clockwise and so on.

These extents can be guessed up to some degree. Use common sense, look at Your custom attack and tip which lines are probably intersected by attacking limbs of Your move.

Watch out - if attack is frontal ( direct kick forward ), you should worry not only about 0° (directly front), but also about 10°, 20° (a bit to the right) and also about 340°, 350° (a bit to the left).

Next guess the length (you will get used to the sense of distance soon), write it in, test it with some AI which blocks a lot. If you did it right, Your attack will be often blocked.

Don't overdo it with horizontal extent length - too long will cause AIs to react too far from you, does not look pretty.

Have extended fun, --Loser 19:12, 13 July 2010 (UTC)

Adding colorful trails

Open the xml formated TRAM and search for the "Particles" tag and insert your code.

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 used character class (ONCC) which lunch the actual particle, here it is "h2h_strtrail_e01".

Second example is about two different contrails in one TRAM at 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 used ONCC as well. Using your own contrail particle is also possible, just insert it's 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

Throws target animation are registered in the TRAC of the throw initiator (a.k.a. throw source). Target animations are forced onto the other character removing the need to have that animation in target TRAC.

Throw target (TRAM*tgt) animations can cover only up to 256 (0-255) frames.

Fw throws

Situation: you load two chars into Mod Tools and rotate (+/-180°) the throw target char because you want them to stand face to face. When you are done animating, the target animation would need to be reversed again: multiplying the velocities with -1, also the rotation needs a tweak. So far 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 fw throws

• put your files into the "input_and_output" folder
• disable macro security if you don't want to click every time on the macro option button
• close other worksheets first before you run the macro
• if you are not afraid of VBA code you can enter the developer environment by hitting [alt]+[F11], e.g. for extending the attack library with more screenshots and settings
  • in that case search for: "LibraryThrows", " LibraryAttack", "Picture", "CBAttackHelp.AddItem"

• the macro (for all TRAM except overlay-TRAM), demo vid

A look on run move complex

Example on Striker's moves, meant as illustration for "what would be needed for 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

Start looking on the image most right.

• 

  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 official aborted cutscene
• KONOKOlev16_bomb planting a bomb
• KONCOMsuper_kick now used in OTA scripts (mod) as spawn event
• KONCOMsuper_punch KONCOMpunch_heavy but without attack name shout, HalfDamage, and makes 10 less damage in first attack part
• COMPISidle_special1 comguy checking environment and his gun (it's actually used if you wait long enough, isn't it?)
• STRPISidle_special1 striker showing off his gun, whatever (it's actually used if you wait long enough, isn't it?)
• THUGlev1_direct thug probably directing a truck driver

From modders

Following files are available in DAE (and maybe ONI format).

charA and charB performing stun animations

• Fury double flip (.dae)
  • note: -
• Konoko enters prone mode (.dae + .oni)
  • note: prone mode artefact
• Konoko leaves prone mode (.dae)
  • note: prone mode artefact
• female stun (throw pair) (.dae)
  • note: needs to be slowed down (-> more frames)