mgba_press_buttons
Append a button press to the mGBA input queue, holding buttons for a set number of frames and releasing before the next press. Drive Game Boy Advance games programmatically with precise input timing.
Instructions
PURPOSE: Append a button-press to mGBA's input FIFO — hold the given buttons for frames frames, then release for release_frames frames before the next queued press starts. USAGE: Use to drive games with input. Each call APPENDS to the queue rather than overwriting, so consecutive calls produce distinct edge events that ROMs see as separate presses (rather than one continuous hold). To press the same button twice in a row reliably, send two presses — release_frames between them gives the ROM time to detect a key-up, which most input handlers require to register the second press. To advance emulation manually (without queueing inputs), use mgba_advance_frames. To inspect input-state side effects, pause first with mgba_pause and read RAM between presses. BEHAVIOR: Modifies the bridge's input queue; the press fires asynchronously on mGBA's frame callback. The call returns immediately with the new queue size — it does NOT block until the press completes. Returns an error if buttons contains a name not in the valid-key set, or if the bridge's input handling isn't installed on this build. RETURNS: Single line 'Queued press: KEYS (hold Nf, release Mf). Queue size: K'.
Valid button names: A, B, Select, Start, Right, Left, Up, Down, R, L.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| buttons | Yes | List of button names to hold simultaneously for this press (e.g. ["A"], ["Down", "B"] for a Konami-code-style combo). Names are case-sensitive. An unknown name returns an error rather than being silently ignored. | |
| frames | No | Number of frames to hold the buttons down (at 60 fps; default 1). For a normal menu-confirm tap, 2-4 is usually plenty; for held-direction movement on slower games, increase as needed. | |
| release_frames | No | Number of frames to release ALL keys after the hold, before the next queued press fires (default 1). Increase to 2-4 if a ROM debounces input and misses back-to-back presses; this gap is what lets the ROM see two distinct edge events instead of one long hold. |