Skip to content

RetroDECKY - Development Architecture

RetroDECKY logo

Architecture Overview

RetroDECKY acts as an intermediary layer between ES-DE / RetroDECK (which runs games and emits event scripts) and the SteamOS user interface.

Subsystem Responsibility
Local HTTP service Receives game lifecycle POST requests from ES-DE scripts and serves ES-DE media and custom documents to the frontend.
Decky backend The plugin's Python layer that communicates with Decky Loader. The UI calls into it for actions, settings, setup checks, and document lists via the standard Decky plugin channel (separate from the local HTTP service).
Event emission When a game event POST is handled, the backend emits an update through the Decky event emitter so the menu refreshes immediately rather than polling for the active game.

The React frontend retrieves media data from the local HTTP service, uses the Decky backend for structured data, and can dispatch simulated keyboard shortcuts to the active emulator or component.

Diagram showing how RetroDECKY sits between ES-DE/RetroDECK and SteamOS, illustrating the local HTTP service, Decky backend, and event emission data flow.

Game Event Detection

RetroDECKY leverages ES-DE custom event scripts. The game-start and game-end events notify the plugin when a session begins or ends, allowing the menu to display the correct game context and metadata.

Scripts are located under:

/home/deck/.var/app/net.retrodeck.retrodeck/config/ES-DE/scripts
├── game-end
│   └── game_end_RetroDECKY_v1.sh
└── game-start
    └── game_start_RetroDECKY_v1.sh

Each script sends a lightweight background HTTP POST request to RetroDECKY's local /api/game-event endpoint. Both payloads carry the same four fields provided by ES-DE: ROM path, game name, system name, and system full name. This allows the plugin to identify the currently running game.

Detected ES-DE Metadata

The plugin automatically resolves assets from ES-DE metadata directories located under ${retrodeck_home_path}/ES-DE/ and ${retrodeck_downloaded_media_path}.

Supported media types:

  • Gamelists
  • Cover artwork
  • Miximages
  • Game manuals

Metadata and assets are served through the local HTTP layer described above and rendered in the Decky UI.

Hotkey Triggering

RetroDECKY supports most component hotkeys documented in the RetroDECK Hotkeys reference.

  • A build-time script converts hotkey definitions into an action mapping JSON file per component.
  • Full mappings are documented in the autogenerated Github: Actions Summary.
  • When a user selects an action from the menu, the plugin simulates the corresponding keyboard input combination for the active component.

Game PDF Viewer

The plugin renders PDF documents using PDF.js and react-pdf, with WASM acceleration for improved rendering performance.