https://github.com/mnmlyw/pico-z
a PICO-8 emulator with save states
https://github.com/mnmlyw/pico-z
emulator fantasy-console gamedev lua pico-8 retro-gaming sdl3 zig
Last synced: about 1 month ago
JSON representation
a PICO-8 emulator with save states
- Host: GitHub
- URL: https://github.com/mnmlyw/pico-z
- Owner: mnmlyw
- License: mit
- Created: 2026-02-10T21:39:58.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-28T00:54:46.000Z (about 2 months ago)
- Last Synced: 2026-04-28T02:35:46.997Z (about 2 months ago)
- Topics: emulator, fantasy-console, gamedev, lua, pico-8, retro-gaming, sdl3, zig
- Language: Zig
- Homepage: https://mnmlyw.github.io/pico-z/
- Size: 2.49 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# PICO-Z
A PICO-8 emulator with save states. Plays `.p8` and `.p8.png` carts on macOS, Windows, Linux, and [in the browser](https://mnmlyw.github.io/pico-z/play/).
Built with Zig, ziglua (Lua 5.2), and SDL3. Web version compiles to WASM (356KB, no Emscripten).
Tested with [Celeste Classic](https://www.lexaloffle.com/bbs/?tid=2145) and other community carts.
> **Note:** PICO-Z is a player/emulator only — it does not include PICO-8's editor, splore, or game creation tools. To make games, get [PICO-8](https://www.lexaloffle.com/pico-8.php) from Lexaloffle.
## Try It
**[Play in Browser](https://mnmlyw.github.io/pico-z/play/)** — open any `.p8` or `.p8.png` cart directly in your browser. No install needed.
To get a cart to try, download [Celeste Classic](https://www.lexaloffle.com/bbs/?tid=2145) or browse the [PICO-8 BBS](https://www.lexaloffle.com/bbs/?cat=7).
## Build & Run
Requires Zig 0.15+.
```bash
zig build # build native app
zig build run -- # build and run a .p8 or .p8.png cart
zig build web # build WASM module to web/
```
## Features
- **Cart loading** — `.p8` text format and `.p8.png` image format (PNG decoding, steganographic extraction, old and PXA decompression)
- **Preprocessor** — transforms PICO-8 Lua syntax (short-if, `?` print shorthand, compound assignment incl. `^=`, `!=`, peek shortcuts, binary literals, bitwise ops) to standard Lua 5.2
- **Graphics** — pset, line, rect, circ (incl. inverted fill), oval, spr, sspr, map, tline, print (with P8SCII control codes), pal, fillp, clip, camera
- **Audio** — 4-channel waveform synthesis (8 waveforms + custom instruments), SFX effects (slide, vibrato, drop, fade, arpeggio), music pattern sequencing
- **Input** — keyboard + gamepad via SDL3, btn/btnp with repeat, mouse via stat(32-35)
- **Memory** — flat 65536-byte RAM matching PICO-8 layout (sprites, map, SFX, draw state, screen)
- **Sandbox** — Lua stdlib restricted to match PICO-8 (no io, os, debug, require, etc.)
- **Multi-cart** — `load()` to switch cartridges at runtime, `run()` to restart
- **Quick Save/Load** — press **P** to save state, **L** to load; saves full game state (RAM, audio, Lua globals) — not available in standard PICO-8
- **Cart Reload** — press **R** to reload the cart from disk without restarting the emulator
- **Drag and drop** — drop `.p8` or `.p8.png` files onto the window to load
## Downloads
- **[Web Player](https://mnmlyw.github.io/pico-z/play/)** — runs in any modern browser
- **Desktop** — pre-built binaries for macOS, Windows, and Linux on the [Releases](../../releases) page
## Controls
| Key | Action |
|-----|--------|
| Arrow keys | D-pad |
| Z / C | O button |
| X / V | X button |
| P | Save state |
| L | Load state |
| R | Reload cart from disk |
| ESC | Quit |
## Credits
PICO-Z is not affiliated with [Lexaloffle](https://www.lexaloffle.com/) or [PICO-8](https://www.lexaloffle.com/pico-8.php). PICO-8 is created by Joseph White.