Building Animations - M2TW

Building animations are used in M2TW battle-map buildings to represent gates opening and closing, walls being progressively destroyed, and towers and gates being damaged.

Useage Overview

Walls

Wall objects have a varying number of groups, normally depending on the size of wall. Town pallisade wall objects only have 4 groups, typical castle wall objects have 6 groups. Animations are used to show the transition between one group and the next, so for a 4 group wall object you would have 3 transitions. If animations are not used the view in-game simply switches suddenly from one damage state group to the next.

Towers

Arrow Tower objects should be a 2 group object with a damaged and undamaged state. Animations are used to show the transition. Tall and complex tower objects in the game that can not be specifically targetted by artillery may also use an animation as above. If an animation is not used the view in-game simply switches suddenly from one damage state group to the next.

Gates

The only building animations that are essential are the gate animation sets, when the gate 'opens' it uses an 'Open' animation to show the opening process, it stays at the end of that animation until troops clear the area, then uses a 'Close' animation to return to the starting position. Unlike the other transitions this is not a switch from one object-group to another, the temporarily open state is solely shown by the animation, if an animation is not used troops trying to use the gate will get stuck. This is a peculiarity of gates - for other building items the structure collisions do not actually stop troops.

File Structure

The object itself (wall/gate/tower) and the object's groups are structures within the .world file.

The animation requires the following files which will be common to all instances of the same wall/gate/tower:

• .anim
• .mesh
• .evt - sound effects trigger
• textures - which would normally be the same as those used for the object.

To activate the animation for a particular instance of an object the .world files for the settlement are used:

• .world - contains the file-path and name of the .anim to be used, and the assignment to each object.
• .worldcollision - sets the displacement and rotation from 0,0,0 to where the animation should appear for the specific object.
• .animinstances contains packed chunks of compressed information specific to each object.

More detail is given below, ignore the technical information unless you're interested in tool development:

Common Files

These are the .anim, .mesh & .evt files which are used for each instance of an object e.g. each northern_european town palisade wall object, these can be used by more than one settlement. The vanilla files are found in data/blockset/culture/animations/animation_type/animation_name/ folders. Within each folder there will be sets of the three files for each transition stage. For walls these file names end with _a, _b, _c etc. this is purely a naming convention and the .world files have been set so the first transition uses the files ending _a, second uses _b etc.

The .anim file name and path is the only one listed in the .world files, the .mesh and .evt are called by having the same name and folder location.

There is some overlap in content between the .anim, .mesh and .animinstances files, so not all of the content is used by the game, e.g. uv mapping from the .anim file is not read in-game, vertex positions from the .mesh file are not read in-game. However, the content of the other files is clearly derived originally from the .anim.

.anim

The most important content of the .anim is the joint positions, their movements and rotations. The file also determines which chunks of the animated structure fade away at the end. The .anim also contains the triggers for any visual effects used by the animation, most usually dust_puff sets, though the effects could theoretically be any set contained within the text files listed in descr_effects.txt (effects that don't have a time limit in the text file will continue after the animation has stopped!)

Technical Information

The .anim file is a binary file which appears to have used the Granny 3D system to export animations - the file can not be directly opened in any 3d program - the rotations are stored as quaternions in a variety of different methods including a method designed for maximum compression which removes the largest number from the 4 quaternion values and indicates which value has been removed with a bit indicator (unfortunately the resultant 3 value rotations look a lot like eulers until you realise what is going on!). The file can be re-written to use the simpler style of listing quaternions throughout so all 4 values are shown for each rotation, this makes the rotations sections slightly longer but as there is also a lot of gumpf associated with the Granny export that can be safely deleted the overall file size can be reduced. The other complication with understanding the file is that it uses a system of 'pointers' instead of listing all of the contents in a top to bottom fashion.

.mesh

The most important content of the .mesh is the assignment of each vertex to a joint group number, the uv mapping and the texture name and path - note that only one texture can be used per .mesh file.

Technical Information

The .mesh file contains purely 'mesh' information, the vertex information, triangles, normals and uv mapping. Although the joint assignments used in-game are set in this file there are actually no joints or bones in it! The 'joint assignment' uses unused sections of vertex information to store the joint number against each vertex, and also an indicator as to whether the vertex is in a group that 'fades'.

.evt

Contains the triggers for any sound effect applied during the animation. This file can be edited as a text file.

Use specific files

The association of the above files with an individual object in a battle-map settlement occurs in the .world files of the settlement.

.world

The .world file contains the data for the objects, e.g. walls/towers/gates, that appear on the battle-map of a settlement. Any multi-group object can have an animation-set assigned as appropriate. A number recorded against the object refers to the position of the animation in the list of animations used within the .world. For each animation used within the .world file, a path and file name is stored for each transition, these can be edited in IWTE, the picture below shows an example for a gate animation:

.worldcollision

The .worldcollision file does not change according to whether an animation is used or not. The importance of the file is that the transposition used from collision position (at 0,0,0 coordinates 0 rotation) to the specific object position and rotation is also used for the display of the animation whilst in progress. Therefore if the collision transposition has been set-up incorrectly the animation will appear in the wrong place.

.animinstances

The .animinstances file contains an entry for each object in the .world file, if the object does not have an animation the entry is simply 0. For objects with animations the entry comprises "Transition Name", followed by a compressed (packed) section of data representing the vertex information derived from the .mesh file, and for vanilla files information specific to the object location for each vertex, i.e. if a particular vertex is within range of a light-emitting effect.

Technical Information

The compressed chunks of data in the .animinstance file are used in-game to show the position of the vertexes in relation to the joints, this is why changing the .mesh file on its own does not affect the size/position of animated objects. The compression system used is similar to the one used to 'pack' other aspects of the game such as sound files and unit animations, however, this file requires that each transition be 'packed' as a separate and whole chunk.

In addition to the information taken from the mesh, in the vanilla files, parts of the information for each vertex are also used to store light/dark shading information for the beginning and end of the animation, and intensity of applied effect from up to 3 adjacent light-emitting effects (e.g. night braziers, or damage fires). The reference to adjacent light-emitting effects uses a numeric based on the effect's position in the list of effects within the .world file, this is why copying a chunk of animinstance data from one .world to another .workd which has fewer effects can result in the 'disco lighting' problem during the animation - if the animinstance attempts to use an effect number which doesn't exist in the new .world

Transition Names

For an object with two groups only one animation can be used the name will be;

DamageTransition0.

For walls with multiple groups there will be one less animation than the number of groups and the names in sequence will be;

DamageTransition0, DamageTransition1, DamageTransition2, DamageTransition3, DamageTransition4 etc

Gates have three groups in the .world structures, a closed group, a partly damaged group, and a destroyed group. The closed & partly damaged groups each have a set of open, close, and impact animations, two other animations give the transition from undamaged to damaged to destroyed. The transition names are;

DamageTransition0, DamageTransition1, DoorCloseAnim0, DoorCloseAnim1, DoorImpactAnim0, DoorImpactAnim1, DoorOpenAnim0, DoorOpenAnim1.