b2dPlayMovie

Starts movie playback from beginning (sets playing=true, records startTime, resets currentFrame=-1, sets as active). Takes handle (movie handle from b2dLoadMovie, integer). Returns nothing. Only starts if not already playing and not paused and not finished (idempotent, safe to call multiple times), sets playing=true (movie actively playing), sets paused=false (clear any paused state), records startTime (std::chrono::steady_clock::now for frame timing), resets currentFrame=-1 (next frame will be 0), sets g_activeMovieHandle=handle (marks as active movie). Use to start movie playback (begin streaming frames from ZIP), restart movie from beginning (call after movie finished), or begin cutscene (start video playback at specific point). Playback mechanics: frame extraction on-demand (frames extracted from ZIP during b2dDrawMovie calls, not during b2dPlayMovie), timing based on fps (elapsed time determines which frame to show, frame = elapsed x fps), automatic looping if enabled (when movie.loop=true, restarts from frame 0 when reaching end), stops when finished (if not looping, sets finished=true when reaching last frame). Use cases: (1) Start cutscene (b2dPlayMovie(introMovie): While b2dMoviePlaying(introMovie): b2dDrawMovie(introMovie,x,y): b3dRenderWorld()), (2) Restart movie (b2dPlayMovie(movie) restarts from beginning even if previously played), (3) Background video (b2dPlayMovie(bgMovie): draw continuously as animated background), (4) Conditional playback (If cutsceneTriggered Then b2dPlayMovie(cutscene)). Common patterns: start = b2dPlayMovie(movie) begin playback; draw loop = While b2dMoviePlaying(movie): b2dDrawMovie(movie,x,y). Playback state: playing (movie actively advancing frames based on elapsed time), not playing (idle state, no frame advancement), paused (separate state, use b2dPauseMovie, movie remains at current frame), finished (reached end without looping, use b2dPlayMovie to restart). Timing details: uses steady_clock (monotonic time source, immune to system clock changes), startTime recorded (playback start moment, used to calculate elapsed time), frame calculation (currentFrame = floor(elapsed x fps), elapsed = now - startTime), framerate independent (movie plays at specified fps regardless of game framerate). Performance: cost zero (only sets state variables, no GPU/IO operations), deferred work (actual frame extraction happens during b2dDrawMovie calls), lightweight (safe to call every frame if needed, idempotent behavior). Validation: silently ignores if handle<=0 or not found (negative, zero, or invalid handle), only starts if not playing and not paused (prevents restarting already-playing movie), does not clear finished flag (b2dStopMovie required to clear finished state for replay). Related: b2dStopMovie stops playback (returns to idle state, resets to beginning), b2dPauseMovie pauses playback (freezes at current frame, keeps texture valid), b2dResumeMovie resumes playback (continues from paused position), b2dMoviePlaying queries state (returns 1 if playing or paused), b2dDrawMovie renders current frame (extracts frame from ZIP, advances playback).