boxshelf-beta README

The project's README from github.com/sassiestrhihno/boxshelf-beta. As one markdown file: README.md.

Boxshelf beta

⬇ Download the latest release · Source code (GPL-3.0) · Source zip of the latest version

Boxshelf is a TV-style launcher for your emulators, Steam games and media apps. Your games sit on a 3D shelf with real box art: you can flip a case, open it, take the disc out, read the manual, and walk the whole collection in the Museum. One controller runs everything.

This is a public beta for Windows, Android (made for the AYN Thor and its two screens) and, as an experimental first build, Linux / Steam Deck. Thank you for trying it: please tell us what breaks.

Source code: Boxshelf is open source (GPL-3.0). The full source is at github.com/sassiestrhihno/boxshelf-source.

Download

Every build is on the Releases page. Each release lists what changed and what's known to be broken.

Your device File
Windows 10 / 11 PC Boxshelf-<version>-windows.zip
Android, including the dual-screen AYN Thor (both screens) Boxshelf-<version>-android-thor.apk
Linux / Steam Deck (experimental) Boxshelf-<version>-linux.AppImage

Boxshelf doesn't include or download any games, BIOS files or keys: you need the emulators and games you already own.

Want to read or build the code? It's in boxshelf-source.

Install on Windows

  1. Unzip the download into a folder of its own, for example Documents\Boxshelf. It's portable: it doesn't install anything, and deleting the folder removes it.
  2. Run Boxshelf.exe.
  3. Windows may show "Windows protected your PC": the beta isn't code-signed yet. Click More info, then Run anyway.
  4. The setup wizard opens. Click Find my emulators and games (or I'll pick them myself), tick the consoles you play, then Open Boxshelf.

You need: Windows 10 or 11 (64-bit).

Install on Android (AYN Thor)

  1. Open the .apk on your device. The first time, Android asks to allow installs from your browser or file manager.
  2. Open Boxshelf. Setup finds the emulator apps you have installed and asks for your games folders.
  3. Box art downloads in the background into a Boxshelf Art folder next to your games.

On the Thor the bottom screen shows the game you're on with its buttons (Settings → Display → Bottom screen turns it off). You need: Android 7 or newer.

Install on Linux / Steam Deck (experimental)

  1. Put the .AppImage somewhere like ~/Applications and make it executable (right-click → Properties → Permissions, or chmod +x).
  2. Run it (on a Steam Deck, in Desktop Mode). Settings are kept in ~/Boxshelf.
  3. It finds emulators installed as programs, Flatpaks or AppImages (EmuDeck and RetroDECK included) and your games in ~/Emulation/roms, ~/retrodeck/roms or on your SD card.

Not there yet on Linux: the Home menu and quit combo during a game (quit from the emulator's own menu), the power menu, and Steam Deck Gaming Mode (untested). On Ubuntu 24.04 you may need to start it with --no-sandbox.

Supported systems

GameCube, Wii, Wii U, Switch, Switch 2, PSP, PS2, PS3, PS4, PS5, Xbox 360 and 3DS; PlayStation, NES, SNES, N64, Game Boy, Game Boy Color, Game Boy Advance, DS, Mega Drive / Genesis, Master System, Game Gear and Dreamcast (through RetroArch or their best standalone emulators); plus Steam and the Stremio and Nuvio media apps. Each system uses the emulator you choose for it in setup (setup and Settings have a button to each emulator's official download page). Which consoles and emulators are available depends on the platform.

PC games: your Steam and Epic Games libraries share the PC shelf. Recomps, PC ports and any other program go on a Custom shelf: add them in Settings → Custom games, and everything installed with Quiver Launcher shows up there by itself.

The easiest layout keeps everything beside Boxshelf (the wizard finds it on its own):

Boxshelf\
  Boxshelf.exe
  Dolphin\  Cemu\  Eden\  PPSSPP\  PCSX2\  RPCS3\  shadPS4\  Xenia\  Azahar\     (your emulators)
  ROMS\Gamecube  ROMS\Wii  ROMS\Switch  ROMS\PS2  ...                           (your games)

Emulators and games anywhere else work too: choose their folders in setup or Settings.

Controls

Action Keyboard Controller
Browse ← → D-pad / left stick
Change shelf ↑ ↓ LT / RT
Play / Open Enter A
Back Esc B
Flip the box F Y
Details I X
Inspect (open the case, read the manual) V Click the right stick
Quick menu (theme, sounds, sort, power) the ☰ button Start / Menu (☰)
Settings S View / Back (hold it for the Museum)
Quit a game Hold L3 + R3 (changeable in Settings)

Report a problem

  1. In Boxshelf, open Settings → System → Report a problem → Create. It saves a zip on your Desktop with the log, your settings and your PC's graphics details. Passwords, API keys and your RetroAchievements name are removed, and your user folder is replaced with ~.
  2. Open a new issue here, say what happened and what you expected, and attach the zip.

Screenshots or a short video help a lot.

Good to know

See KNOWN-ISSUES.md for what's already known, and THIRD-PARTY-NOTICES.md for the open-source parts Boxshelf uses.

Boxshelf is free software under the GNU GPL v3.0. The source code is at boxshelf-source.

boxshelf-beta (sassiestrhihno/boxshelf-beta)

Searching Database…

What is this?Boxshelf is a TV-style launcher for your emulators, Steam games and media apps. Your games sit on a 3D shelf with real box art, and one controller runs everything.
Is it an emulator itself or just a front end?Just a front end. It launches the emulators and games you already have and doesn't include or download any games, BIOS files or keys.
How do I get it running?On Windows, unzip the download into its own folder and run Boxshelf.exe. On Android, open the APK and allow installs. On Linux, make the AppImage executable and run it. The setup wizard then finds your emulators and games.
What do I need beforehand?Windows 10 or 11 (64-bit), or Android 7 or newer, plus the emulators and games you already own. On Linux, setup can find emulators installed as programs, Flatpaks or AppImages.
Any catches I should know about?The beta isn't code-signed, so Windows warns on first run and you need to click More info, then Run anyway. On Linux the Home menu, the quit combo during a game and the power menu are missing, and Steam Deck Gaming Mode is untested.
Which platforms does it run on?Windows 10 and 11 as a portable zip, Android as an APK (made for the AYN Thor), and Linux / Steam Deck as an experimental AppImage.
Does it send my data anywhere?Your settings and play history stay on your device. It has no accounts, ads or tracking, and it only goes online for box art, manuals, achievements and the update check.
Is it free to use?Yes. It's free software under the GNU GPL v3.0, and the source code is on GitHub.
What does the 3D shelf actually let me do with a game?You can flip a case, open it, take the disc out, read the manual, and walk the whole collection in the Museum.
Can it show games from Steam, Epic and other launchers?Yes. Steam and Epic libraries share the PC shelf, and anything installed with Quiver Launcher shows up on a Custom shelf automatically.
Does the AYN Thor's bottom screen do anything useful?It shows the game you're on along with its buttons. Settings → Display → Bottom screen turns that off if you don't want it.
Where does the box art come from?Only if you opt in, box art and manuals download from libretro thumbnails, LaunchBox, GameTDB, the Super Mario Wiki and the Internet Archive, among others.
Size
<0.1 MB
Stars
955
Updated
CommitNov 14
Age
13d
Commits · 90 Days