b3dAnimTime

Queries current animation playback time in seconds (returns currentTime, 0.0 if invalid entity). Takes entity (animated mesh entity handle). Returns currentTime as Double (playback position in seconds, advances each frame if playing, frozen if paused), or 0.0 if invalid entity or not animated mesh. Reads entity.animatedMesh.currentTime (internal playback position, updated by UpdateAnimations each frame). Use to query playback progress (calculate percentage complete, trigger events at specific times), synchronize animations (read one entity's time, set others to match), or display timeline (show current position in animation editor UI). CurrentTime behavior: starts at sequence startTime or 0.0 (depends on b3dAnimate or b3dAnimateSeq call), advances by speed x deltaTime each frame (if playing, automatic progression), wraps at endTime (loop mode wraps to startTime, once mode stops, pingpong mode reverses), frozen if paused (b3dPauseAnimSeq stops advancement, time preserved). Use cases: (1) Progress tracking (progress = b3dAnimTime(player) / b3dAnimLength(player) calculate percentage), (2) Event triggers (If b3dAnimTime(character) >= 1.5 Then PlayFootstepSound() trigger at 1.5 seconds), (3) Animation sync (leaderTime = b3dAnimTime(leader), b3dSetAnimTime(follower, leaderTime, 0) sync follower), (4) Timeline display (timeLabel = "Time: " + Str(b3dAnimTime(entity)) + "s" show in UI). Common patterns: progress = b3dAnimTime(entity) / (b3dAnimLength(entity) / 1000.0) percentage 0-1; event = If b3dAnimTime(char) >= eventTime And Not triggered Then TriggerEvent() one-time event; sync = For Each npc: b3dSetAnimTime(npc, masterTime, 0) where masterTime = b3dAnimTime(master). Typical values: 0.0 at start (beginning of animation or sequence), advances to duration (e.g., 0.0 -> 3.5 for 3.5 second animation), wraps in loop mode (exceeds duration, wraps back to start), negative in pingpong (reverses to negative values during backward playback, implementation detail). Time precision: Double for sub-millisecond precision (sufficient for smooth animation), typically 0.016s increments at 60 FPS (advances by deltaTime each frame, ~16ms per frame), not frame-locked (continuous time, not discrete frames). Return value 0.0 ambiguous: could mean at start of animation (valid), could mean invalid entity (error), check b3dAnimating to distinguish (if Animating and AnimTime = 0.0 then genuinely at start, if Not Animating and AnimTime = 0.0 might be invalid or stopped). Doesn't affect playback: query-only function (reads currentTime, doesn't modify), animation continues playing (or paused) as before call), safe to call every frame (minimal cost, just member variable access). Difference from b3dAnimLength: b3dAnimTime returns current position (where playback head is now, changes each frame), b3dAnimLength returns total duration (how long animation is, constant), combine both for percentage (currentTime / (length / 1000.0) since length in milliseconds, time in seconds). Validation: returns 0.0 if entity invalid (not found in g_entities map), returns 0.0 if entity not ENTITY_ANIMATED_MESH (wrong type, not animated), returns 0.0 if animatedMesh pointer null (shouldn't happen, safety check), otherwise returns currentTime (valid playback position). Related: b3dSetAnimTime sets current time (manual seek, sets the value read by this function), b3dAnimLength queries duration (total animation length, used with AnimTime for percentage), b3dAnimate starts playback (sets initial time, AnimTime tracks progress), b3dAnimateSeq alternative playback (also uses currentTime, read with this function), b3dAnimating queries playing state (returns 1 if playing, 0 if stopped, complements time query).