PollAnimEvent$ ( entity )

Parameters

entity - handle of an animated entity

Description

Takes the oldest waiting animation event off an entity queue and returns its name, or an empty string when nothing is waiting.

This is the read end of the animation event system. Set marks up with AddAnimEvent, then after each UpdateWorld drain the queue and act on the names:

e$=PollAnimEvent(player) : While e$<>"" : If e$="footstep" Then PlaySound step_sound : e$=PollAnimEvent(player) : Wend

Events come out in the order they fired, first in first out, and each one is returned exactly once.

Polling rather than callbacks is a deliberate choice: your code runs between updates instead of in the middle of one, so you are free to free entities, load things or change animations in response to an event without upsetting the update that produced it.

Names are whatever you passed to AddAnimEvent, so an event never collides with a real command name; compare them as ordinary strings.

See also: PendingAnimEvents, AddAnimEvent, ClearAnimEvents, UpdateWorld.

Example

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

; Place footstep events on the walk cycle for UpdateWorld to queue
walk=FindAnimSeq(fox,"Walk")
AddAnimEvent fox,walk,10,"left footstep"
AddAnimEvent fox,walk,30,"right footstep"

CrossFadeAnim fox,walk,0,1

last_event$="none yet"
total=0

While Not KeyDown(1)

    UpdateWorld

    ; PollAnimEvent removes and returns the oldest queued event name;
    ; it returns "" once the queue is empty
    Repeat
        event$=PollAnimEvent(fox)
        If event$<>"" Then last_event$=event$ : total=total+1
    Until event$=""

    ; 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,"Arrows: camera   Esc: exit"
    Text 0,20,"PollAnimEvent last returned: "+last_event$
    Text 0,40,"Footsteps polled so far: "+total+"   AnimTime: "+AnimTime(fox)

    Flip

Wend

End

Index

Blitz3D+ Command Reference

PollAnimEvent$ ( entity )

Parameters

Description

Example