Add Anim Data: Modding Tutorial

-- How to Apply Unique Animations to Your Follower --

  * Created by GomaPudding - Feb 03, 2018

    Sep 09, 2018 - added "Advanced Tutorial 1"


This tutorial will show you how to use Add Anim Data for applying unique animations to your follower.
From basic to advanced, the contents will be added step by step.
Although some basic skills in modding are required, but if you read this you can realize that it is not so difficult to use this tool in modding.

In order to give you a simple explanation, I do not describe the details such as what the tool actually does.
For the people who want to learn more, I give a technical explanation in README.

And there is one more thing that I should inform you. The contents written here basically assume applying animations to a follower,
but from the technical point of view, I think the same thing is possible for the player character.

Basic Tutorial: apply unique animations to your follower

Here is an example of applying unique 1hm_equip.hkx and 1hm_unequip.hkx animations to your female follower.

  1. Create your standalone follower whose race is separated from other NPCs.
    • The reason for separating the race is that the animation definition of characters is set for each race.
      (To be precise, the actor's behavior graph, hkx file, is defined in the race form.)
    • Currently only the human type followers (those behavior graph file is defaultmale/defaultfemale.hkx) can be applied to the tool.
    • If you want to try this tutorial for your player character, I think you should make another dedicated playable race.
  1. Rename the unique animation files (*.hkx) with special name and place them in the appropriate directory.
    • Do not include space in the file name.
    • Here the two animation files were renamed as follows: alice1865_1hm_equip.hkx, alice1865_1hm_unequip.hkx
    • Basically place them in the same directory as their vanilla animations. In this case: Data\meshes\actors\character\animations\
  1. Make a lis file with a text editor. For example: Alice1865.lis
    • You can use your favorite file name (do not include space), but if you want to distribute your follower as a mod,
      you should name it so that user can find which mod is linked.
    • The contents of the lis file are just text data, but the extension must not be changed from ".lis".
    • Now, the contents of the lis file are shown below.

      .hkxname Alice1865_DefaultFemale

      .sexmf Female

      + 1hm_equip.hkx alice1865_1hm_equip.hkx
      + 1hm_unequip.hkx alice1865_1hm_unequip.hkx


    • .hkxname - This will be the name of the behavior graph file.
      You need to set special name so that it does not conflict with other names. For details, see next step.
    • .sexmf - Set either Male or Female.
      If you want to make your female follower behaving like a man, you can set "Male".
    • .animlist - This is the correspondence list of animations files. It is defined one pair of animations per a line.
      The left side is an original animation file name in vanilla and the right side is an unique animation file name you want to apply.
      Tabs are available as separator. 全角スペースは使えません。
    • .end - Do not forget to describe it.
  1. Put the lis file into ANIMLIST folder then execute the tool. And the behavior graph file where the animations you specified were defined will be generated.
    • In this example, you can find Alice1865_DefaultFemale.hkx in Data\meshes\actors\character\.
  1. By using CK, TES5Edit, etc., set the above behavior graph hkx file in Behavior Graph for your follower's race.
    • Note that set it as a relative path, not an absolute path.
  1. All the modding procedures are completed.
    • If you intend to release your follower mod, note that the files generated by executing the tool are not necessary to include in your mod.
    • On the one hand, the unique animations must be included, but be sure to check the license when using animations except that you created.

Thank you very much for reading. Honestly, I think that it is the most difficult to explain how to use the tool.

Advanced Tutorial 1: control the coordinate moving of your follower during animation

I don't know whether the term "coordinate moving/movement" is appropriate, but here I will express the movement behavior of character's position in 3D space with that term.

For example, the forward power attack does not accept control by a player while the animation is valid, but player character automatically moves forward according to predefined coordinate movement information, which is separated from hkx animation files and is defined in "animationdatasinglefile.txt". For such animations, you can modify their coordinate movement behavior by using my tool. Before the concrete explanation, I will explain how the coordinate movement is defined in vanilla.

The coordinate movement information in animationdatasinglefile.txt file

First of all, I will explain the contents of "animationdatasinglefile.txt" in vanilla. You can also find the vanilla file from my tool folder. That is GPT01_AddAnimData_010\vanilla\meshes\animationdatasinglefile.txt. This file contains data of approximately 170,000 rows in total. Here, I will explain the contents while indicating the place of description by line number. So I recommend reading this explanation while actually checking the file with a text editor that can display line numbers. Also, please note that the following description is based on the result of trial and error, so it may contain incorrect information.

Lines 1 to 430 are like a list of animation definition groups. The number 429 on line 1 indicates the number of these groups. (Or I should say that it indicates how many lines of information are written in this list section.)

Below line 430, the animation definitions are described in the order of these groups. For example, there are the name of "DefaultFemale" in line 10 and "DefaultMale" in line 11, which mean the animation difinition group name for female and male respectively. The actual definition of DefaulFemale is described in lines 8732 to 46491. In the same way, that of DefaultMale is described in lines 46492 to 84279. Both DefaultFemale and DefaultMale have almost the same contents, so I will explain about DefaultFemale.

The animation definition section of DefaultFemale shown in lines 8732 to 46491 is roughly divided into two parts. The number 25054 on line 8732 indicates how many lines the first half part has. That is, the last line of the first half part is line 33786 (8732 + 25054), so the second half part starts from line 33787. The coordinate movement information is described in the second half part, but since all the information on this part is described by row of numbers, it is impossible to catch the relationship between each animation and its corresponding coordinate movement information even by checking only this part. In order to know which information is described, it is necessary to confirm the corresponding ID number from the information of the first half part. So, I will explain the contents described in the first half part by giving examples.

In the first half part, for example, the information of the forward power attack for one-handed swords is described in lines 25318 to 25331. Line 25318, that is "1HM_AttackPowerFwdUncropped" in the first line of this information is the definition name of the animation. (About this definition name, you can probably guess from the hkx animation file name, 1hm_attackpowerfwd.hkx.) The line just below it, the number 8 in line 25319 is the ID number of the coordinate movement information. The other information below shows the occurrence time of system events related to this animation. Looking at this, you can see that HitFrame is 0.733 seconds, for example. Please note that changing the occurrence time of the system event will not be reflected in the game. Probably this information is only shown as a result and is assumed to be not loaded at startup. And one more thing, there is another animation definition name of 1 HM_AttackPowerFwd_Outro on line 25332, which also has the same ID number. The details will be described later, but my tool gets the ID number of the coordinate movement information from the animation definition name, so even if we use either definition name the result is the same.

Now, as we know the ID number of the coordinate movement information corresponding to 1HM_AttackPowerFwd, let's move to the explanation of the second half part. The coordinate movement information of ID number 8 is described in lines 33856 to 33874. The first line, that is, the number 8 on line 33856 indicates the ID number. In this second half part, since the information is almost arranged in order of ID number, I think it is relatively easy to find the desired information. The number just below the ID number, that is, 1.5 on line 33857 indicates the playback time of the animation. (The unit is "sec".) The actual coordinate movement data is described in lines 33859 to 33872. Here, four numbers are arranged per a line, and these are considered as one data set. This data set indicates time (sec), X coordinate, Y coordinate and Z coordinate in order from the left. The number 14 on line 33858 indicates how many lines this data set is. Looking at a series of data, you can see that only the value of Y coordinate increases with time. That is, this coordinate movement information shows that it is only moving forward. With the similar description rule, the information of the coordinate axes rotation is also described from lines 33873 to 33874, but since it is rarely used, its explanation is omitted here. (That Data is described with quaternion.)

The description rules for the coordinate movement modification in lis file

Actually, the most important explanation has already been finished above. Continue to use 1HM_AttackPowerFwd as an example, I will explain how to modify the coordinate movement of this animation with the tool.

To modify the coordinate movement information, add the description to the lis file (before the ".end" line) like the following. (Please refer to this video for the actual animation.)

.mod movrot 1HM_AttackPowerFwdUncropped
0.000000 0 0 0
0.233333 0 90 0
0.333333 0 135 0
0.600000 0 150 0
0.866667 0 345 0
1.000000 0 345 0
1.200000 0 347 0
1.300000 0 338 0
1.533333 0 342 0
1.733333 0 273 0
1.833333 0 234 0
1.866667 0 232 0
1.933333 0 227 0
2.033333 0 198 0
2.166667 0 195 0
2.333333 0 201 0
2.400000 0 210 0
3.133333 0 510 0
3.466667 0 570 0
4.833333 0 570 0
4.833333 0 0 0 1

"1HM_AttackPowerFwdUncropped" in the first line corresponds to the animation definition name as described above. The lines other than the first and last lines match the description rule of the part excluding the ID number of the coordinate movement information described above. It is necessary to carefully check if there are no mistakes in the number of lines of the coordinate movement data set (20 in this case) or the contents of the data set. If you make a mistake, the entire animation may not work properly or the game itself may not start.

When modifying coordinate movement especially for power attacks, there are some points to note. First, you can not modify the time when HitFrame event occurs with my tool and also can not apply additional HitFrame. (Although it is possible to show pseudo multiple attacks by using some scripts together, I will not explain the way here.) Second, in the case of NPC, the coordinate at HitFrame time are related to the factors that determine whether to attack. For example, if NPC is moving backward far away from the initial position at HitFrame time, NPC can probably not use that power attack because an enemy almost never come to that position. Finally, especially when NPC moves forward, if NPC hits an enemy (or obstacle) on the half way of the coordinate movement, NPC can not move to the desired coordinate. There are several ways to avoid this, but the details will be explained in the next tutorial.

By the way, the animation playback time of the above forward power attack is 4.833333 sec, which is considerably longer than 1.5 sec in vanilla. Other animations will not be played while the coordinate movement is controlled, so it is also possible to apply longer animation than vanilla. However, it is supposed that animation processing must be completed at the playback time specified by vanilla in terms of internal processing. So note that this trick actually works well but it is not a formal modification method.

Advanced Tutorial 2: how to make attractive power attack animations with scripts

in preparation

back to main page

inserted by FC2 system