Recording and playing input scripts

Capture button presses to a text file, replay them deterministically. PRO

Pixl8 can record everything you press while playing a cart to a plain-text .p8.script file, then play that file back later to reproduce the exact same run frame-for-frame. The script format is human-readable, so you can also write or edit one by hand — useful for speedrun verification, screenshot pipelines, repro carts for engine bugs, or anything that benefits from deterministic input. Recording and playback are part of the Pro unlock.

Recording a script

1. Start the cart you want to record.
2. Open the pause menu and pick Record inputs. A small overlay confirms the recording has started.
3. Play normally. Every button press and release is captured against the cart's frame counter.
4. To finish, open the pause menu again and pick Stop recording. The file is written to Pixl8's scripts/ folder as <cartname>.p8.script.

Only one recording is kept per cart — recording again overwrites the previous file. Back up the old one first if you want to keep it.

Playing a script back

1. Start the cart that the recording was made for.
2. Open the pause menu and pick Playback recording.
3. The cart resumes with the script driving inputs.

Playback is fully deterministic only if nothing else changed between the recording and the playback — the same cart file, the same starting state, and no extra input from the player. Carts that read the wall clock or use rnd() seeded from time will diverge.

Editing a script

Pick Edit recording from the pause menu to open the script for the current cart in a built-in text editor. Save when you're done. You can also pull the file out via Settings → Backup and edit it on a computer if that's easier.

One handy aid for editing: turn on Settings → Show frame counter. That puts the current frame number in the upper-left whenever the cart is paused, so you can find the exact frame where something happened and edit events at that line.

Script syntax

A .p8.script file is plain text. Each non-blank line is one event group:

<frame>   <action>  [<action> ...]   # optional comment

The frame number must be non-decreasing line-to-line. Multiple actions on the same line all happen at that frame. Anything after a # is a comment.

Actions

+left  +right  +up  +down  +o  +x   press a button
-left  -right  -up  -down  -o  -x   release a button
screenshot [name]                   capture the cart's framebuffer
save                                quick-save to slot 0
load                                quick-load from slot 0
pause                               pause the cart at this frame

o and x are PICO-8's two action buttons (the round and cross faces of a gamepad). Any unrecognised token is ignored, so future events can be added without breaking older versions.

Screenshot filenames

Without a name, screenshots get a default like screenshot_<frame>.png. If you pass a name it must follow these rules — Pixl8 rejects the event otherwise:

• no slashes or path separators,
• no leading dot,
• no control characters,
• 255 characters or fewer.

Captured screenshots are sorted by cart under Settings → Manage screenshots so you can browse them after playback.

Example

# celeste.p8.script — sample run
0     +x                    # press jump on frame 0
3     -x                    # let go three frames later
60    +right                # start running right at one second
120   +x                    # jump
124   -x                    # release jump
180   -right                # stop running
240   screenshot pico_dash  # grab a screenshot at frame 240
600   pause                 # pause at frame 600 for inspection

Backing up and sharing scripts

Scripts live in the scripts/ folder inside Pixl8's data dir, and are included in Settings → Backup & Restore ZIP exports. To share a single recording, you can pull just the matching .p8.script file out of the ZIP and send it to whoever needs to replay it.

Found a quirk in playback or want a new event type? Open an issue on GitHub with a sample script and the cart it targets.