Skip to content
RetroGameSetsPublic

About

Multi Platforms Games Download Center . This repository is not affiliated with Batocera, Retrobat or Pixel Nostalgia RGS

Resources

Stars

449 stars

Watchers

18 watching

Forks

Latest commit

ย 

History

483 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

๐ŸŽฎ Retro Game Sets Xtra (RGSX)

Discord Support โ€ข Installation โ€ข French Documentation โ€ข Turkish Documentation โ€ข Troubleshoot / Common Errors โ€ข

A free, user-friendly ROM downloader for Batocera, Knulli, and RetroBat with multi-source support.

RGSX Web platform list RGSX application platform grid

RGSX global game search RGSX controller controls help

RGSX grid layout settings RGSX ROM folder browser

RGSX download history RGSX Web settings

RGSX ROM source choice RGSX ScreenScraper game details


๐Ÿš€ Installation

Quick Install (Batocera / Knulli / dArkOS)

SSH or Terminal access required:

curl -L bit.ly/rgsx-install | sh

After installation:

  1. Update game lists: Menu > Game Settings > Update game list
  2. Find RGSX under PORTS or Homebrew and ports

On dArkOS, the same command runs the dArkOS installer and EmulationStation restarts by itself: see dArkOS below.

Manual Install (All Systems)

  1. Download: RGSX_full_latest.zip
  2. Extract:
    • Batocera/Knulli: Extract ports folder to /roms/
    • RetroBat: Extract both ports and windows folders to /roms/
  3. Refresh: Menu > Game Settings > Update game list

dArkOS / dArkOSRE / dArkOSen (R36S and clones)

Install script (recommended): tools/install_darkos.sh downloads the latest release, installs RGSX in /roms/ports (or /roms2/ports with a second SD card), adds RGSX to gamelist.xml without touching your other ports (a backup is saved as gamelist.xml.rgsx-backup), then restarts EmulationStation. Run it the same way to update.

  • Over SSH (ssh ark@IPADDRESS, password ark; enable SSH with Options > Enable Remote Services):
    curl -L bit.ly/rgsx-install | sh
    Without curl: wget -qO- bit.ly/rgsx-install | sh
  • From the menu: copy install_darkos.sh to /roms/tools/, then start it from Options in EmulationStation.
  • A local zip or folder also works: bash install_darkos.sh /path/to/RGSX_full_latest.zip

Manual install: copy ports/RGSX from RGSX_full_latest.zip to /roms/ports/, and RGSX.png / RGSX.mp4 into /roms/ports/images/ and /roms/ports/videos/. Merge the folders, never replace them: they also hold your other ports. Do not copy a gamelist.xml over yours. dArkOS only lists launchers placed directly in ports/, so also create /roms/ports/RGSX.sh:

printf '#!/bin/bash\nexec "$(dirname "$0")/RGSX/RGSX.sh" "$@"\n' > /roms/ports/RGSX.sh

Then restart EmulationStation.

