A fast, minimal retro-gaming OS for the RetroStone2 handheld, and for Raspberry Pi and Orange Pi boards.
RetroStoneOS boots straight into an EmulationStation-style menu in about two seconds, plays games from 40 systems, and switches between the built-in screen and a TV live, just by plugging HDMI in. It replaces the old RetrOrangePi stack (Armbian + RetroPie + RetroArch + EmulationStation) with one small, purpose-built system: mainline Linux, a single menu/emulation program written in C, and libretro emulator cores. There's no desktop, no X11 and no layer cake, and every setting lives in one menu.
This fork (KurdtNervanna/RetroStoneOS, branch
pro-storage) adds Ports: Doom, Cave Story and native N64 PC ports (Super Mario 64, Ocarina of Time, Majora's Mask, Star Fox 64, Mario Kart 64, GoldenEye 007, Perfect Dark, Smash 64) running on the RetroStone2's GPU, in one menu list. The native ports follow HDMI live like every emulator and work with a real N64 pad. You build them on your PC from your own ROM: how to get native ports. Its Releases update over the air (Settings > System update). The official RetroStoneOS is PaddleStroke/RetroStoneOS. What is different from the official image, and what has been sent upstream: FORK.md.
Fast
- About 2 s from power-on to the logo, and the menu about 0.3 s later. The menu is drawn from a snapshot while game lists load in the background.
- Theme art is prefetched in the background, so a system's first visit in the carousel does not stutter.
- Shutdown in about a second. Powering off during a game saves it; at the next boot the game resumes Always, Ask or Never (your choice).
Plays well
- Hardware-scaled video (pixel-perfect 2x on the RetroStone2 LCD) with audio/video sync and dynamic rate control.
- 60 Hz LCD mode, per-game core options, per-game scaling and CPU profile, save states with thumbnails, auto-save on exit.
- Each game runs in its own process: a crashing emulator can't take the menu down.
- N64 with GPU rendering and a shader cache, plus an in-game benchmark that finds the fastest settings for each game.
- Rumble on pads that have motors.
Laptop-style display switching
- Plug HDMI in and the picture moves to the TV (720p, or 640x480 for the retro look). Unplug it and it's back on the LCD, even mid-game. The native Ports do the same: they render at 640x480 and the display engine scales them to the screen in use (docs/native-games.md).
- In docked mode, the controller that starts a game becomes player 1.
Controls
- Built-in buttons and the analog stick are handled by the kernel. USB/Bluetooth pads are recognised automatically (SDL GameControllerDB).
- RetroPie hotkeys: Select+Start exit, Select+R/L save/load state, Select+Left/Right state slot, Select+X in-game menu, Select+B reset.
- Select+R2 fast-forward, Select+L2 screenshot, Select+Y game switcher (jump between your recent games, each resumed where you left it).
- Remaps per system and per game, including the RetroStone2's optional 6-button Mega Drive layout.
- Keyboard (menus): arrows move, Enter = A (open, confirm), Esc or Backspace = B (back), Tab = Select, Space = Start, X / Y, Page Up / Page Down = L / R, Home / End = L2 / R2. A keyboard is not a game controller (games need a pad or the built-in buttons), but in a game Esc opens the in-game menu (with Exit) and Tab is the hotkey button (Tab+Space exits). A Bluetooth keyboard works the same once paired (Settings > Network > Bluetooth devices); mice are not used yet.
Finding games
- Letter jump and search (in one list or across all games).
- Play time per game and a "Most played" list, next to favourites and recently played.
- Hide or delete a game from the menu.
Getting games on it
- SD card in a PC: the
RETROSTONEdrive, ready right after flashing. - USB stick: plug it in, then Import games, Export games or Back up saves. Copies are incremental, with duplicate handling.
- WiFi/Ethernet: a drag-and-drop web page (PIN-protected, with a QR code), or the Windows share
\\RETROSTONE.
Updates
- Signed over-the-air updates from Settings > System update (WiFi), or offline from a USB drive or the SD card.
- The new system goes to the other A/B slot and is checked before the switch; if it doesn't start, the console goes back to the previous one by itself. Games, saves and settings are never touched. See docs/updates.md.
Handheld care
- Battery gauge and warnings, a clean save and shutdown at critical battery, a charge-only mode, and idle dimming.
- Idle power-off: after 5 minutes without input (Settings > Power > "Power off after", or Never) the console saves the game and powers off, after a 10 s notice that any button cancels.
- Panel care on the RetroStone2: the LCD keeps receiving a picture whenever it is powered (its "screen off" is backlight off plus a black frame), which protects the panel.
- The SD card is checked after an unexpected power loss, and a hardware watchdog guards against hangs.
- The first boot can't hang on its "Preparing the SD card" screen, and it leaves a step-by-step trace (
rsos/logs/firstboot.txton the card) for bug reports. - WiFi, Bluetooth and Ethernet are off by default, so they cost no boot time or battery.
Looks
- EmulationStation theme support (drop any ES theme in
themes/). - Built-in rsos-dark and rsos-light themes with console art, plus the gbz35 themes.
- 22 languages, chosen at the first boot (English, French, German, Spanish, Italian, Portuguese, Japanese, Chinese, Korean, Russian and more).
| Family | Systems |
|---|---|
| RetroStone | 8BCraft's own games, built in: Bomber Mole, Leady Squid, Duck Parade, Blueberry Tumble, Beaver Rush, Pancake Tower and Pogo Mamie (RetroStone VC, docs/vc-games.md) |
| Nintendo | NES, Famicom Disk System, SNES, Nintendo 64, Game Boy, Game Boy Color, Game Boy Advance, Pokémon mini |
| Sega | Master System, Mega Drive/Genesis, Game Gear, SG-1000, 32X, Mega-CD, Pico |
| Sony | PlayStation |
| NEC | PC Engine/TurboGrafx-16, PC Engine CD, SuperGrafx |
| SNK | Neo Geo, Neo Geo CD, Neo Geo Pocket (Color) |
| Arcade | MAME 2003-Plus, FinalBurn Neo |
| Computers | MS-DOS (DOSBox Pure), Commodore 64, ZX Spectrum, Amstrad CPC, MSX, Atari 400/800/XL/XE |
| Game engines and ports | ScummVM, Doom (Freedoom included), Cave Story, PICO-8 (fake-08) |
| Others | Atari 2600/5200/7800/Lynx, WonderSwan (Color), ColecoVision |
Pre-installed games, so the console is fun out of the box: the RetroStone system (Bomber Mole, Leady Squid, Duck Parade, Blueberry Tumble, Beaver Rush, Pancake Tower and Pogo Mamie),
µCity (Game Boy Color, GPL-3.0+ / CC BY-SA 4.0) and Freedoom (Doom, BSD-3-Clause); see
docs/homebrew.md and docs/vc-games.md.
BIOS files go in RETROSTONE/bios/ (see docs/cores.md). No commercial games or BIOS files are included.
| Board | Defconfig | Status |
|---|---|---|
| RetroStone2 (8BCraft, Allwinner A20) | retrostone2 |
Primary target, tested |
| RetroStone1 (8BCraft, Allwinner H3) | retrostone1 |
Untested, built by CI; built-in screen (composite) compile-tested only |
| Raspberry Pi 2 (and Pi 3 / Zero 2 W in 32-bit mode) | rpi2 |
Built by CI; reported working on a Pi 3 after a config.txt change, fixed in 0.1.4 (issue #6) |
| Raspberry Pi 3 / Zero 2 W (64-bit) | rpi3_64 |
Untested, built by CI |
| Adafruit PiGRRL 2 (Pi 2 or 3, 2.8" PiTFT) | rpi2, rpi3_64 + a config.txt block |
Untested (docs/boards/pigrrl2.md) |
| Raspberry Pi 4 / 400 / CM4 | rpi4_64 |
Untested, built by CI |
| Raspberry Pi 5 / 500 | rpi5_64 |
Untested, built by CI |
| Orange Pi PC / PC Plus (H3) | orangepi_h3_pc |
Untested, built by CI |
| Orange Pi One / Lite (H3) | orangepi_h3_one |
Untested, built by CI |
| Orange Pi 5 (RK3588S) | orangepi5 |
Untested, built by CI |
The single-board computer images are built automatically by CI, and are mostly untested on the boards: they
are HDMI boxes for USB/Bluetooth pads. Please open an issue with your results! Details in docs/boards.md;
adding a board takes one folder and a board.ini profile (docs/porting.md).
- Download the image for your board from Releases.
- Flash it to a microSD card of 2 GB or more (4 GB for the Orange Pi 5) with balenaEtcher or Rufus.
- Copy your games into
RETROSTONE/roms/<system>/, from the PC (the drive appears right after flashing), from a USB stick, or over WiFi later. - Boot. The first start prepares the SD card and asks for your language, then the menu appears.
Later versions install from the console itself (Settings > System update); no reflashing needed.
RetroStoneOS is a Buildroot external tree. On Linux (or WSL2):
wget https://buildroot.org/downloads/buildroot-2026.02.3.tar.xz && tar xf buildroot-2026.02.3.tar.xz
cd buildroot-2026.02.3
make BR2_EXTERNAL=/path/to/RetroStoneOS/buildroot-external retrostone2_defconfig # or rpi4_64_defconfig, ...
make
# -> output/images/sdcard.imgThe RetroStone games build from a RetroStone VC checkout next to
this one (../RetroStoneVC; or set BR2_PACKAGE_RSOS_VC_GAMES=n, docs/vc-games.md). The menu
program also builds and tests on a PC: cd frontend && make check. Details: docs/build.md.
| build.md | Building, the SD layout, A/B slots, boot time, the release build |
| boards.md · porting.md | Supported boards; adding a board |
| cores.md | Emulators, BIOS files, ROM folders, performance |
| ui-design.md | The menu, themes, settings |
| host-design.md | The libretro game host (hotkeys, fast-forward, screenshots, game switcher) |
| input-design.md | Controls, remaps, rumble |
| display-design.md | LCD/HDMI switching and scaling |
| rom-transfer.md | USB, web page and Windows share |
| updates.md | Signed system updates (.rsu packages, keys) |
| power.md | Battery, charging, shutdown |
| native-games.md | Ports: native games, HDMI switching, N64 pad layouts |
| bluetooth-audio.md | Bluetooth headphones (A2DP): routing, pairing, what to measure |
| pro-storage.md | RetroStone2 Pro: eMMC and M.2 storage, starter card; game covers, multi-disc games, memory speed |
| translating.md | Adding or fixing a translation |
| homebrew.md | The bundled games and their licences |
| vc-games.md | The RetroStone system: 8BCraft's own games (RetroStone VC) |
| ci.md | CI, releases and the repository secrets |
| hardware-pinmap.md · kernel-patches.md | RetroStone2 hardware and kernel patches |
| bringup.md | Hardware test script (bring-up logs) |
| hardware/ | RetroStone2 schematic, PCB and Gerber files; RetroStone1 schematic and PCB |
| CONVENTIONS.md · requirements.md · review/ | Project conventions, requirements and reviews |
The RetroStoneOS code is under the MIT License. Bundled third-party components keep their own licences (the
Linux kernel and U-Boot under GPL-2.0, the emulator cores under various licences including some non-commercial ones,
the Carbon/gbz35 theme art under CC BY-NC-SA, and the RetroStone games under MIT (code) and CC BY-NC-SA 4.0 (art,
music, levels)). See LICENSE for the details, and each release's
legal-info archive for the full sources and licence texts. The hardware files in hardware/ (RetroStone2 and
RetroStone1) are open hardware under the CERN-OHL-P-2.0 (see hardware/README.md).
The images are free, for non-commercial use. RetroStoneOS is a free download and is not sold with any hardware. Its images include non-commercial emulator cores (snes9x2005/2010, PicoDrive, MAME 2003-Plus, FBNeo) and CC BY-NC-SA theme art, so an image must not be sold, and must not be preloaded on hardware that is sold (a console, an SD card or a kit). Sharing the images for free is fine.
- The RetroStone2 handheld: Pierre-Louis Boyer / 8BCraft.
- The libretro core authors, Buildroot, the linux-sunxi community and the mainline kernel developers.
- Olimex, for the original A20 HDMI audio driver work.
- Themes: rxbrad (gbz35) and Rookervik (Carbon, RetroPie).
- Antonio Niño Díaz for µCity, and the Freedoom project (see docs/homebrew.md).





