PlayAnimation

Category: Animations
Since engine version: 1.0 OC

Description

Starts playing a new animation. The return value of this function is the animation number of the animation node inserted which can be used to manipulate or remove the animation later. If there are already animations in the given slot then additionally a combination node is created. This combination node is assigned the returned number plus 1.

Syntax

int PlayAnimation(string animation, int slot, array position, array weight, int sibling, int attach_number);

Parameters

animation:: Name of the animation to be played.
slot:: Slot in the animation stack in which the animation should be inserted. See Animations.
position:: Specifies how to compute the position of the animation. The value needs to be created with one of the "Anim_" animation functions.
weight:: [opt] Specifies how to compute the weight of the animation in case the animation is combined with another animation in the given slot. The value needs to be created with one of the "Anim_" animation functions.
If nil, the animation is created with constant weight 1000 and other animations in the same slot are removed.
sibling:: [opt] If the animation is combined with another animation then this refers to the node with which the new node is combined. If not given or nil then the animation is combined with the animation at the top of the slot as returned by GetRootAnimation.
attach_number:: [opt] If given, refers to the number of the attached mesh on which the animation is to be played.

Remarks

If a weight is specified, other animations remain in the slot and are automatically combined. Scripters are responsible for removing animations either by replacing them (pass nil as weight), calling StopAnimation or using the ANIM_Remove flag in the Anim_Linear function.

See the animation documentation for further explanations of the animation system.

Examples

PlayAnimation("Scale", 5, Anim_Y(0, GetAnimationLength("Scale"), 0, 15), Anim_Const(1000));

Plays the animation "Scale" and overwrites any potentially existing animations in slot 5 without removing them. The animation position is chosen by the Y coordinate of the object so that the animation is synchronized with the movement of the clonk climbing.

var swim_up = PlayAnimation("SwimDiveUp", 5, Anim_Linear(0, 0, GetAnimationLength("SwimDiveUp"), 40, ANIM_Loop), Anim_Linear(0, 0, 1000, 15, ANIM_Remove));
var swim_down = PlayAnimation("SwimDiveDown", 5, Anim_Linear(0, 0, GetAnimationLength("SwimDiveDown"), 40, ANIM_Loop), Anim_Const(500), swim_up);
var swim_comb = swim_down + 1;

Superimposes a SwimDiveUp and a SwimDiveDown animation in such a way that both animations have the same weight. The result will be that lies horizontally in the water. If there is another animation being played in slot 5 then a transition lasting 15 frames is performed. At its end the previous animation will be removed. Using the variables swim_comb the weight of the two animations can be adapted to the swimming direction with additional code.

Clonk-Karl, 2010-01