-
Notifications
You must be signed in to change notification settings - Fork 7
Home
TreeFrogUI is a free, custom retro-emulation frontend for a range of MIPS-based Hichip handhelds.
It replaces the stock game menu with a faster, more configurable interface and significantly expands the number of supported systems and features.
TreeFrogUI combines a lightweight game browser, dozens of emulator cores, save-state support, configurable video and audio options, themes, artwork, media applications, Quick Resume, and more.
New to TreeFrogUI?
The recommended way to get started is with the TreeFrogUI Installer.Manual installation is also available through the Installation Guide.
TreeFrogUI currently supports:
Device | Support -- | -- R36SX v2.6 | ✅ Supported R36SX v2.7 | ✅ Supported R36HD / compatible R36SX clones | ✅ Supported SF3000 | ✅ Supported SF3000 HD | ✅ Supported SF3100 | ✅ Supported SF3500 | ✅ Supported GB350 | ✅ SupportedTreeFrogUI is open source and is built around several components, including:
TreeFrogUI / FrogUI — game browser and launcher;
picoarch — libretro frontend and hardware integration layer;
libretro cores — emulators for individual systems;
standalone applications and emulators;
device-specific boot integration;
device-specific patches and configuration.
TreeFrogUI integrates with the device boot process to launch its own frontend while maintaining compatibility with the underlying hardware environment.
Developers interested in building, porting, testing, debugging, or contributing can start here:
Found a bug or have an idea for TreeFrogUI?
You can also join the TreeFrogUI community on Discord:
Contributions, testing results, compatibility reports, bug reports, and documentation improvements are welcome.
When reporting a device-specific issue, please include:
your exact device model and revision;
your TreeFrogUI version;
how TreeFrogUI was installed;
what you expected to happen;
what actually happened;
clear reproduction steps;
log.txt, when applicable.
Providing detailed information makes diagnosing hardware-specific problems much easier.
TreeFrogUI is maintained independently, and supporting new handheld models often requires access to physical hardware for development and testing.
If you enjoy TreeFrogUI and would like to support its development:
➡️ Support TreeFrogUI on Ko-fi
TreeFrogUI combines multiple open-source components, and each component retains its respective license.
The TreeFrogUI frontend is based on heavily modified open-source software, while emulator cores, libraries, applications, and other included components may use different licenses.
Always refer to the complete license information before redistributing or modifying the project:
Welcome to TreeFrogUI. 🐸🎮
Enjoy your handheld, explore the available systems, customize the interface, and help make TreeFrogUI better by reporting issues and sharing your experience.
# 🐸 TreeFrogUITreeFrogUI is a free, custom retro-emulation frontend for a range of MIPS-based Hichip handhelds.
It replaces the stock game menu with a faster, more configurable interface and significantly expands the number of supported systems and features.
TreeFrogUI combines a lightweight game browser, dozens of emulator cores, save-state support, configurable video and audio options, themes, artwork, media applications, Quick Resume, and more.
New to TreeFrogUI? The recommended way to get started is with the [TreeFrogUI Installer](https://github.com/tzubertowski/TreeFrogUI-installer/releases).
Manual installation is also available through the [Installation Guide](https://github.com/tzubertowski/TreeFrogUI/blob/main/install.md).
TreeFrogUI currently supports:
| Device | Support |
|---|---|
| R36SX v2.6 | ✅ Supported |
| R36SX v2.7 | ✅ Supported |
| R36HD / compatible R36SX clones | ✅ Supported |
| SF3000 | ✅ Supported |
| SF3000 HD | ✅ Supported |
| SF3100 | ✅ Supported |
| SF3500 | ✅ Supported |
| GB350 | ✅ Supported |
A single TreeFrogUI release package supports multiple device families and automatically detects the appropriate hardware configuration at boot.
Device revisions can differ internally even when the consoles look almost identical. Always make sure you are installing TreeFrogUI for a supported device and follow the installation instructions carefully.
The recommended way to install TreeFrogUI is by using the official TreeFrogUI Installer.
The installer guides you through the installation process and handles the required device-specific setup, making it the easiest installation method for most users.
It is available for:
- Windows
- Linux
- macOS
➡️ [Download the TreeFrogUI Installer](https://github.com/tzubertowski/TreeFrogUI-installer/releases)
For most users, the TreeFrogUI Installer should be the first choice.
TreeFrogUI should be installed on a freshly prepared SD card.
Installing it directly over the factory/preinstalled system may cause problems such as:
- missing or broken audio;
- incorrect controls;
- display issues;
- crashes;
- boot failures.
Whenever possible, keep a backup of your original SD card before making any changes.
Using a separate, good-quality SD card for TreeFrogUI is strongly recommended.
Manual installation is available for advanced users or situations where the installer cannot be used.
➡️ [Manual Installation Guide](https://github.com/tzubertowski/TreeFrogUI/blob/main/install.md)
Unless you specifically need the manual process, use the official installer instead.
For most users, getting started with TreeFrogUI looks like this:
- Identify your exact device model.
- Back up your original SD card.
- Get a fresh SD card for TreeFrogUI.
- Download the [TreeFrogUI Installer](https://github.com/tzubertowski/TreeFrogUI-installer/releases).
- Follow the installer instructions and select the appropriate device when prompted.
- Insert the prepared SD card into your console.
- Boot TreeFrogUI.
- Copy your games into the appropriate folders under
roms/. - Add any required BIOS or firmware files.
- Customize themes, artwork, emulator options, and other preferences as desired.
For users who cannot use the installer:
➡️ [Manual Installation Guide](https://github.com/tzubertowski/TreeFrogUI/blob/main/install.md)
TreeFrogUI is more than a replacement game list. It provides a complete frontend and emulation environment designed specifically for supported handhelds.
TreeFrogUI supports dozens of emulator cores and systems, including:
- NES / Famicom
- SNES / Super Famicom
- Game Boy
- Game Boy Color
- Game Boy Advance
- Mega Drive / Genesis
- Sega Master System
- Game Gear
- Sega CD
- PlayStation 1
- PC Engine / TurboGrafx-16
- Neo Geo
- Arcade systems
- Atari systems
- Commodore Amiga
- Commodore 64
- MSX
- ZX Spectrum
- DOS / PC
- PICO-8
- Doom
- Quake
- Cave Story
- Arduboy
- and many more
See the complete system and emulator mapping here:
➡️ [Supported Systems and Cores](https://github.com/tzubertowski/TreeFrogUI/blob/main/cores.md)
TreeFrogUI includes features such as:
- configurable emulator core options;
- in-game saves;
- save states;
- Quick Resume;
- automatic save/load support;
- Recent Games;
- optional OnionOS-style Game Switcher;
- favourites;
- play-time statistics;
- screenshots;
- fast-forward;
- rewind;
- configurable display scaling;
- configurable audio and video settings;
- customizable themes;
- multiple menu layouts;
- system icons;
- background theme packs;
- custom fonts;
- custom wallpapers;
- box art;
- title-screen artwork;
- screenshots;
- USB / OTG game libraries;
- offline updates.
TreeFrogUI also provides applications beyond emulation, including:
- 📖 Ebook reader
- 🎬 Video player
- 🎵 Music player
- 🖼️ Image viewer
- 🎧 Rockbox support
Games are stored inside the roms/ directory on your SD card.
The folder name determines which emulator or system TreeFrogUI uses.
For example:
roms/
├── FC/
│ └── Super Mario Bros.nes
├── SFC/
│ └── Super Mario World.sfc
├── GBA/
│ └── Advance Wars.gba
├── gb/
│ └── Tetris.gb
├── MD/
│ └── Sonic.md
└── PS/
├── Game.bin
└── Game.cue
Common examples:
| Folder | System |
|---|---|
FC |
NES / Famicom |
SFC |
SNES / Super Famicom |
GBA |
Game Boy Advance |
gb |
Game Boy / Game Boy Color |
MD |
Mega Drive / Genesis |
GG |
Game Gear |
PS |
PlayStation 1 |
pce |
PC Engine |
amiga |
Commodore Amiga |
c64 |
Commodore 64 |
m2k |
MAME 2000 |
pico8 |
PICO-8 |
Some systems support multiple folders or alternative emulator cores.
➡️ [Full ROM Folder and Emulator Mapping](https://github.com/tzubertowski/TreeFrogUI/blob/main/README.md#rom-folder-setup)
Arcade emulators generally require ROM sets matching the specific emulator/core version.
In most cases, arcade .zip files should remain zipped.
Using the wrong ROM set may result in:
- games not launching;
- missing files;
- incorrect graphics;
- missing audio;
- crashes.
See the dedicated arcade documentation:
➡️ [Arcade Setup Documentation](https://github.com/tzubertowski/TreeFrogUI/blob/main/docs/cores/arcade.md)
Some systems require additional BIOS or firmware files to work correctly.
Common examples include:
- PlayStation 1
- Game Boy Advance
- Sega CD
- Famicom Disk System
- Neo Geo
- Commodore Amiga
- Atari ST
- Odyssey² / Videopac
- PC-FX
- PC-88
BIOS files are typically stored in:
cubegm/bios/
Some emulator cores may have different requirements, so check the individual core documentation when necessary.
TreeFrogUI does not provide proprietary BIOS files, commercial ROM sets, or copyrighted game data that must be supplied by the user. Only use files you have the legal right to use.
For most libretro-based systems, SELECT acts as the function key.
| Shortcut | Action |
|---|---|
SELECT + START |
Open the in-game menu |
SELECT + R2 |
Save state |
SELECT + L2 |
Load state |
SELECT + R1 |
Fast-forward |
SELECT + B |
Hold to rewind |
SELECT + L1 |
Take a screenshot |
Fast-forward and rewind may need to be enabled through the emulator's Audio and video options.
Some standalone emulators use their own menus and shortcut systems.
TreeFrogUI is highly customizable.
You can change:
- color themes;
- menu styles;
- system icon packs;
- background theme packs;
- per-system backgrounds;
- wallpapers;
- fonts;
- box art;
- screenshots;
- title-screen artwork;
- display scaling.
See the complete customization documentation:
➡️ [Customization Guide](https://github.com/tzubertowski/TreeFrogUI/blob/main/theme.md)
Artwork can be placed alongside ROM collections using .res directories.
For example:
roms/GBA/Advance Wars.gba
roms/GBA/.res/Advance Wars.png
Artwork can be used to display game covers, screenshots, title screens, and other visual assets inside TreeFrogUI.
TreeFrogUI can use a FAT32 USB / OTG drive as a separate game library on supported hardware.
A typical external drive looks like:
roms/
├── GBA/
├── FC/
├── SFC/
├── PS/
└── ...
The external library can then be selected as a game source from TreeFrogUI.
See the complete guide:
➡️ [USB / OTG Storage Guide](https://github.com/tzubertowski/TreeFrogUI/blob/main/docs/otg-storage.md)
Display capabilities differ between device families.
Depending on the device and emulator, TreeFrogUI provides scaling options such as:
- Integer scaling
- Native scaling
- Fill
- Aspect-ratio scaling
Some device families have different scaling capabilities because of their display hardware and stock display drivers.
See the dedicated documentation:
➡️ [Display Scaling Guide](https://github.com/tzubertowski/TreeFrogUI/blob/main/docs/display-scaling.md)
TreeFrogUI supports offline updates on compatible installations.
Typically, updating involves:
- Download the official
update.zip. - Copy it to the root of the SD card.
- Safely eject the card.
- Insert it into the console.
- Boot the device.
- Allow TreeFrogUI to verify and apply the update.
Updates are designed to preserve personal content such as:
- ROMs;
- BIOS files;
- saves;
- save states;
- screenshots;
- favourites;
- recent games;
- play-time data;
- personal media.
Some older installations may require a full or manual upgrade before the automatic update system can be used.
➡️ [Latest TreeFrogUI Releases](https://github.com/tzubertowski/TreeFrogUI/releases/latest)
➡️ [Release Notes](https://github.com/tzubertowski/TreeFrogUI/blob/main/release-notes.md)
If TreeFrogUI does not boot or behaves unexpectedly, first verify:
- you are using a supported device;
- you selected the correct device during installation;
- the SD card was prepared correctly;
- you did not install TreeFrogUI over the factory/preinstalled system;
- required BIOS files are present;
- ROMs are inside the correct folders;
- the SD card itself is working correctly.
Logging is disabled by default to avoid unnecessary writes to the SD card.
To enable diagnostic logging:
- Power off the console.
- Insert the SD card into your computer.
- Create an empty file named:
log.txt
at the root of the SD card, next to directories such as:
cubegm/
frogui/
roms/
- Put the SD card back into the console.
- Boot the device.
- Reproduce the problem.
- Remove the SD card and inspect
/log.txt.
The log can provide useful information about:
- the boot process;
- detected hardware;
- device configuration;
- display initialization;
- application startup;
- emulator crashes.
Delete log.txt afterwards to disable logging again.
The following resources provide more detailed information about TreeFrogUI:
TreeFrogUI is open source and is built around several components, including:
- TreeFrogUI / FrogUI — game browser and launcher;
- picoarch — libretro frontend and hardware integration layer;
- libretro cores — emulators for individual systems;
- standalone applications and emulators;
- device-specific boot integration;
- device-specific patches and configuration.
TreeFrogUI integrates with the device boot process to launch its own frontend while maintaining compatibility with the underlying hardware environment.
Developers interested in building, porting, testing, debugging, or contributing can start here:
➡️ [TreeFrogUI Repository](https://github.com/tzubertowski/TreeFrogUI)
➡️ [Developer Documentation](https://github.com/tzubertowski/TreeFrogUI/tree/main/docs/dev)
Found a bug or have an idea for TreeFrogUI?
➡️ [Open a GitHub Issue](https://github.com/tzubertowski/TreeFrogUI/issues)
You can also join the TreeFrogUI community on Discord:
➡️ [TreeFrogUI Discord](https://discord.gg/JYFsmBYFBd)
Contributions, testing results, compatibility reports, bug reports, and documentation improvements are welcome.
When reporting a device-specific issue, please include:
- your exact device model and revision;
- your TreeFrogUI version;
- how TreeFrogUI was installed;
- what you expected to happen;
- what actually happened;
- clear reproduction steps;
-
log.txt, when applicable.
Providing detailed information makes diagnosing hardware-specific problems much easier.
TreeFrogUI is maintained independently, and supporting new handheld models often requires access to physical hardware for development and testing.
If you enjoy TreeFrogUI and would like to support its development:
➡️ [Support TreeFrogUI on Ko-fi](https://ko-fi.com/proszty)
TreeFrogUI combines multiple open-source components, and each component retains its respective license.
The TreeFrogUI frontend is based on heavily modified open-source software, while emulator cores, libraries, applications, and other included components may use different licenses.
Always refer to the complete license information before redistributing or modifying the project:
➡️ [License and Attribution](https://github.com/tzubertowski/TreeFrogUI/blob/main/LICENSE.md)
- 🐸 [TreeFrogUI GitHub Repository](https://github.com/tzubertowski/TreeFrogUI)
- 🧰 [TreeFrogUI Installer](https://github.com/tzubertowski/TreeFrogUI-installer/releases)
- ⬇️ [Latest TreeFrogUI Release](https://github.com/tzubertowski/TreeFrogUI/releases/latest)
- 📖 [Manual Installation Guide](https://github.com/tzubertowski/TreeFrogUI/blob/main/install.md)
- 🎮 [Supported Systems and Cores](https://github.com/tzubertowski/TreeFrogUI/blob/main/cores.md)
- 🐛 [Issues](https://github.com/tzubertowski/TreeFrogUI/issues)
- 💬 [Discord Community](https://discord.gg/JYFsmBYFBd)
- ☕ [Ko-fi](https://ko-fi.com/proszty)
Welcome to TreeFrogUI. 🐸🎮
Enjoy your handheld, explore the available systems, customize the interface, and help make TreeFrogUI better by reporting issues and sharing your experience.