Track play sessions on Batocera with retroshelf
Install the retroshelf plugin on Batocera (ARM handhelds and x86_64 PCs) and send your play sessions to your collection.
What you need
Install the plugin
Download the plugin
There are two downloads. Pick the one that matches your hardware:
- arm64 for ARM handhelds (Retroid, Anbernic RG353/RK3326 devices)
- amd64 for x86_64 PCs and handhelds
Extract into the Ports folder
Extract the zip into /userdata/roms/ports/ so that retroshelf.sh sits next to a retroshelf/ folder.
/userdata/roms/ports/retroshelf/
Refresh the games list
Open the Start menu, go to Games settings › Update gamelists, or simply reboot the device. retroshelf then appears in the Ports category.
Launch and link
Make sure Wi-Fi is enabled in the EmulationStation network settings, then open retroshelf from the Ports category. You'll see a 6-character code.
On your phone or computer, go to retroshelf.org/link and enter the code. The app links your device automatically. On this first launch, retroshelf also installs the hook that records your sessions.
Play games
Play normally. When you leave a game, retroshelf syncs the session if your device is online. You can also open retroshelf any time to sync manually.
How sync works
Session hook
A hook installed on first launch records every game start and stop, so sessions are captured without any manual tracking.
Works offline
No Wi-Fi? Sessions queue on the device and sync the next time you're connected.
Automatic sync
After setup, new sessions sync when you finish a game. You can still open retroshelf to sync manually.
Clock-jump protection
If the device clock jumps, retroshelf skips sessions that clearly cannot be right, like runs longer than 12 hours.
Compatible devices
The retroshelf plugin works on Batocera devices with Wi-Fi. These are currently supported:
AYN Technologies
Bittboy / Miyoo / Wolsen
CHI
PowKiddy
Retroflag
Retroid
Don't see your device? Batocera runs on a wide range of hardware. If it runs Batocera and has Wi-Fi, the plugin should work. Pick the arm64 or amd64 download to match.
Ready to start?
Set up in under 5 minutes
Download the plugin and link your Batocera device.
FAQ
Which Batocera download do I need?
There are two: arm64 for ARM handhelds (Retroid, Anbernic RG353/RK3326 devices) and amd64 for x86_64 PCs and handhelds. Pick the one that matches your hardware.
Does the retroshelf plugin need Wi-Fi to track play time?
Wi-Fi is only needed to link and sync. When you're offline, sessions queue on the device and sync automatically the next time you're connected.
How does retroshelf record sessions on Batocera?
The first time you launch retroshelf, it installs a small hook that Batocera runs whenever a game starts or stops. The hook records each session locally, and retroshelf syncs it to your collection.
Do I need to refresh the games list after installing?
Yes. Batocera only picks up new Ports entries after you update the gamelists (Start menu → Games settings → Update gamelists) or reboot the device.
How do I uninstall the retroshelf plugin?
To unlink, go to Settings on retroshelf and revoke the device. To uninstall, first run retroshelf/bin/retroshelf-uninstall.sh to remove the game hook and synced state (add --keep-data if you plan to reinstall), then delete retroshelf.sh and the retroshelf/ folder from /userdata/roms/ports/.
Related