Blitz3D+ Command Reference

PlayAnim ( entity,clip$[,blend#][,mode][,speed#][,restart] )

Parameters

entity - handle of an animated entity
clip$ - name of the animation clip to play
blend# (optional) - crossfade time, in UpdateWorld units; 0 (default)
mode (optional) - playback mode; 1 (default):
1: loop
2: ping-pong
3: one-shot

speed# (optional) - animation frames advanced per UpdateWorld; 1 (default)
restart (optional) - True to restart the clip even if it is already playing; False (default)

Description

Plays a named animation clip with a crossfade, and returns the sequence number it started.

This is the friendly front end to the animation system: instead of tracking sequence numbers, you name the move. PlayAnim player,"run",0.2 finds the clip called run, blends into it over 0.2 of an UpdateWorld unit and loops it. Names are matched exactly first, then case-insensitively, so "Run" and "run" both work.

The restart parameter is what makes this comfortable to call from a state machine. With restart False - the default - asking for the clip that is already playing in the same mode does nothing at all, so you can call PlayAnim every single frame from your idle/walk/run logic and the animation just carries on. Pass True when a move genuinely has to start over, such as replaying an attack while the previous swing is still finishing.

blend# is a real crossfade, not just a tween into the first frame: both clips keep playing and the poses are mixed, so a walk melting into a run looks natural. A blend of 0 switches instantly. Values around 0.1 to 0.3 suit most character transitions.

Clip names come from the model file, so this needs a format that stores them - .b3d, .gltf and .glb do. If the name is not found the command raises an error listing the clips that are available, which is the quickest way to find out what your artist actually called things.

See also: CrossFadeAnim, Animate, AnimSeq, SetAnimSpeed, LoadAnimMesh.

Example

; PlayAnim 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

While Not KeyDown(1)

    ; A tiny animation state machine: pick a clip name from the held keys
    state$="Survey"
    If KeyDown(17) Then state$="Walk"
    If KeyDown(19) Then state$="Run"

    ; PlayAnim starts the named clip with a crossfade and returns its sequence
    ; number. It is safe to call every frame: repeating the current state does
    ; not restart the clip.
    sequence=PlayAnim(fox,state$,10)

    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,"Hold W to walk, R to run   Arrows: camera   Esc: exit"
    Text 0,20,"PlayAnim(fox,"+Chr$(34)+state$+Chr$(34)+",10) returned sequence "+sequence

    Flip

Wend

End

Index