Using the debugger

Source-level debugger for PICO-8 carts. PRO

Pixl8 ships a real source-level debugger that runs alongside the cart: step through Lua a line or a statement at a time, set breakpoints, inspect variables and locals, evaluate expressions in the running coroutine, and read a colourised view of the cart's source. The debugger is part of the Pro unlock.

Opening the debugger

While the cart is running:

1. Open the pause menu.
2. Pick Exit to console to drop into the Pixl8 shell.
3. Type debug and press Enter. The cart pauses on the next Lua line it executes, and the screen splits to show the debug pane.

The dual-pane layout

Once the debugger is active the surface splits in two — the cart's 128×128 framebuffer on one side, the debug pane (256×256) on the other. The debug pane shows:

• A colourised view of the cart's source code, with the current line highlighted and breakpoints marked.
• A prompt line at the bottom for typing commands.
• Output from print, locals, bt, etc.

Syntax highlighting follows the VS Code Dark Modern scheme: keywords in purple, strings in orange, numbers in green, built-in PICO-8 calls in bright green, with rainbow brackets to help track nesting on dense expressions.

Put the debug pane on a separate screen

If your phone is plugged into an HDMI display, Samsung DeX, or casting to a monitor, you can keep the cart full-size on the phone and route the debug pane to the external display instead. Toggle this in Settings → Debug on external display before opening the debugger. The option is only enabled when Android reports a secondary display attached.

Commands

Type any of these at the debugger prompt. Most have a short and long form — both work. Pressing Enter on an empty line repeats the previous command, which is the fastest way to step through code.

Stepping

s, step [n]      step into — n lines (default 1)
si               step a single statement (sub-line)
n, next [n]      step over — runs called functions to return
c, cont [n]      continue, stopping at the n-th breakpoint hit

Breakpoints

b <n>            set a breakpoint at line n
d <n>            delete breakpoint at line n
bl               list all active breakpoints

Code view

l, list [n]      jump the source view to line n
/<text>          search forward for <text> in the source

Inspect state

p, print <expr>  evaluate <expr> against the running coroutine
|, lua <code>    execute arbitrary lua in the cart's environment
locals           show the local variables in the current frame
bt, backtrace    print the call stack with line numbers

Leaving

q, quit          exit the debugger and resume the cart normally

Keyboard shortcuts

• Enter on an empty prompt repeats the previous command.
• ↑ / ↓ walks back and forward through the last commands you typed — a 32-slot history. Press Enter to re-run, or edit before sending.
• Page Up / Page Down scrolls the source view a screen at a time.
• Ctrl + ↑ / ↓ scrolls one line.
• ← / → on an empty prompt scrolls the source horizontally (useful for long lines).

Tips

• si is for stepping inside a single line that has several statements separated by ; or multiple expressions in a chain. s moves a whole line at a time, which is usually what you want.
• p reads any Lua expression — globals, locals, table fields, function calls. It's the quickest way to confirm a value without editing the cart.
• lua can be used to change state — assign a variable, force a flag, spawn an entity — and the cart picks it up when you resume.
• Breakpoints persist for the cart while Pixl8 is open. They clear when you load a different cart or reboot the engine.

Limitations

The debugger steps and breakpoints are tied to the source lines stored in the cart. Many published PICO-8 carts are heavily minified before release — whitespace stripped, identifiers shortened to single letters, multiple statements crammed onto each line — to squeeze under the token / char limits. On those carts, the experience suffers in two ways:

• A single source line might hold dozens of statements, so step can move much further per press than feels intuitive, and si may not break exactly where you'd expect.
• Short, machine-generated names (a, _1, f0) make locals and print output very hard to read.

If you're debugging your own cart, work against the pre-minify source — keep the readable version around and point Pixl8 at that one while you're hunting a bug. Save minification for the release build only. If you're debugging someone else's cart, an un-minified source is often available on the cart's BBS thread; if not, the debugger will still work, just with less precision.

Found a bug in the debugger or want a feature added? Open an issue on GitHub.