Blitz3D+ Command Reference

FindAnimSeq ( entity,name$ )

Parameters

entity - handle of an animated entity

name$ - name of the animation clip to look for

Description

Returns the sequence number of a named animation clip, or -1 if the entity has no such clip.

Your game thinks in names - "Idle", "Walk", "Attack" - while Animate, SetAnimTime and AnimSeq think in numbers. FindAnimSeq is the bridge. Look the name up once while you are setting the character up, keep the number in a variable, and your state machine never has to care that "Run" happens to be clip 2 in this particular file.

The match is forgiving about case: an exact match wins if there is one, and failing that the engine tries again ignoring case, so "walk", "Walk" and "WALK" all find the same clip. Names come from the model file, so glTF/GLB and B3D characters are the ones that carry them.

Always check for -1 before using the result. Passing -1 to Animate is not what you want, and a missing clip usually means a typo or a model that was exported without that animation - printing the name you asked for makes that obvious. Clips created at runtime by AddAnimSeq or ExtractAnimSeq have no name at all, so FindAnimSeq can never find them; hold on to the number those commands return instead.

The lookup is a linear scan through the clip list, so do it during setup rather than every frame. If all you want is to start a clip by name, PlayAnim does the lookup, the crossfade and the "do not restart what is already playing" check for you in one call.

See also: AnimSeqName, CountAnimSeqs, PlayAnim, Animate, SetAnimTime.

Example

; FindAnimSeq 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")

; The fox ships with 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

; Game code thinks in clip names, not clip numbers
wanted$="Survey"
asked$=""

While Not KeyDown(1)

    ; 1/2/3 ask for a real clip, 4 asks for one this model does not have
    If KeyHit(2) Then wanted$="Survey"
    If KeyHit(3) Then wanted$="Walk"
    If KeyHit(4) Then wanted$="run"
    If KeyHit(5) Then wanted$="Backflip"

    ; Only look the name up when the request changes - the number is stable
    If wanted$<>asked$
        asked$=wanted$
        ; FindAnimSeq returns the sequence number, or -1 if there is no match
        seq=FindAnimSeq(fox,asked$)
        If seq>=0 Then Animate fox,1,0.6,seq
    EndIf

    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 Survey  2 Walk  3 run  4 Backflip   Arrows: camera   Esc: exit"
    Text 0,20,"FindAnimSeq(fox,"+Chr$(34)+asked$+Chr$(34)+") = "+seq

    If seq<0
        Text 0,40,"-1 means no such clip - the fox keeps doing whatever it was"
    Else
        Text 0,40,"Playing "+Chr$(34)+AnimSeqName$(fox,seq)+Chr$(34)+" - note key 3 matched despite the lower case"
    EndIf

    Flip

Wend

End

Index