Blitz3D+ Command Reference

Animate entity[,mode][,speed#][,sequence][,transition#]

Parameters

entity - handle of an animated entity
mode (optional) - playback mode; 1 (default):
0: stop
1: loop
2: ping-pong - play forwards, then backwards, forever
3: one-shot - play once and stop

speed# (optional) - animation frames advanced per UpdateWorld; 1 (default)
sequence (optional) - which animation sequence to play; 0 (default)
transition# (optional) - time spent easing from the current pose into the first frame; 0 (default)

Description

Starts an entity animating.

Call it once to set a move going - it is not a per-frame command. The animation then advances every time you call UpdateWorld, so a loop that calls UpdateWorld and RenderWorld is all the upkeep it needs.

Speed is in animation frames per UpdateWorld step, scaled by the elapsed value you pass to UpdateWorld. Doubling it plays the move twice as fast; a negative speed plays it backwards, starting from the end of the sequence. Mode 0 stops the animation and parks the entity on the first frame of the sequence.

An entity loaded with LoadAnimMesh starts with a single sequence, number 0. LoadAnimSeq and AddAnimSeq append more, numbered 1, 2 and so on, and the sequence parameter picks between them. Asking for a sequence that does not exist leaves the entity as it was.

transition# is the fix for the jolt you get when a character snaps from a standing pose into the first frame of a run. Leave it at 0 for an instant change; give it a small positive value and the entity eases from wherever its parts are now into the start of the new sequence over that many UpdateWorld steps. For switching between moves mid-game, CrossFadeAnim and PlayAnim blend the whole sequences rather than just the entry pose, which looks better again.

Animate always restarts the sequence from the beginning. If you want to change speed without losing your place, use SetAnimSpeed.

This is for models with a hierarchy and animation data, such as those loaded by LoadAnimMesh. Quake II .md2 models are morph-animated rather than skeletal and have a family of their own - use AnimateMD2 for those.

See also: Animating, AnimTime, SetAnimSpeed, PlayAnim, CrossFadeAnim, LoadAnimMesh.

Example

; Animate Example
; ---------------

Graphics3D 640,480,0,2
SetBuffer BackBuffer()

camera=CreateCamera()
PositionEntity camera,0,2,-6
RotateEntity camera,12,0,0

light=CreateLight()
RotateEntity light,45,45,0

; A grassy paddock for the fox to roam
ground=CreatePlane()
EntityTexture ground,LoadTexture("media/MossyGround.BMP")

; Load the rigged fox; it has the named clips "Survey", "Walk" and "Run"
fox=LoadAnimMesh("../../../samples/glTF/assets/Fox/Fox.glb")
If fox=0 Then RuntimeError "Could not load Fox.glb: "+ModelLoadError()

; Shrink the fox to game scale (the file is modelled about 100 units tall)
FitMesh fox,-0.8,0,-0.8,1.6,1.6,1.6,True

; Look up the sequence numbers of the named clips
survey=FindAnimSeq(fox,"Survey")
walk=FindAnimSeq(fox,"Walk")
run=FindAnimSeq(fox,"Run")

; Start the fox looking around
Animate fox,1,1,survey
info$="Animate fox,1,1,survey (loop)"

While Not KeyDown(1)

    ; Each key starts a sequence in a different Animate mode
    If KeyHit(2) Then Animate fox,1,1,survey,10 : info$="Animate fox,1,1,survey,10 (loop)"
    If KeyHit(3) Then Animate fox,2,1,walk,10 : info$="Animate fox,2,1,walk,10 (ping-pong)"
    If KeyHit(4) Then Animate fox,3,1,run,10 : info$="Animate fox,3,1,run,10 (one-shot)"

    ; UpdateWorld advances the animation each frame
    UpdateWorld

    ; Arrow keys move the camera
    If KeyDown(200) Then MoveEntity camera,0,0,0.1
    If KeyDown(208) Then MoveEntity camera,0,0,-0.1
    If KeyDown(203) Then TurnEntity camera,0,1,0
    If KeyDown(205) Then TurnEntity camera,0,-1,0

    RenderWorld

    Text 0,0,"1: loop Survey   2: ping-pong Walk   3: one-shot Run   Arrows: camera   Esc: exit"
    Text 0,20,info$
    Text 0,40,"Sequence: "+AnimSeq(fox)+"   Animating: "+Animating(fox)

    Flip

Wend

End

Index