EmulationStation-X (ES-X)

YouTube demo

🎁 X-TRAS — Free Games Starter Catalog

X-TRAS gives a fresh RetroPie installation something useful to launch immediately.

Instead of bundling commercial ROMs, ES-X includes a curated catalog of free homebrew games whose redistribution rights are explicitly documented. Games can be downloaded directly from the ES-X interface and are placed automatically in the correct RetroPie ROM folder.

X-TRAS is not an abandonware or commercial-ROM catalog. Active entries must have clear redistribution rights and a verifiable upstream source.

X-TRAS is designed around a strict catalog policy:

• Free and legally redistributable homebrew only
• No abandonware
• No commercial ROMs
• No freeware-only titles when redistribution permission is unclear
• No fan games or assets with unclear rights
• Author, license and upstream source are documented for every catalog entry
• Direct downloads are used only when a stable, verified source is available
• Already installed games are detected automatically

The catalog is external to the executable:

• Repository catalog: esx/xtras-free-games.ini
• Installed catalog: ~/.emulationstation/esx/xtras-free-games.ini
• Catalog entries can be updated without recompiling ES-X

The initial starter catalog already covers multiple classic systems, including Game Boy, Game Boy Color, Game Boy Advance, NES, Master System, Game Gear and Mega Drive / Genesis.

The goal is deliberately simple: a user starting with zero games can install a small legal starter library and immediately test several systems from inside ES-X.

The catalog is intentionally small and curated rather than trying to become a massive game store. It is also structured so other projects can reuse or extend the catalog format if they wish.

Background tasks — keep browsing while ES-X works

ES-X now supports a lightweight, shared background-task notification panel for long-running operations. It reports progress or the current stage using Font Awesome glyphs, without requiring a separate service or abandoning RetroPie compatibility.

• Native scraper: automatic-result scraping can run in the background, and its original dialog can be restored. Manual conflict review remains foreground-only.
• Skyscraper: resource gathering and gamelist generation expose their running/completed state; use B to return to the frontend and the dialog's stop control when needed.
• Theme Browser: continue downloading or updating themes while browsing; reopening the browser resumes an active operation. Updates stage the new download before replacing an existing theme.
• X-TRAS: free-game downloads and noninteractive RetroPie-Setup port installs/updates can continue while browsing. The status panel shows a short port name and log-derived installation stages. Port removal stays foreground-only.

A displayed percentage is a true scraper count or a single RetroPie-Setup stage, not an invented total for downloads or port installation. Theme downloads use an animated indeterminate bar.

Manual validation: native scraping continued after entering/leaving a game, downloaded and updated themes were applied successfully, and a GZDoom port installation completed in the background with a success notification. Further ARM64, failure-path and simultaneous-job checks remain useful.

Controls, details and test checklist: Background Tasks.

Example Theme Gallery

Native metadata media picker

ES-X now includes a lightweight, controller-friendly file browser for selecting game artwork and videos directly from Edit Metadata. No external file manager is needed: the picker uses the existing ES-X interface and the Font Awesome TTF icons already bundled with the frontend. No additional PNG icon pack is required.

Open a game's options, choose Edit Metadata, and select an image or video field (such as Image, Thumbnail, Marquee, Box art, Screenshot, Wheel, Texture, or Video) to browse folders and choose a local file. Image and video extensions are filtered automatically; extension matching is case-insensitive.

• A: enter a folder or select a file.
• B: close the picker without changing the field.
• Y: go to the parent folder.
• X: clear the selected media field.

The browser starts from the current media folder when available, or the system's ROM directory. Selected media paths work with the live metadata view; ES-X writes portable relative paths into gamelist.xml where appropriate. Save your metadata changes to keep the selection.

This is a focused media selector, not a general-purpose file manager: it does not rename, move, copy, or delete files.

Multilingual scraper

☕ Native Java ME (J2ME) Scraping

ES-X includes dedicated scraping support for Java ME games through the internal ScreenScraper integration.

Unlike traditional filename-based scraping, ES-X can inspect the JAR package and read MIDlet-Name directly from META-INF/MANIFEST.MF to identify the actual game title.

This is especially useful for J2ME collections, where downloaded games often contain device names, screen resolutions, database IDs, language tags, or repacker information in their filenames.

Features include:

• Native J2ME platform mapping to ScreenScraper
• Automatic MIDlet-Name detection from JAR manifests
• Cleaned filename fallback for renamed or repacked games
• Artwork fallback when traditional box art is unavailable
• Protection against malformed release dates
• No requirement to manually rename the original JAR files

Because Java ME preservation databases are incomplete, not every title can be matched automatically, but ES-X significantly improves identification of real-world J2ME collections.

