mgba_advance_frames
Step emulation by a specified number of frames synchronously to enable frame-precise input automation and timing against in-game animations. Returns the updated frame count.
Instructions
PURPOSE: Step emulation by exactly N frames synchronously and return the new frame count. USAGE: Use for frame-precise input automation (combine with mgba_press_buttons to time inputs against in-game animation), letting the system initialize after a hard reset (RAM is mostly zero in the first ~30 frames after mgba_reset), or settling state between memory reads. For long jumps (thousands of frames) prefer mgba_save_state / mgba_load_state of a pre-prepared state — advance_frames scales linearly. To resume real-time playback indefinitely instead of stepping, use mgba_unpause. Works whether emulation is currently paused or running and does NOT change the pause state. BEHAVIOR: Advances mGBA's frame clock by N frames inside the bridge's frame callback. Each step costs roughly one real frame (~16ms at 60Hz GBA / ~16.7ms at 60Hz GB) plus one bridge round-trip — so advancing 600 frames takes ~10 seconds wall-clock. This method is build-dependent on mGBA; check capabilities.frameAdvance in mgba_get_info first. Returns an error if the capability is missing on this build. RETURNS: Single line 'Advanced N frame(s). Current frame: NEW_COUNT'.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of frames to advance (≥1, default 1). Latency scales linearly: ~16ms per frame at 60Hz. New frame count = previous frame count + count. |