Blitz3D+ Command Reference

SetAnimTime entity,time#[,anim_seq]

Parameters

entity - handle of an animated entity

time# - frame position within the sequence; fractions are interpolated between frames

anim_seq (optional) - sequence number to pose; 0 (default)

Description

Poses an entity at an exact frame of an animation sequence.

Animate hands the clock to the engine; SetAnimTime keeps it for yourself. You say which frame you want and the character snaps to that pose immediately. That is what you need for a cutscene scrubber, a replay you can rewind, a "pose the model" screen in an editor, or a character whose animation is driven by something other than time - a door that opens in step with a lever, a wheel whose spin follows the vehicle's speed.

Time is measured in frames, and fractions are honoured: 4.5 blends halfway between frame 4 and frame 5, so a slow scrub looks smooth rather than steppy. Values outside the clip wrap around instead of clamping, so on the 43-frame Walk clip, frame 60 poses as frame 17 and -1 poses as frame 42. AnimTime always reads back the wrapped value.

The big gotcha: SetAnimTime stops playback. It clears the entity's animation mode and speed, so Animating drops to 0 and the character stays frozen on your pose until you call Animate or PlayAnim again. That is usually what you want, but it does mean you cannot use SetAnimTime to nudge a clip that is meant to keep running - it will stop dead.

Two quieter behaviours are worth knowing. Asking for a sequence number that does not exist is silently ignored, so nothing moves and you get no error - check the number with FindAnimSeq or CountAnimSeqs first. Calling this on an entity that has no animation at all is a genuine runtime error, so guard models that might have been loaded with LoadMesh rather than LoadAnimMesh.

See also: Animate, AnimTime, AnimLength, Animating, AnimSeq, PlayAnim.

Example

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

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

; Scrub the Walk clip by hand, the way a cutscene or a replay would
walk=FindAnimSeq(fox,"Walk")

frame#=0
scrub=1

While Not KeyDown(1)

    ; Space swaps between hand-scrubbing and normal looped playback
    If KeyHit(57)
        scrub=1-scrub
        If scrub=0 Then Animate fox,1,0.6,walk
    EndIf

    If scrub
        ; Creep forward so there is always something to watch...
        frame=frame+0.15
        ; ...and let [ / ] drag the pose about much faster
        If KeyDown(26) Then frame=frame-1.2
        If KeyDown(27) Then frame=frame+1.2

        ; Pose the fox at an exact frame of the Walk clip
        SetAnimTime fox,frame,walk
    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,"Space: scrub / play   [ / ] : drag the pose   Arrows: camera   Esc: exit"

    If scrub
        Text 0,20,"SetAnimTime fox,"+frame+","+walk
        Text 0,40,"AnimTime "+AnimTime(fox)+" - the raw frame is wrapped into 0.."+AnimLength(fox)
    Else
        Text 0,20,"Animate is driving the clip - press Space to scrub again"
        Text 0,40,"AnimTime "+AnimTime(fox)+"   AnimLength "+AnimLength(fox)
    EndIf

    ; SetAnimTime stops playback, so Animating drops to 0 while scrubbing
    Text 0,60,"Animating(fox) = "+Animating(fox)

    Flip

Wend

End

Index