Example Theme Options

Example Grid view

TEST — Rounded video previews

Video elements can opt into videoCornerRadius for VLC frames and imageCornerRadius for the snapshot/fallback displayed before or after playback. Both default to zero, preserving classic rectangular playback. The geometry is reused between frames with no extra decoding or video texture. TEST: the author reported a successful visual result with the XMB md_video preview on 2026-10-28. This does not establish Orange Pi video performance or complete regression coverage; additional checks are pending. See theme documentation.

Automatic genre collections and theme fallbacks

ES-X can group games from existing <genre> metadata into optional automatic genre collections spanning multiple consoles. The original per-system Options → Filter Gamelist → Genre remains available. These features do not move ROMs or rewrite the games' metadata.

• Genre Collections — setup, IDs and compatibility
• Theme XML — system and gamelist fallback names

The theme engine supports optional system metadata includes (<include optional="true">...), and ${systemMetaLine} displays only available metadata fields. System carousels can show a missing system logo's name with showFallbackName; game-list carousels can independently use carouselShowFallbackName to label a generic image only when game art is missing. Both fallback-name features require theme opt-in. The gamelist property is present in main since PR #67 and was visually checked with Pi-Station-X's PS4 Carousel Gamelist; other Pi-Station-X layouts do not turn it on.

Example Gamelist Carousel

ES-X adds carousel support directly to TextListComponent, allowing themes to build modern game list layouts without creating a separate view.

The gamelist can now be presented as a horizontal or vertical carousel using scraped artwork, with theme-controlled scaling, spacing, opacity, image source, image fit, and selected item emphasis.

This makes it possible to create PS5-style horizontal game carousels, classic screenshot-based vertical layouts, and other console-inspired interfaces while still using the classic EmulationStation theme structure.

TEST — Rounded carousel artwork: optional carouselImageCornerRadius (also imageCornerRadius) clips image corners without ornamental overlays, shaders or stencil buffers. <carouselImageCornerRadius>0.010</carouselImageCornerRadius> was visually confirmed on the PS5-style gamelist carousel on desktop and then reported working perfectly on the Orange Pi 4A (October 27, 2026). The precise GL/GLES backend used on the Orange Pi was not identified, and alternate image fits and broader regressions remain to be tested. This feature is available for testing and may receive adjustments; existing themes remain unchanged unless they enable it. See theme documentation.

What is ES-X?

EmulationStation-X (ES-X) is a stable, creator-focused evolution of the original EmulationStation engine, built specifically for RetroPie systems.

It started from a simple need: create better themes without leaving RetroPie.

ES-X does not replace EmulationStation. It extends it.

It preserves RetroPie compatibility, ARM performance, and familiar structure, while expanding what themes and UI systems can achieve.

Philosophy

ES-X follows a clear direction:

• Modernize without fragmenting the ecosystem
• Empower theme creators
• Keep performance ARM-friendly
• Expand carefully, not aggressively

Inspired by projects such as ES-DE, Batocera, and Recalbox, ES-X adapts selected ideas to fit RetroPie’s architecture — not to imitate them, but to expand creative possibilities within a different ecosystem.

Why ES-X Exists

Classic EmulationStation is stable and lightweight. But for theme creators, achieving modern layouts often requires duplication, structural compromises, or engine-level workarounds.

ES-X reduces that friction.

It treats themes not as static skins, but as configurable systems.

• Users benefit from improved visuals and runtime flexibility.
• Creators benefit from a cleaner and more modular foundation.

Who ES-X Is For / Not For

ES-X is for:

• Theme creators who want advanced control without engine hacks
• RetroPie users who want modern visuals while keeping compatibility
• Contributors interested in careful, production-oriented evolution

ES-X is not for:

• Replacing RetroPie’s ecosystem with a fully different frontend
• Breaking compatibility for quick experimentation
• Feature bloat without long-term ARM stability

Core Systems (Production-Ready)

🌍 Runtime Language System (.ini)

• Full UI translation without recompilation
• Dynamic loading at runtime
• Community-friendly structure
• Located in: ~/.emulationstation/lang/

Stable and actively used.

🎨 Theme Options System

The heart of ES-X:

• theme.xml → draws the UI
• theme.ini → defines options
• ES-X → binds both at runtime

This enables:

• Multiple layouts from a single theme
• Performance-friendly variants
• Console-style customization
• Zero duplication

Themes become configurable systems, not fixed presets.

See: THEME_OPTIONS.md

🧩 Extended Theme Engine

