b3dGetCurrentFrame

Returns current animation frame of animated entity. Takes entity (entity handle from b3dLoadAnimMesh or other animated mesh loading function with skeletal animation data). Returns current animation frame as Int (0-based frame index in current animation sequence, 0 = first frame, increments over time as animation plays).

Animation frames: skeletal animation consists of frames (each frame = specific bone pose at time point, frames play in sequence for smooth animation), frame index indicates current playback position (frame 0 = animation start, frame N = current position in sequence). Current frame: updates automatically as animation plays (incremented based on animation speed and elapsed time), wraps or clamps at animation end depending on loop settings.

Use cases: (1) Sync game events with animation (trigger footstep sound at specific walk animation frame), (2) Animation blending (transition between animations at specific frames), (3) Debug animation (display current frame for troubleshooting), (4) Animation scripting (check if animation reached specific frame to trigger action). Common patterns: event triggering (if b3dGetCurrentFrame(player) = walkStepFrame then playFootstepSound), animation complete check (if b3dGetCurrentFrame(entity) >= lastFrame then startNextAnimation).

Frame timing: frame increments based on animation speed (faster speed = more frames per second, slower speed = fewer frames per second), independent of rendering FPS (animation timing based on elapsed time, not render frames). Animation looping: looping animations wrap frame to 0 after last frame (continuous cycle, current frame resets), non-looping animations clamp to last frame (stays at end when complete).

Validation: returns 0 or -1 if entity invalid or has no animation data, returns current frame index if entity has active animation. Performance: O(1) operation (simple property read, no computation cost).

Related: b3dLoadAnimMesh loads skeletal animated mesh (entity must have animation data for this function to work), b3dAnimate controls animation playback (sets speed, sequence, loop mode), b3dAnimSeq sets animation sequence (determines which animation playing and frame range).