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.
NOTE: As far as we are aware using custom animations (if .anim file name or path are changed from vanilla) will result in battle loading CTDs for Linux/mac versions, see here
- 1 Building Animation Useage Overview
- 2 File Structure
- 3 Re-using Existing Animations with IWTE
- 4 Creating New Animations with IWTE and Milkshape
- 4.1 Creating an Animation from Scratch
- 4.2 Animation Model Requirements
- 4.3 Processing the ms3d File/s
- 4.4 Re-naming and Placing Files
- 4.5 Texture Path
- 4.6 Applying the New Animation to a .world Object
Building Animation Useage Overview
Wall objects have a varying number of groups, normally depending on the size of wall. Town palisade 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.
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.
The only building animations that are essential are the gate animation sets, when the gate 'opens' it uses a 'DoorOpenAnim' animation to show the opening process, it stays at the end of that animation until troops clear the area, then uses a 'DoorCloseAnim' 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.
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:
- .evt - if sound effects are required
- 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:
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.
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!)
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.
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.
The following two pictures show how the appearance of a typical wall object changes whilst in animation mode if a different texture is specified in the mesh, from that used in the .world for the structure:
It is possible to create 'custom' .mesh files which use different textures/uv mapping, however currently (April 2017) use of mesh files with non-vanilla names/locations causes a battle loading CTD for Linux/Mac users.
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'.
Contains the triggers for any sound effect applied during the animation. This file can be edited as a text file. Although all existing animations seem to have .evt files, new animations work fine without .evt files, so they are not needed unless you want to generate sound effects.
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.
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:
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.
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.
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
For an object with two groups only one animation can be used the name will be;
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 up to DamageTransition4.
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.
Re-using Existing Animations with IWTE
If you have an object in the .world file and you want to give it an animation you can do so as follows :
- A) open the 3 files using the 'Read 3 Binary Files' button.
- B) select the object in the objects window.
- C) if relevant go to 'MainObjects' tab and 'create new Mainobject' button (choose wall, gate, or arrow tower)
- D) go to the 'Animations' tab and select one of the following options:
This method is used to assign an existing animation set and collision already present in this set of world files. It will ask you to select the animation from a list and guide you through the other options it requires. Note it currently picks up the animation packed data content from the selected animation's object. Eg use if you had a wall with no animation but you already had a similar wall with an animation in your working files.
This method is used to assign an existing animation set and collision already present in another set of world files. It will ask you to select the 3 binary files for that other .world then select the animation from a list and guide you through the other options it requires. Note it currently picks up the animation packed data content from the selected animation's object. Eg use if you had a wall but no appropriate wall animation yet assigned to an object in your working set of world files.
Replacing a Single Existing Animations Pack File Chunk
This function may be of use for replacing animinstance chunk sections from existing animations that have lighting problems in one object, but better results in other objects. Use the 'Replace single Anim pack' button to replace a single packed file section. This will replace the equivalent chunk (which must already exist) within the .animinstances file. For objects with multiple animations (e.g. walls) each level (e.g DamageTransition0, DamageTransition1 etc) needs to be replaced individually. To produce the packed file chunks you either need to have created a new animation or extract the packs from an existing animinstance file as described below.
NOTE: the packed chunk you select must have been derived from the same original .mesh file using the same number of vertexes and joint assignments as the .anim you are using, a mismatch will not cause a CTD but will either produce odd results or simply not appear at-all.
Extracting .animinstance Packed Chunks
On the Animations tab the button Extract Anim packs is used to extract all animinstance packed chunks from a set of worldfiles. It will generate a high-level directory called animpkgdir within the directory containing the worldfiles. Inside this directory is a summary of all the packfiles that were extracted as well as a directory for each object with an animation. The packed files in it are the ones that will be loaded for an object if the directory is selected via the New Animation/Collision button. Note these files are only the component needed by the .animinstances file they are not the full animations.
Changing the texture
The textures used are controlled by the .mesh file. To change the textures use IWTE "Animations" tab, "Edit .mesh tga paths" button. The revised file will replace the .mesh you opened and a copy of the original .mesh will be created in /backup folder.
Changing Visual Effects
The visual effects are triggered from the .anim file. To change or add effects use IWTE "Animations" tab, "Amend .anim effects" button. The revised file will be named "oldFileName_1.anim" - rename this to replace the original file.
Creating New Animations with IWTE and Milkshape
NOTES: This section applies to versions of IWTE from 20_01_A onwards, which introduces the functionality to fully create and amend animations. An ms3d animation file is required. Vanilla .anims can be converted to ms3d files for use as a starting point, this would be especially useful if you just want to make minor adjustments to complicated animations such as wall destruction. To pack the mesh information into .animinstance chunks the IWTE download includes a program (wdanimpack_amd64.exe) which is a tweaked and compiled version of a packer released by Tellos Athenaios and the Europa Barbarorum Team here, the process uses compiled LZO compression code.
Creating an Animation from Scratch
The full set of information required for an animation needs to be created first. This means you need to generate:-
- an animation folder containing all the animation sets (.anim, .evt, and .mesh files) that are required. It is this directory that needs to be found by the game when it loads the .world file. (IWTE does not provide or edit the .evt file, this can be done by text editing.)
- a folder containing a packed file for each animation set which will be loaded into the .animinstances file. This directory is only used to load the .animinstances file it is not used by the game.
Animation Model Requirements
To generate the .anim, .mesh and packed file IWTE requires an animated ms3d file. You need an ms3d file as follows:
- Initial object start position centred on 0,0,0 coordinate. - this is important, if you don't start the object there the .worldcollision won't match the animation to the correct location.
- All vertexes and faces needed for the animation present in the model before you start animating, so parts that break off need to be formed as complete shapes, and the interior areas exposed need to be constructed before animating. BUT please remember that ideally, you need to save and retain a simpler model to use for the undamaged group in the .world file.
- Each chunk that moves independently to be in a separate milkshape group.
- Each vertex of a group to be 100% assigned to the same joint, one joint per group, including a joint for a static group if there is one.
- Full UV mapping to the texture you want to use. One texture per animation only.
- Make sure you have a flat plane of your starting structure aligned with the x or z axis, this will help in aligning collisions properly. For a 'round' object you should have this orientation:
as indicated by the red box IWTE uses a notional smallest rectangle system around objects to align them to collisions, this will align with the flat sides and cause a rotational displacement to be applied to the collision which won't exactly match the animation. (wilddog is working on a fix for this, but having a flat plane at the base would still be preferred)
- Anim length - if you want to set a length of time for the animation (and not get IWTE's default) put the time in seconds on a new line in the ms3d model comment.
- Visual Effects - to add a visual effect via milkshape make a simple shape such as a box as a group without a joint. Position it at the x/y coordinates you want and with the base at the height you want. Add a group comment such as:
- hemisphere_dust_burst_small_set (effect_set_name)
- 0.70 (effect_trigger_time)
- The effect set name can call any SET for a visual effect in the game's effects .txt files.
- Name the group "Effect_0", for the first effect, "Effect_1", for second effect, etc.
- Fading groups - if you want a milkshape group to fade away at the end of the animation, e.g. for debris that isn't going to be included in the damaged version of the object, add:
- as a comment to the group you want to fade out.
- Names of groups don't matter - except for effects as explained above.
- Names of joints don't matter.
- Skeleton - there isn't one in the building animation system - please don't try to link joints.
- Lighter/Darker joints - if you're starting with an ms3d file which has been written from a .world by IWTE you'll have the lighter/darker 'joints' used to store shading information - you will need to delete these - delete by double-clicking them in the joints window and pressing delete on your keyboard.
- Sound Effects - they don't go in the .anim (or ms3d), add them in the .evt file by copying an existing one, re-naming and editing with notepad.
Correcting Non-centered Animations
So, if you've created your ms3d animation without first reading the section above about the start position for the object being centered on 0,0,0, when you try the ms3d to .anim conversion for a DamageTransition0 or gate starting position the dos window of IWTE will give you a warning, like:
Copy the three figures given into a new line in the model comment of the ms3d file and run the conversion again. If the data is picked up correctly you will see a line in the command box saying:
- animation position to be adjusted by -0.000000 0.107807 -0.516006
NOTE: The centering is required for the first damage transition and undamaged gates starting in the closed position (because the collision transposition displaces from 0,0,0 to the center of the first group of an object). It is assumed that if you have subsequent animations for gates starting in the open position or subsequent levels of damage that you have started them from the same position! If so, and if the DamageTransition0 requires centering then copy the SAME offset numbers into the model comment for the other animations. If you've got animated ms3ds for subsequent stages that don't correctly overlay the first group's center then it is up to you to figure out what the offset needs to be!
If you need a multi-stage animation (for walls with multiple damage states) you may find it easier to make the first stage animation, use IWTE to generate the .anim file - at the same time as generating the .anim it will generate an _end.ms3d which is a static file containing the groups and joints from your first animation in their final position/rotation - this can be used as the starting point for the next phase of the animation.
Processing the ms3d File/s
Once the animation is complete use IWTE “Animations” tab, “ms3d to anim files” button and select the ms3d file. This will generate a .mesh file, a .anim file and a .packed (.unpacked also generated but not used). It will also produce for you an 'animstart' and 'animend' ms3d file - these are not used by the game/IWTE but might be useful for you if you haven't already made static ms3d groups for the undamaged/damaged versions of the object you animated.
It is very important that you FIRST rename your .ms3d file so it contains the correct naming of the animation transition. The format of the name is ‘yourname_AnimationTransition.ms3d’ the AnimationTransition part must be one of the known animation transition names and spelt exactly. Eg DamageTransition0 for the first damage transition. DamageTransition1 for the second, etc. or one of the gate movement transitions. The gate transitions must be as follows; DamageTransition0, DamageTransition1, DoorCloseAnim0, DoorCloseAnim1, DoorImpactAnim0, DoorImpactAnim1, DoorOpenAnim0, DoorOpenAnim1. The transition name will be recorded inside the .packed file, trying to change it at a later stage will result in a CTD. IWTE will not convert an ms3d file if the name is not in the correct format.
If your object requires multiple animations, e.g. walls or gates, you will need a separate ms3d file for each animation, and you will need to go through the make .anim process for each. For gates the vanilla animations typically use the same .anim for DamageTransition0 (which is the step from undamaged, to minor-damage, and for DoorImpactAnim1 (which is the minor-damage version being hit and shaking slightly) - if you want to use the same .anim for these you will need to make a 2nd copy of the ms3d to re-name so you can generate packed files with both transition names.
Re-naming and Placing Files
The .anim and .mesh files generated will have the same name as your original ms3d file e.g. my_new_wall_DamageTransition0 - you can leave them as that, so long as the .evt file is given the same name, if you keep this name it will be the one required in the .world file, you can re-name the .anim, .mesh and .evt to something simpler such as my_new_wall_a (obviously keep the names aligned so you know which represents which transition!).
Place all the .anim, .mesh and .evt files in the animfolder you wish to use (same folder for all the animation sets for the object's animation). The vanilla files are normally placed in blockset/culture/animations, you could do the same or use blockset/mod_name/animations etc.
If you didn't include a texture name in the ms3d comment .mesh files will have been generated with dummyname.texture and dummyname_normal.texture names, use the "Edit animation tga paths" button to include your desired .texture and normal.texture, change the path and name as desired and click OK. This will overwrite the .mesh file you opened so it will be ready to use in game, the original mesh file will have been copied to the /backup folder.
Applying the New Animation to a .world Object
Creating the .world Object
If the object does not already exist in your .world it must be added first, either as a new structure or added to an appropriate existing structure. To add the object you need to have each stage of the object constructed as a group in the milkshape file, with the groups in the correct sequence (undamaged first), and use the IWTE convention of naming e.g obj1-gp0, obj1-gp1, obj1-gp2 etc to tell IWTE the groups form part of the same object. NOTE: This is one group per STAGE, so normal objects will just have the 2 (undamaged and damaged) groups, gates 3 groups, walls 4 to 6 groups, at this stage you don't use one group per joint! When you've got your ms3d file prepared use the add or replace structure function to incorporate it.
If you didn't remember to keep a static version of the object before creating your animated version, when you use the '.ms3d to anim files' button, in addition to making the .anim this will also generate a static ms3d file for the start and the end positions. The start position file can be used for the undamaged group. To use the end position ms3d to create the damaged group for the .world object delete any milkshape groups that you have set to fade, or don't need, from the static damaged group, and re-group all the other remaining parts. Get the groups into the same ms3d file by using milkshape's merge function. Your object will be at 0,0,0 coordinates, move it to where it needs to appear in your .world and rotate it if necessary, merge the object's ms3d into an existing structure if you want to incorporate it in the structure.
Applying the Animation
Load the 3 binaries for your .world. Select the object you want to have the new animation in the 'Objects' window. On the 'Animations' tab use the 'New Animation/Collision' button. This will ask you for the directory where the .packed files are, (these are the .packed files you generated using the ms3d to .anim function) navigate to the directory. You will then be asked to 'Indicate direction Object faces' - IF your in-world object faces the same way as the .anim then leave the direction arrow at 0 - IF you rotated the object, imagine your .anim as representing the 0 position and use the arrow to show the approximate new direction, or enter the value if known.
If your object is a wall or gate you will be taken through the normal docking/breach screens, adjust the options to suit your requirements.
Finally, go to 'WorldFiles' tab 'update animation paths' button. From the drop-down list select your new animation, this will have been put in at default values;
Double click on each path and change the file path and name to wherever you are going to place your final .anim/.mesh/.evt files. Click OK when done. Save 3 Binary Files - re-name them to use in-game.