Blitz3D+ Command Reference

AnimSeqName$ ( entity,sequence )

Parameters

entity - handle of an animated entity

sequence - sequence number, from 0 to CountAnimSeqs-1

Description

Returns the name of one of an entity's animation sequences.

Animation clips arrive with the names the artist gave them - "Idle", "Walk", "Attack" - and Blitz3D+ keeps those names when it imports a model. AnimSeqName turns a sequence number back into its name, which is exactly what you want for a debug overlay, an animation picker in a tool, or simply printing what a model you just downloaded is capable of. Walk the numbers 0 to CountAnimSeqs-1 to list the lot.

Going the other way - name to number - is FindAnimSeq's job, and PlayAnim skips the numbers entirely by taking a name directly.

An empty string comes back in two different situations, so treat it as "no name available" rather than an error. The sequence number may simply be out of range (negative, or past the last clip), or the clip may genuinely be nameless. Clips created at runtime by AddAnimSeq and ExtractAnimSeq are always nameless, and file formats that do not store animation names - MD2 and 3DS, for instance - give you unnamed clips too. Nameless clips can still be played; you just have to remember their numbers yourself.

See also: FindAnimSeq, CountAnimSeqs, AnimSeq, ExtractAnimSeq, PlayAnim.

Example

; AnimSeqName 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 clip names come straight from the artist's glTF file
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

total=CountAnimSeqs(fox)

; Deliberately start one below the first clip so you can see what an
; out-of-range sequence number reports
seq=-1

; Which clip is currently running (-99 means "nothing yet")
playing=-99

While Not KeyDown(1)

    ; [ / ] walk the sequence number past both ends of the list
    If KeyHit(26)
        seq=seq-1
        If seq<-1 Then seq=total
    EndIf
    If KeyHit(27)
        seq=seq+1
        If seq>total Then seq=-1
    EndIf

    ; Ask the model what this sequence is called
    name$=AnimSeqName$(fox,seq)

    ; Only play clips that really exist
    If name$<>"" And seq<>playing
        Animate fox,1,0.6,seq
        playing=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,"[ / ] : previous / next sequence   Arrows: camera   Esc: exit"
    Text 0,20,"AnimSeqName$(fox,"+seq+") = "+Chr$(34)+name$+Chr$(34)

    ; An empty string is how the engine says "no such sequence"
    If name$=""
        Text 0,40,"Empty name - sequence "+seq+" is outside 0.."+(total-1)
    Else
        Text 0,40,"That clip exists, so it is playing now"
    EndIf

    Flip

Wend

End

Index