• True zIndex layering
• Advanced scale, spacing, and opacity controls
• Text borders & shadows (engine-level)
• Theme-controlled image source and fallback handling
• Safe metadata fallback handling
• Expanded carousel support for system and game views
• Horizontal and vertical gamelist carousel modes using TextListComponent

ES-X extends the classic theme engine while preserving compatibility with existing EmulationStation themes.

The goal is to make advanced layouts possible through theme XML instead of requiring hardcoded engine hacks.

🎮 Enhanced Grid Layout Control

ES-X expands Grid view flexibility, enabling themes to:

Create single-row horizontal layouts with carousel-like behavior

Scale and highlight the selected item with clean visual separation

Control spacing, composition, and visual emphasis directly via theme XML

Define custom gridtile frames using backgroundImage, allowing themed borders and overlays per state (default / selected)

Build modern console-style interfaces without modifying the engine core

Gridtile rendering has also been stabilized to prevent unintended image alpha modulation, ensuring selected items display with full opacity and accurate color reproduction.

All enhancements preserve performance, compatibility, and the lightweight architecture of classic EmulationStation.

🔊 Background Music & Audio System

• SDL_mixer-based background music manager
• Stable shuffle model
• Automatic pause on game launch
• Resume with next track
• Safe handling of corrupted audio files
• Ducking when video is playing
• Navigation sounds (scroll / select / back)

Built for long-term stability on ARM devices.

🎬 Refined Transition System

ES-X separates navigation transitions from game launch transitions.

This keeps the system carousel visually stable while allowing smoother animations within game lists and during game launch.

Inspired by modern console UI design, this produces a more balanced navigation experience without excessive motion.

Designed for Theme Creators

ES-X prioritizes clarity of mental model.

Compared to traditional EmulationStation workflows:

• Layering is predictable
• Layout variants are modular
• Localization is externalized
• Visual logic is separated from configuration

The goal is not maximum complexity. The goal is accessible expressiveness.

Beautiful themes should not require engine hacks.

Current Feature Status

Feature	Status
Runtime language system	✅ Stable
Theme variables	✅ Available
Theme Options system	✅ Stable
Text borders & shadows	✅ Stable
Dark menu mode	✅ Stable
Background music	✅ Stable
Navigation sounds	✅ Stable
Audio ducking	✅ Stable
Controller overlay	🔄 Planned
Network indicator	✅ Stable
Native metadata media picker (Font Awesome TTF)	✅ Available
Native J2ME scraping	✅ Available
MIDlet manifest detection	✅ Available
Theme Browser	✅ Stable
System descriptions / Info viewer	✅ Stable
Quick System Select	✅ Stable
Integrated Skyscraper interface	✅ Available
Background task notifications (scrapers / themes / X-TRAS)	✅ Manually validated; further regression tests recommended
X-TRAS free games catalog	✅ Available
Gamelist carousel	✅ Stable
Enhanced Grid layouts	✅ Stable
Core systems are stable for daily use. New capabilities are introduced carefully to preserve compatibility and performance.

TheGamesDB API key (optional)

ES-X keeps its existing TheGamesDB key by default. When that shared key receives HTTP 429 responses, users with their own authorized key can override it at runtime without editing source code:

export ESX_THEGAMESDB_APIKEY='YOUR_AUTHORIZED_API_KEY'
./emulationstation

The variable must be present in the environment of the actual ES-X launcher (including when started through RetroPie). Do not post the key in issues or store it in es_settings.cfg or tracked project files. ES-X does not log the key. Be careful with screenshots, terminal histories and shared shell scripts.

After TheGamesDB responds with HTTP 429, ES-X prevents new TheGamesDB API requests for approximately two minutes in that process. Already active requests may complete or fail. The pause is not an API quota reset, and cannot guarantee that an unavailable/limited key will work. ScreenScraper and other download services remain unaffected.

Installation

Recommended (RetroPie Module)

https://github.com/Renetrox/EmulationStation-X-Module-for-retropie

• ✔ Handles dependencies
• ✔ Correct build flags
• ✔ Clean RetroPie integration

Manual Build (Advanced)

git clone --recursive https://github.com/Renetrox/EmulationStation-X.git
cd EmulationStation-X
mkdir build && cd build
cmake ..
make -j4

If cloned without submodules:

git submodule update --init --recursive

Roadmap Focus

• Full language coverage
• Expanded theme-driven layout control
• Controller & network overlays
• Creator-oriented documentation
• Continued refinement without breaking RetroPie stability

Author

Dino René Caballero Márquez (Renetrox)
Educator • RetroPie Enthusiast • Theme Developer
Paraguay

License

MIT (same as original EmulationStation).

---

Accessibility is not just using it — it is understanding it, hearing it, and shaping it your way.