Notes:

  • The R36S has no built-in WiFi. Plug a USB WiFi dongle into the OTG port and connect from Options > Wifi. RGSX shows a warning at startup when no adapter or no connection is found.
  • pygame and requests are not part of dArkOS. They are bundled in ports/RGSX/vendor_darkos (built with tools/build_darkos_vendor.sh from Debian trixie packages, linked against the system SDL2).
  • Settings and the local database are stored in /home/ark/.config/rgsx (ext4), not on the exFAT ROM card. Media Manager covers can take a lot of space, so they go to the ROM card: /roms/rgsx/media (or /roms2/rgsx/media).
  • When games were added during the session, EmulationStation restarts automatically after you quit RGSX so they show up.
  • The A/B button swap (EmulationStation's "SWITCH A/B BUTTONS IN EMULATIONSTATION" option, or the dArkOSen Button Mapper) is applied automatically when RGSX starts.
  • Torrent downloads are not available on ARM devices yet.

Manual Update (if automatic update failed)

Download and extract the latest release: RGSX_full_latest.zip

Installed paths:

  • /roms/ports/RGSX (all systems)
  • /roms/windows/RGSX (RetroBat only)

๐ŸŽฎ Usage

First Launch

  • Syncs the systems and games catalog into a local SQLite database
  • Downloads the images needed by the interface
  • Auto-configures controls if your controller is recognized
  • Controls broken? Delete /saves/ports/rgsx/controls.json and restart

Retrobat / first Windows launch

  • It is recommended to launch RGSX Retrobat.bat manually once, outside the Retrobat interface, to verify that everything is working.
  • Allow Windows firewall prompts when they appear, especially for qBittorrent on first launch.
  • Retrobat hides some system windows by default, so a first manual launch helps avoid missing an important prompt.
  • The launcher then configures a local rule for the embedded qBittorrent binary and for the TCP 18572 WebUI.

Keyboard Mode: When no controller is detected, controls display as [Key] instead of icons.

Pause Menu Structure

Root menu โ€” Games, Language, Controls, Display, Settings, Support, Reset Default Settings, and Quit.

  • Games: refresh the catalog, scan locally owned ROMs, open download history, show/hide unsupported systems, and choose visible platforms.
  • Controls: view the currently mapped actions or remap keyboard/controller inputs.
  • Display: choose from eight grids (3ร—3, 3ร—4, 4ร—3, 4ร—4, 5ร—4, 6ร—4, 6ร—6, or 8ร—6), adjust UI and footer font sizes separately, choose a font (Pixel, Bell Centennial, or DejaVu Sans), background theme, and Light Mode. Monitor selection appears only when multiple displays are detected; window/fullscreen mode is Windows-only. You can also hide unknown-extension warnings.
  • Scrap: edit ScreenScraper credentials, open the Media Manager, and turn ScreenScraper on or off (Enable ScreenScraper / Disable ScreenScraper). While it is off, the Media Manager is blocked, running downloads are cancelled, and the preview panel is hidden. The choice is stored as screenscraper_disabled in rgsx_settings.json.
  • Settings: background music, symlink behavior, automatic extraction, ROM folder, maximum simultaneous downloads, API-key status, and connection status. Web service at boot and Custom DNS are available on Linux/Batocera.
  • Support: diagnostic tools and support archive generation.
  • Quit: quit or restart RGSX. Language selection is directly in the root menu.

ScreenScraper and Media Manager

In the game list, the local cover of the selected game appears at once if it exists. When ScreenScraper is disabled, the preview panel is hidden and nothing is fetched automatically for the game list. After the configured delay (two seconds by default: SCREENSCRAPER_PREVIEW_DELAY_SEC in config.py, or the RGSX_SCREENSCRAPER_PREVIEW_DELAY environment variable) on the same game, RGSX shows its ScreenScraper synopsis in the preview panel: it is read from the local database when already stored (games not found on ScreenScraper are stored too, so they are not queried again), otherwise it is fetched and stored. The cover is downloaded only if it is missing locally and ScreenScraper has one; a game without a cover on ScreenScraper is not asked for it again. The synopsis appears once loaded. If no information is available, the panel shows an unavailable placeholder. The preferred ScreenScraper system ID is stored per platform in the online RGSX catalog and can be edited in RGSX Sources Manager. If no ID is configured, RGSX falls back to the periodically refreshed ScreenScraper system list cached in SQLite, then to built-in aliases. A one-second hold on Confirm opens the game details page with the cover, screenshot, and synopsis. These are read first from the local media folder and the database; ScreenScraper is queried only for what is missing locally. In Pause > Scrap, the ScreenScraper username and password can be edited together; a virtual keyboard is shown only when a controller is detected, otherwise type directly, use Tab to switch fields and ENTER to confirm. A message shows the remaining quota. The account is stored in the dedicated saves/ports/rgsx/screenscraper_account.json file and can also be edited from the web interface.

The Media Manager downloads media in bulk. Its profiles are Cover (default) and Cover + Screenshot + Synopsis (max). The number of games processed at once is taken from ssuser.maxthreads, verified through ssuserInfos.php for the configured account; starting waits for this check and is blocked if the limit is missing or invalid. This thread limit is separate from the per-minute request quota, which is enforced independently. The estimate counts one API request per game and does not count direct image downloads. Platform rows show how many catalog games have at least one local image, and a small picture icon marks those games in the game list. Existing local files and synopses are reused; only missing games or media types are processed. "Not found" results are cached to avoid repeated requests. The persistent queue can be resumed after cancellation or a quota limit. The History control shortcut starts, resumes, or cancels the current job without navigating back to the first row.

In the web interface, each platform offers List and Grid views. Grid cards show the Box2D, game name, size badge, and text Download and Queue buttons on one line, followed by a synopsis preview. Clicking the image opens the enlarged Box2D with the synopsis beside it; missing media can be searched from this dialog. In List view, size and Download/Queue remain on the game row, while Box2D and Synopsis occupy a separate column at the end. The chosen view and sort order are remembered in a browser cookie, with Grid as the default. ScreenScraper searches can be retried even when a previous negative result is cached. Results use the same local cache and SQLite database as the application, and a shared lock prevents conflicts with the Media Manager. In List view, the date comes before the size/download/queue group, which stays on one line even on mobile; these controls are the same height as the Box2D and Synopsis buttons.

Local Database and Migration

The systems/games catalog, download history, locally detected owned games, ScreenScraper synopses (including "not found" answers), and related persistent state are stored in /saves/ports/rgsx/rgsx.sqlite3. The initial catalog sync downloads a full snapshot; later syncs apply changes incrementally. When a source or platform is hidden or re-enabled, RGSX reconciles the visible platform list and transfers game data only for newly visible platforms. Games > Refresh Game Catalog runs synchronization again. General preferences remain in rgsx_settings.json, and custom controls remain in controls.json.

On the first launch after upgrading from the former JSON-based storage, RGSX imports the download history, owned-game records, and torrent cache when present. Any discovered legacy cache/data files are moved to /saves/ports/rgsx/backup_old_rgsx/<date>/. Do not delete the SQLite database while RGSX is running: it contains the catalog and persistent user data. SQLite may create temporary -wal and -shm files alongside the database.


โœจ Features

  • ๐ŸŽฏ Smart System Detection โ€“ Auto-discovers supported systems from es_systems.cfg
  • ๐Ÿ“ฆ Intelligent Archive Handling โ€“ Auto-extracts archives when systems don't support ZIP files
  • ๐Ÿ”‘ Premium Unlocking โ€“ 1Fichier API + AllDebrid/Debrid-Link/Real-Debrid/TorBox fallback for unlimited downloads
  • ๐ŸŽจ Fully Customizable โ€“ Eight layouts up to 8ร—6, Pixel/Bell Centennial/DejaVu Sans fonts, font sizes (UI + footer), languages (EN/FR/DE/ES/IT/PT/TR)
  • ๐ŸŽฎ Controller-First Design โ€“ Auto-mapping for popular controllers + custom remapping support
  • ๐Ÿ” Advanced Filtering โ€“ Search by name, hide/show unsupported systems, filter platforms; with a controller, the virtual search keyboard uses the same layout as the ScreenScraper one
  • ๐Ÿ“Š Download Management โ€“ Queue system, history tracking, progress notifications
  • ๐Ÿ–ผ๏ธ ScreenScraper Media (temporarily disabled) โ€“ Delayed cover downloads, game details, screenshots, and bulk media management
  • โ™ฟ Accessibility โ€“ Separate font scaling for UI and footer, keyboard-only mode support; text is reduced before being truncated, so it stays inside its frame

๐Ÿ”‘ API Keys Setup

For unlimited 1Fichier downloads, add your API key(s) to /saves/ports/rgsx/:

  • 1FichierAPI.txt โ€“ 1Fichier API key (recommended)
  • AllDebridAPI.txt โ€“ AllDebrid fallback (optional)
  • DebridLinkAPI.txt โ€“ Debrid-Link fallback (optional)
  • RealDebridAPI.txt โ€“ Real-Debrid fallback (optional)
  • TorBoxAPI.txt โ€“ TorBox fallback (optional)

Each file must contain ONLY the key, no extra text.

Downloading Games

  1. Browse platforms โ†’ Select game
  2. Direct Download: Press Confirm
  3. Queue Download: Press X (West button)
  4. Track progress in History menu or via popup notifications

Embedded qBittorrent torrent backend

Torrent downloads now run through an embedded qBittorrent binary on both Windows and Linux/Batocera.

  • LAN debug WebUI: http://YOUR_DEVICE_IP:18572
  • Default credentials: admin / RGSXqbt
  • The RGSX web interface now includes a qBittorrent button that opens this WebUI directly.

Useful notes:

  • This WebUI is intended for debugging and advanced torrent monitoring from a phone or another PC on the same local network.
  • If LAN access to the WebUI does not work, first check the local Windows firewall.
  • Do not expose port 18572 directly to the Internet: it is the WebUI admin port, not the BitTorrent performance port.
  • If torrent connectivity is poor, prefer UPnP or forwarding the actual BitTorrent listening port configured inside qBittorrent.

๐ŸŒ Web Interface (Batocera/Knulli Only)

RGSX includes a web interface that launched automatically when using RGSX for remote browsing and downloading games from any device on your network.

Accessing the Web Interface

  1. Find your Batocera IP address:

    • Check Batocera menu: Network Settings
    • Or from terminal: ip addr show
  2. Open in browser: http://[BATOCERA_IP]:5000 or http://BATOCERA:5000

    • Example: http://192.168.1.100:5000
  3. Available from any device: Phone, tablet, PC on the same network

Web Interface Features

  • ๐Ÿ“ฑ Mobile-Friendly โ€“ Responsive design works on all screen sizes
  • ๐Ÿ” Browse All Systems โ€“ View all platforms and games
  • โฌ‡๏ธ Remote Downloads โ€“ Queue downloads directly to your Batocera
  • ๐Ÿ“Š Real-Time Status โ€“ See active downloads and history
  • ๐Ÿ–ผ๏ธ ScreenScraper Media โ€“ Select platforms, resume the queue, follow progress, and use the account's verified thread limit; existing local media is reused
  • ๐ŸŽฎ Same Game Lists โ€“ Uses identical sources as the main app

Enable/Disable Web Service at Boot, without the need to launch RGSX

From RGSX Menu

  1. Open Pause Menu (Start/ALTGr)
  2. Navigate to Settings > Web Service
  3. Toggle Enable at Boot
  4. Restart your device

Port Configuration: The web service runs on port 5000 by default. Ensure this port is not blocked by firewall rules.


๐Ÿ“ File Structure

/roms/
โ”œโ”€โ”€ ports/
โ”‚   โ”œโ”€โ”€ RGSX/
โ”‚   โ”‚   โ”œโ”€โ”€ __main__.py                # Entry point
โ”‚   โ”‚   โ”œโ”€โ”€ config.py                  # Application paths and configuration
โ”‚   โ”‚   โ”œโ”€โ”€ database.py                # Local SQLite storage
โ”‚   โ”‚   โ”œโ”€โ”€ catalog_sync.py            # Online catalog synchronization
โ”‚   โ”‚   โ”œโ”€โ”€ controls.py                # Navigation, input, and actions
โ”‚   โ”‚   โ”œโ”€โ”€ controls_mapper.py         # Control profiles and remapping
โ”‚   โ”‚   โ”œโ”€โ”€ display.py                 # Pygame interface and menus
โ”‚   โ”‚   โ”œโ”€โ”€ game_info.py               # ScreenScraper details retrieval
โ”‚   โ”‚   โ”œโ”€โ”€ media_manager.py           # Bulk media downloads
โ”‚   โ”‚   โ”œโ”€โ”€ network.py                 # Downloads
โ”‚   โ”‚   โ”œโ”€โ”€ preview.py                 # Game-list cover preview and delayed fetch
โ”‚   โ”‚   โ”œโ”€โ”€ rgsx_settings.py           # User preferences
โ”‚   โ”‚   โ”œโ”€โ”€ screenscraper.py           # ScreenScraper API client
โ”‚   โ”‚   โ”œโ”€โ”€ rgsx_web.py                # Web interface and server
โ”‚   โ”‚   โ”œโ”€โ”€ assets/                    # Profiles, images, fonts, music, and tools
โ”‚   โ”‚   โ”œโ”€โ”€ languages/                 # Translations (EN/FR/DE/ES/IT/PT/TR)
โ”‚   โ”‚   โ”œโ”€โ”€ static/                    # Web interface CSS and JavaScript
โ”‚   โ”‚   โ””โ”€โ”€ logs/                      # RGSX.log and rgsx_web.log
โ”‚   โ”œโ”€โ”€ gamelist.xml
โ”‚   โ”œโ”€โ”€ images/
โ”‚   โ””โ”€โ”€ videos/
โ””โ”€โ”€ windows/
    โ”œโ”€โ”€ RGSX Retrobat.bat              # Launcher for Windows only (can be used without retrobat too)
    โ”œโ”€โ”€ gamelist.xml
    โ”œโ”€โ”€ images/
    โ””โ”€โ”€ videos/

/saves/ports/rgsx/
โ”œโ”€โ”€ rgsx_settings.json        # User preferences
โ”œโ”€โ”€ controls.json             # Control mapping
โ”œโ”€โ”€ rgsx.sqlite3 # Catalog, history, ScreenScraper synopses, and persistent user state
โ”œโ”€โ”€ images/                   # System images
โ”œโ”€โ”€ media/                    # Cached game covers and screenshots
โ”œโ”€โ”€ screenscraper_account.json # Optional ScreenScraper account
โ”œโ”€โ”€ backup_old_rgsx/          # Legacy files archived during migration, if present
โ”œโ”€โ”€ 1FichierAPI.txt           # 1Fichier API key
โ”œโ”€โ”€ AllDebridAPI.txt          # AllDebrid API key
โ”œโ”€โ”€ DebridLinkAPI.txt         # Debrid-Link API key
โ”œโ”€โ”€ RealDebridAPI.txt         # Real-Debrid API key
โ””โ”€โ”€ TorBoxAPI.txt              # TorBox API key

The -wal and -shm files that may appear beside rgsx.sqlite3 are temporary SQLite files used while the application is running.


๐Ÿ› ๏ธ Troubleshooting

Issue Solution
Controls not working Delete /saves/ports/rgsx/controls.json + restart app, you can try delete /roms/ports/RGSX/assets/controls/xx.json too
No games or empty catalog? Open Games > Refresh Game Catalog, then check Games > Filter Platforms and the unsupported-systems visibility option. In Settings, confirm the configured ROM folder is correct. Check Connection Status if synchronization fails.
Missing systems on the list? RGSX discovers systems from the emulator configuration. Enable unsupported-system visibility under Games and check the platform filter.
Catalog sync or database write failure Check available disk space and write permissions in /saves/ports/rgsx/, then inspect the logs. Do not delete rgsx.sqlite3 without a backup: it also contains history and owned-game records.
App crashes Check /roms/ports/RGSX/logs/RGSX.log (and rgsx_web.log for the web server).
Layout change not applied Restart RGSX after changing layout
Covers missing from the game list If ScreenScraper is disabled, the preview panel (cover and synopsis) is hidden. Re-enable it in Pause > Scrap.
ScreenScraper error: account required, 403, or quota reached Enter your own ScreenScraper login in Pause > Scrap. Developer credentials are fetched once per session from the RGSX credentials service and kept in memory only. A 403 means the credentials were rejected; a quota error means your account's daily limit is reached.
Problem downloading some Games ? Open Pause Menu > Settings > Connection Status. If one or more required sites are red, enable Custom DNS in Settings and reboot. Also check ISP/router protections (especially ASUS web threat blocking).

Need help? Share logs from /roms/ports/RGSX/logs/ on Discord.


๐Ÿค Contributing

  • Bug Reports: Open GitHub issue with logs or post on Discord
  • Feature Requests: Discuss on Discord first, then open issue
  • Code Contributions:
    git checkout -b feature/your-feature
    # Test on Batocera/RetroBat
    # Submit Pull Request

๐Ÿ“ License

Free and open-source software. Use, modify, and distribute freely.

Thanks to all contributors, and followers of this app

If you want to support my project you can buy me a beer : https://bit.ly/donate-to-rgsx

Star History

Star History Chart

Developed with โค๏ธ for the retro gaming community.

About

Multi Platforms Games Download Center . This repository is not affiliated with Batocera, Retrobat or Pixel Nostalgia RGS

Resources

Stars

449 stars

Watchers

18 watching

Forks

Releases

Packages

Used by

Contributors

Languages