https://github.com/jevonlipsey/pico-ios
An iOS Native Emulator for the PICO-8 fantasy console. Free and Open Source. Experimental Alpha available for Android!
https://github.com/jevonlipsey/pico-ios
android apk emulation emulationonios emulator gaming ios ipa iphone javascript lowlevel pico pico8 retrogaming swift vue
Last synced: 4 months ago
JSON representation
An iOS Native Emulator for the PICO-8 fantasy console. Free and Open Source. Experimental Alpha available for Android!
- Host: GitHub
- URL: https://github.com/jevonlipsey/pico-ios
- Owner: jevonlipsey
- License: gpl-3.0
- Created: 2025-12-24T22:53:14.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-19T13:14:17.000Z (4 months ago)
- Last Synced: 2026-01-19T17:03:56.429Z (4 months ago)
- Topics: android, apk, emulation, emulationonios, emulator, gaming, ios, ipa, iphone, javascript, lowlevel, pico, pico8, retrogaming, swift, vue
- Language: JavaScript
- Homepage:
- Size: 91 MB
- Stars: 122
- Watchers: 3
- Forks: 2
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
https://github.com/user-attachments/assets/ec24f92e-d29a-4319-8293-439487d60b35
## Features
- **Native Engine**: Runs flawlessly on **iOS**, due to the official PICO-8 engine being implemented as a WASM module.
- **Quick Save & Load**: The **only** PICO-8 experience with instant save states. Freeze time and resume anywhere, across devices.
- **Adaptive Controls**: Custom Gameboy-esque controls with tactile haptics. Works in portrait and landscape. Swap to virtual joystick.
- **Smart Library**: Automatically extracts cartridge labels and metadata, presenting your collection in a polished grid.
## Under the Hood: A Rant
The core engineering challenge was **reconciling the asynchronous nature of mobile file I/O with the synchronous requirements of the Emscripten/WASM virtual file system.**
PICO-8 demands a synchronous file system. Bridging this to mobile required completely reverse-engineering the Emscripten boot sequence.
- **Bootloader Hijacking:** The engine defaults to booting the standard "JELPI" demo cart. To bypass this, I had to intercept the `Module.preRun` lifecycle, manually injecting user code into the WASM heap and forcing the pointer to the correct entry point before the runtime could initialize.
- **True State Persistence:** I architected a system that dumps the _entire simulated RAM_ into a serialized blob. I implemented **GZIP** compression to keep these memory snapshots lightweight, allowing for atomic, instant state restoration.
It’s _not_ a browser wrapper; it’s a custom runtime environment built for native mobile hardware. Enjoy the speeds!
## Tech Stack
## Installation
### iOS (Sideload)
You can sideload Pocket8 via AltStore, SideStore, or Sideloadly.
**Auto-Update Source (Recommended)**
Add the official source to **SideStore** or **AltStore** to get updates automatically (no computer needed!).
1. Copy this URL: `https://raw.githubusercontent.com/jevonlipsey/pico-ios/main/altstore.json`
2. Open SideStore/AltStore -> **Sources** -> **+** -> **Add Source**.
**Manual IPA Install**
1. Download `Pocket8.ipa` from [Releases](https://github.com/jevonlipsey/pico-ios/releases/latest).
2. Sideload via **AltStore**, **SideStore**, or **Sideloadly**.
3. Enable **Developer Mode** in iOS Settings (Settings > General > Device Management > Your Name).
### Android (APK)
1. Download `Pocket8-Android.apk` from [Releases](https://github.com/jevonlipsey/pico-ios/releases/latest).
2. Open the file on your device.
3. If prompted, allow installation from **Unknown Sources**.
_(Note: Play Protect may ask for confirmation. Click "More Details" -> "Install Anyway".)_
## Project Status
Pocket8 is developed in collaboration with **Zep (Lexaloffle)** to be the official BBS Companion app for PICO-8.
Apart from the PICO-8 engine itself, Pocket8 is a solo dev project designed to bring the community a beautiful native app for mobile.
Aiming to submit to the App Store as soon as possible!
- **iOS:** Our primary focus. Licensed as an official companion for browsing the BBS and playing carts natively.
- **Android:** Experimental Alpha. While we are supporting current testers, please note that an official Lexaloffle Android build is planned for later this year.
### Build from Source
```bash
npm install && npx cap sync
npx cap open ios # for Xcode
npx cap open android # for Android Studio
```
## How to Get Games
Pocket8 plays standard `.p8.png` PICO-8 cartridges.
### 1. Find a Game
Tap the **Globe Icon** in the app to open the [Lexaloffle BBS](https://www.lexaloffle.com/bbs/) in your browser. You can also visit [itch.io](https://itch.io/games/tag-pico-8).
### 2. Save the Cartridge
**Important:** You need the **cartridge image file**, not a ZIP or EXE.
1. Find the small square image that looks like a game cartridge (labelled "Cart").
2. **Desktop:** Right-click the image -> "Save Image As".
3. **Mobile:** Long-press the cart image -> "Save to Files" / "Download Image".
### 3. Import
Open Pocket8, tap the `+` icon, and select the `.p8.png` file you just saved.
> **Coming Soon: Tap to Play**
> I am currently collaborating with Zep (Lexaloffle) on an official integration! Soon, you will be able to hit "Play" directly on the BBS website, and it will automatically launch the game inside Pocket8. This feature is in alpha and may not work for all carts at the moment.
## License & Attribution
- **Pocket8 Source Code**: Licensed under [GPL] (c) 2026 Jevon Lipsey.
- **PICO-8 Engine**: (c) Lexaloffle Games. The engine runtime used for the iOS build is proprietary software and will **not** be included in this repository.
## Acknowledgements
- Zep ([Lexaloffle](https://www.lexaloffle.com/)): For creating the fantasy console and being awesome in general. PICO-8 is a masterpiece of design constraints, I'm so excited to bring it to mobile!
- You: For actually reading the documentation. Thanks for the support (:
