ActivateAnim
A function added by the kNVSE Plugin.
Contents
Description
Plays the specified anim at the specified priority and weight, with optional parameters. All arguments except the sequence path are optional. This is a low-level animation function that must be used with care. Use ForcePlayIdle or PlayGroup if you don't know what you're doing. This function plays the specified animation sequence path at the specified priority and weight. The animation will overlay any other animations playing on the actor. Use DeactivateAnim, CrossFadeAnims or BlendToAnim to deactivate or transition the animation to a different one.
- bIsFirstperson specifies if the animation should be played on the player character's first person or third person skeleton. If the target actor is an NPC it will default to 0. If no value is specified and the reference is the player character it will default to the current point of view of view of the player.
- priority specifies the priority. The default value is 1.
- bStartOver specifies if the animation should start from it's "start" key or resume from it's last offset. The default value is 1.
- fWeight specifies the final weight of the animation after easing in. Default value is the sequence weight of the NiControllerSequence which can be retrieved with GetAnimationAttributes.
- fEaseInTime specifies a time period over which the weight will be ramped up from 0.0 to the weight specified by fWeight. This is used for easing in sequences so that they do not pop when activated over other running sequences. The default value is the max of the animation's Blend and BlendIn text keys divided by 30. If the animation is missing both of those keys, the default ease in time will be 0. For more info see Easing In and Out.
- time sync sequence path is an optional sequence with which the time for the activated sequence is synchronized. This synchronization is done via the morph text keys in each sequence. If at least one pair of identical morph text keys is not found in each sequence, this function will return 0.
The path of the sequence must be based from Meshes\, but should not include it in the string for most anim group based animations but should contain the prefix for idle animations.
The anim must be deactivated or otherwise nothing will happen. Animations do not deactivate by themselves after they finish.
Syntax
actor.ActivateAnim anim sequence path:string bIsFirstPerson:0/1 iPriority:integer bStartOver:0/1 fWeight:float fEaseInTime:float time sync sequence path:string
Example
ActivateAnim "Characters\Recoil.kf" 1
Priorities
Each sequence that is activated is assigned a priority. The priority indicates what precedence the sequence has over other active sequences. The default priority for all sequences is 0. If a sequence is activated with a higher priority, it will take complete precedence over the lower priority sequences once it is at full strength (i.e. not easing in or out). This is useful for activating sequences that control part of a character while a full body sequence plays at a lower priority. For example, a full body walk sequence could be active with a priority of 0 and an arm wave sequence could be activated with a priority of 1. The arm wave sequence would take precedence over the walk sequence for the bones it controls, causing the arm to wave while the remainder of the body continues to walk.
Weights
Upon activation each sequence is assigned a weight in the range from 0.0 to 1.0. This value defines the maximum weight the sequence will have once it reaches full strength (i.e. not easing in or out). If multiple sequences are active on a given bone, sequence weights are normalized at each priority level before blending with sequences at other priorities. Effectively, this means the weight of a sequence describes how it blends with other sequences at the same priority. For example, "look right" and "look left" sequences can be activated at priority 0 with a weight of 0.5 each to achieve an end result of looking straight ahead. These same sequences can both be weighted 1.0 (or even 0.0) to produce an identical outcome due to the normalization process that occurs at each priority level.
Easing In and Out
When sequences are activated and deactivated their effective weight values can be eased in and out to achieve smooth transitions in the final result. The durations for this easing are specified in the ActivateAnim and DeactivateAnim functions as well as most transition functions. When being eased in, the weight value is ramped up from 0.0 to the weight that was specified in the activation function. Similarly, when being eased out, the weight value is ramped down from the specified weight to 0.0.
Time Synchronization
With optional time synchronization, the update time for one sequence is determined by another sequence. This results in time compression being performed for the first sequence so that its timing directly corresponds with the second sequence. This allows sequences with different lengths and frequencies to be run simultaneously, with one sequence synchronized to the other. This eliminates potential artifacts of animation blending, such as having foot falls come at different points in each sequence, which is common with walk and run sequences. Any activated sequence can be optionally synchronized to any other sequence. Circular dependencies are detected and rejected by the activation functions.
In order for time synchronization to be used between two sequences, the sequences must have been marked with identical pairs of morph text keys. For example, a walk animation and a run animation could each have a morph text key named "morph: knees together" at the point in each animation where the knees are together. Additionally, they could also have an identical pair of morph text keys called "morph: left foot down" at the point in each animation when the left foot is on the ground. All identical pairs of morph text keys that are found in the two sequences are used for synchronization so the animation looks correct even if the two sequences are of different lengths.
