0 of 0
About this mod
This is a resource for modders to learn about `ToggleSpecialAnim`, the OBSE function which allows you to dynamically override animations during the game's runtime. The mod adds some distinct animations, and a small script with a basic implementation of how you would use the function and how to overcome its limitations.
- Requirements
- Permissions and credits
-- Introduction --
There doesn't seem to be too much info out there on how ToggleSpecialAnim works. I was thinking of using it in a mod I was building, so I did a bit of research and testing of my own, and thought it might be worth sharing.
Most of the information I got initially was from VipCxj's Air Fight System, which contains a really solid implementation of the function; assigning a large array of animations to a specific character at certain times, or for the player on key press.
-- Limitations --
What I discovered was that it is mandatory to refresh the character's animation cache once you've done a ToggleSpecialAnim call. The character will not use any of the new animations until this is performed. This unfortunately also comes with side effects. The character's pose is reset, causing a slight jump to the default pose (arms down by side) before reselecting what the current animation should be and then blending into that.
The second limitation is related to animation priority. Normally, 'specialAnims' toggled on with ToggleSpecialAnim will override and have absolute priority over the equivalent default animation. So, for example, if you ToggleSpecialAnim ON a walk forward animation, the special anim will always be played when you walk forward, and never the default animation (provided you are using the correct weapon type - e.g. "OneHandForward.kf" requires a one-handed weapon).
With Stagger and Recoil however, that's different. For some reason, the engine allows multiple defaults and multiple Special anims to all have equal weighting/priority. That means it will randomly pick between the full pool of available animations for the given stance/group (e.g. any "OneHandStagger" animations will be picked when wielding a one handed weapon and a stagger is triggered).
There is a workaround for this, which is to duplicate the animation and give them indexed suffixes (i.e. "OneHandStagger_01", "OneHandStagger_02" etc.). This way you're increasing the chance of your animation being picked, because there's more of them, and they all have equal weighting. This can be demonstrated with the mod files included here. The ini file allows you to specify how many of the stagger files (up to 9) get loaded in. If you load 9 in, that's a 9/10 chance your special anim will be chosen. (The default ini setting is 4, but it will go up to 9)
-- How to test --
Setup
(The below assumes you don't have any other animations installed which would override/interfere!)
- Install with Wrye Bash/Other mod manager (make sure the animations and the ini file are installed to the corresponding locations)
- Toggle the .esp ON
- Launch the game, load into a place where you can experiment
- You could use "coc testinghall" to go to the testing hall, although it tends to be fairly dark in there unless you install the Testing Hall Improved mod which I would recommend!
- Open up the console to see that ToggleSpecialAnimTest has initialised
- Make sure you have a 1h weapon and it is not sheathed
- If you need a 1h weapon, open the console and run "player.additem 00090613 1" to get yourself a nice new Rusty Iron War Axe (Console paste)
Then
For general use:
- Walk forwards a few times to see that it always picks the default walk forwards
- Press the toggle hotkey (default: Shift+E)
- (Optionally) Check the console again to see that the animations have been toggle on
- Walk forwards a few times more, and see that the floating walk animation is always picked
- (Optionally) Toggle off (Shift+E), test again, and repeat to your heart's content!
For recoil/stagger:
(Similar procedure to above, but since Stagger/Recoil are harder to trigger, we use the console)
- Open the console run the command "player.playgroup stagger 1"
- See that the default stagger animation is played
- Press the toggle hotkey (default: Shift+E)
- Play the stagger animation group on the player again
- At this point you will see either the specialanim chosen, or the default anim; the probability depends on how many stagger anims you specified should be toggled on via the ini for this mod.
- Keep repeating the playgroup command and you should see a trend which reflects the proportion of stagger anims loaded compared to the single default one.
On other NPCs:
The script can be set in game to toggle anims on for another actor.
- Open the console and click on the actor; See their reference number at the top of the screen (e.g. 0002b7d1)
- Run the command set ToggleSpecialAnimTest.rActor to "<your ref id here"
- The script has now been configured to target this actor (unless your ref was invalid!)
When you press the toggle anims hotkey, the anims will be toggled on the actor instead
- Make sure the actor has their weapon out (you can run SetAlert 1 to force this)
- Run PlayGroup Stagger 1 or PlayGroup Forward 1 to see the toggled anims in action, as we did with the player before!
There doesn't seem to be too much info out there on how ToggleSpecialAnim works. I was thinking of using it in a mod I was building, so I did a bit of research and testing of my own, and thought it might be worth sharing.
Most of the information I got initially was from VipCxj's Air Fight System, which contains a really solid implementation of the function; assigning a large array of animations to a specific character at certain times, or for the player on key press.
-- Limitations --
What I discovered was that it is mandatory to refresh the character's animation cache once you've done a ToggleSpecialAnim call. The character will not use any of the new animations until this is performed. This unfortunately also comes with side effects. The character's pose is reset, causing a slight jump to the default pose (arms down by side) before reselecting what the current animation should be and then blending into that.
The second limitation is related to animation priority. Normally, 'specialAnims' toggled on with ToggleSpecialAnim will override and have absolute priority over the equivalent default animation. So, for example, if you ToggleSpecialAnim ON a walk forward animation, the special anim will always be played when you walk forward, and never the default animation (provided you are using the correct weapon type - e.g. "OneHandForward.kf" requires a one-handed weapon).
With Stagger and Recoil however, that's different. For some reason, the engine allows multiple defaults and multiple Special anims to all have equal weighting/priority. That means it will randomly pick between the full pool of available animations for the given stance/group (e.g. any "OneHandStagger" animations will be picked when wielding a one handed weapon and a stagger is triggered).
There is a workaround for this, which is to duplicate the animation and give them indexed suffixes (i.e. "OneHandStagger_01", "OneHandStagger_02" etc.). This way you're increasing the chance of your animation being picked, because there's more of them, and they all have equal weighting. This can be demonstrated with the mod files included here. The ini file allows you to specify how many of the stagger files (up to 9) get loaded in. If you load 9 in, that's a 9/10 chance your special anim will be chosen. (The default ini setting is 4, but it will go up to 9)
-- How to test --
Setup
(The below assumes you don't have any other animations installed which would override/interfere!)
- Install with Wrye Bash/Other mod manager (make sure the animations and the ini file are installed to the corresponding locations)
- Toggle the .esp ON
- Launch the game, load into a place where you can experiment
- You could use "coc testinghall" to go to the testing hall, although it tends to be fairly dark in there unless you install the Testing Hall Improved mod which I would recommend!
- Open up the console to see that ToggleSpecialAnimTest has initialised
- Make sure you have a 1h weapon and it is not sheathed
- If you need a 1h weapon, open the console and run "player.additem 00090613 1" to get yourself a nice new Rusty Iron War Axe (Console paste)
Then
For general use:
- Walk forwards a few times to see that it always picks the default walk forwards
- Press the toggle hotkey (default: Shift+E)
- (Optionally) Check the console again to see that the animations have been toggle on
- Walk forwards a few times more, and see that the floating walk animation is always picked
- (Optionally) Toggle off (Shift+E), test again, and repeat to your heart's content!
For recoil/stagger:
(Similar procedure to above, but since Stagger/Recoil are harder to trigger, we use the console)
- Open the console run the command "player.playgroup stagger 1"
- See that the default stagger animation is played
- Press the toggle hotkey (default: Shift+E)
- Play the stagger animation group on the player again
- At this point you will see either the specialanim chosen, or the default anim; the probability depends on how many stagger anims you specified should be toggled on via the ini for this mod.
- Keep repeating the playgroup command and you should see a trend which reflects the proportion of stagger anims loaded compared to the single default one.
On other NPCs:
The script can be set in game to toggle anims on for another actor.
- Open the console and click on the actor; See their reference number at the top of the screen (e.g. 0002b7d1)
- Run the command set ToggleSpecialAnimTest.rActor to "<your ref id here"
- The script has now been configured to target this actor (unless your ref was invalid!)
When you press the toggle anims hotkey, the anims will be toggled on the actor instead
- Make sure the actor has their weapon out (you can run SetAlert 1 to force this)
- Run PlayGroup Stagger 1 or PlayGroup Forward 1 to see the toggled anims in action, as we did with the player before!