diff --git a/README.md b/README.md index 5a4f698..0c42920 100755 --- a/README.md +++ b/README.md @@ -7,6 +7,8 @@ **RetroDECKY** is a Decky Plugin for the all-in-on Retro Gaming Platform [RetroDECK](https://retrodeck.readthedocs.io/en/latest/). +--- + ## Screenshots

@@ -94,135 +96,89 @@ Decky Loader is required to run the RetroDECKY plugin. --- -## How-to Install RetroDECKY +## How-to: Install RetroDECKY -### Step 1: Install the Plugin +This requires that RetroDECK & Decky Loader is installed. Choose one of the following methods: -- Install from the **Decky Plugin Store** *(not available yet, but will be the recommended path)* -- Download and install from the **GitHub Releases page** - 1. Switch to desktop mode and open your browser - 2. Go to the [GitHub Releases page](https://github.com/Teppichseite/RetroDECKY/releases) - 3. For the latest release download `RetroDECKY.zip` under assets - 4. Switch back to Gaming mode - 5. Open the Quick Access Menu > Decky Tab > Click on the settings icon on the top right - 6. Under "General" enable "Developer mode" - 7. Go to the "Developer" section on the left side - 8. Click on "Browse" next to "Install Plugin from ZIP file" - 9. Select the `RetroDECKY.zip` file you downloaded in step 3 (usually stored under `~/Downloads`) - 10. Click on "Install" ---- - -### Step 2: Launch the Plugin - -1. Open the **Steam Quick Access Menu**. -2. Launch **RetroDECKY**. -3. Follow the **Setup Guide** shown in the plugin interface. -4. Reload Setup Status (if needed): Decky Settings → Plugins → RetroDECKY → Reload - ---- - -## Guides +### Install from the Decky Plugin Store -### Custom Documents +*(not available yet, but will be the recommended path)* -You can add custom documents which you can view during a game session. Supported file types are **PDF**, **TXT**, and **Markdown** (`.md` / `.markdown`). There are two ways to add documents: +Search for **RetroDECKY** in the **Decky Plugin Store** and press **Install**. -1. **In the plugin UI** - - While the game is running, open **RetroDECKY** from the Steam **Quick Access Menu**. - - Navigate to the button **View Manual** and and tap on the document button right next to it - - Tap **Add Document**, choose a file in the system picker (PDF / TXT / Markdown). The plugin copies it into that game’s documents folder and refreshes the list. -2. **Manually** - - Custom documents are stored under `/retrodecky/documents//` - - E.g. for the rom path `~/retrodeck/roms/snes/game A.zip` the documents would be stored under `~/retrodeck/storage/retrodecky/documents/snes/game A/` - - You can just add your documents to the folder and they will be **visible in the plugin UI** +### Manual Install from Github -### RetroAchievements - -RetroDECKY can show [RetroAchievements](https://retroachievements.org/) progress for the currently running game, including **softcore** and **hardcore** completion. - -RetroDECKY only **displays** achievement progress. To actually **earn** achievements while playing, you still need to set up RetroAchievements in **RetroDECK** for the respective emulator as usual. - -1. While no game is running, open **RetroDECKY** from the Steam **Quick Access Menu**. -1. Go to **Settings** > **RetroAchievements**. -2. Enter your RetroAchievements **username** and **API key** (from your [RetroAchievements control panel](https://retroachievements.org/settings?tab=applications)), then save. -3. While a supported game is running, click on the "Achievements" button from the in-game menu to see unlocked and locked achievements. - -Games are matched to RetroAchievements first by **ROM hash**. For some file extensions hashing is not supported — notably Dolphin **`.rvz`** and PSP **`.cso`**. In those cases RetroDECKY falls back to matching the game **by name**. +1. Switch to desktop mode and open your browser. +2. Download and install from the [GitHub Releases page](https://github.com/Teppichseite/RetroDECKY/releases). +3. For the latest release download `RetroDECKY.zip` under assets. +4. Switch back to Gaming mode. +5. Open the Quick Access Menu > Decky Tab > Click on the settings icon on the top right. +6. Under "General" enable "Developer mode". +7. Go to the "Developer" section on the left side. +8. Click on "Browse" next to "Install Plugin from ZIP file". +9. Select the `RetroDECKY.zip` file you downloaded in step 3 (usually stored under `~/Downloads`). +10. Click on **Install**. --- -## Architecture: How does it work? - -RetroDECKY sits between **ES-DE / RetroDECK** (which runs games and fires event scripts) and the **SteamOS** UI. - -- **Local HTTP service** — Receives game lifecycle **POSTs** from ES-DE scripts and **serves** ES-DE media and custom documents so the **Frontend** can load covers and manuals. +## How-to: Launch RetroDECKY -- **Decky backend** — The plugin’s Python side that **Decky Loader** talks to: the UI **calls into** it for actions, settings, setup checks, and document lists (the usual Decky plugin channel, separate from the localhost HTTP service above). +1. Open the **Steam Quick Access Menu**. +2. Launch **RetroDECKY**. +3. Follow the **Setup Guide** shown in the plugin interface. -- **Event emission** — When a game event POST is handled, the backend **emits** an update through Decky event emitter so the menu **refreshes immediately** instead of polling for the active game. +**Note:** -The **React** frontend loads media data from the local service, uses the **Decky backend** for structured data, and can send **simulated keyboard shortcuts** to the active emulator or component. +You might need to Reload Setup Status: `Decky Settings` → `Plugins` → `RetroDECKY` → `Reload` -

- RetroDECKY architecture -

+--- -### Game Event Detection +## Guide: Custom Documents -RetroDECKY uses [ES-DE custom event scripts](https://github.com/RetroDECK/ES-DE/blob/retrodeck-main/INSTALL.md#custom-event-scripts). The **game-start** and **game-end** events notify the plugin when a session begins and ends so the menu can show the right game context and metadata. +You can attach custom reference documents to individual games for in-session viewing. Supported formats are **PDF**, **TXT** and **Markdown** (`.md` or `.markdown`). Documents can be added in two ways: -Scripts live under: +### Via the Plugin UI -``` -/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 -``` +1. While a game is running, open **RetroDECKY** from the Steam **Quick Access Menu**. +2. Locate the **View Manual** button and select the document icon beside it. +3. Tap **Add Document**, then choose a file from the system file picker (PDF, TXT, or Markdown). The plugin copies the file into that game's documents folder and refreshes the list automatically. -Each script sends a small background HTTP **POST** request to RetroDECKY’s local **`/api/game-event`** endpoint: one payload marks a **game start**, the other a **game end**, and both include the same four pieces of information ES-DE passes in: **ROM path**, **game name**, **system name**, and **system full name**. That lets the plugin know which game is currently running. +### Manually -#### Detected ES-DE Metadata +Custom documents are stored under: -The plugin automatically resolves assets using **ES-DE** metadata directories under `${retrodeck_home_path}$/ES-DE/` and under `${retrodeck_downloaded_media_path}$`. +/retrodecky/documents// -Supported media types include: +For example, for the ROM `~/retrodeck/roms/snes/gameA.zip`, documents would be stored under: -- **Gamelists** -- **Cover artwork** -- **Miximages** -- **Game manuals** +`~/retrodeck/storage/retrodecky/documents/snes/gameA/` -Metadata and assets are served through the **local HTTP** layer above and shown in the **Decky** UI. +Simply place files in the appropriate folder and they will appear in the plugin UI automatically. --- -### Hotkey Triggering +## Guide: Enabling RetroAchievements -RetroDECKY supports most component hotkeys documented here: - -[RetroDECK Hotkeys](https://retrodeck.readthedocs.io/en/latest/wiki_rd_controls/radial-steamdeck-full/) +RetroDECKY can show [RetroAchievements](https://retroachievements.org/) progress for the currently running game, including **softcore** and **hardcore** completion. -- A script converts hotkey definitions into an **action mapping JSON file** per component. +RetroDECKY only **displays** achievement progress. To actually **earn** achievements while playing, you still need to set up RetroAchievements in **RetroDECK** for the respective emulator as usual. -- Full mappings are documented in the autogenerated file: [actions_summary.md](./defaults/presets/actions_summary.md) +1. While no game is running, open **RetroDECKY** from the Steam **Quick Access Menu**. +1. Go to **Settings** > **RetroAchievements**. +2. Enter your RetroAchievements **username** and **API key** (from your [RetroAchievements control panel](https://retroachievements.org/settings?tab=applications)), then save. +3. While a supported game is running, click on the "Achievements" button from the in-game menu to see unlocked and locked achievements. -- When a user selects an action from the menu, the plugin simulates the corresponding **keyboard input combination** for the active component. +Games are matched to RetroAchievements first by **ROM hash**. For some file extensions hashing is not supported — notably Dolphin **`.rvz`** and PSP **`.cso`**. In those cases RetroDECKY falls back to matching the game **by name**. --- -### Game PDF Viewer - -The plugin uses PDF.js and react-pdf to render PDF files. Internally it uses WASM to improve rendering performance. - ---- +## Architecture: How does it work? -### RetroAchievements +**Read more here** -RetroDECKY uses the official [RetroAchievements API](https://api-docs.retroachievements.org/) to fetch achievement progress for the currently running game. ROM hashes for game matching are computed with [RAHasher](https://github.com/RetroAchievements/RALibretro) from RALibretro (bundled with the plugin). +[RetroDECKY: Development Architecture](https://retrodeck.readthedocs.io/en/latest/wiki_retrodecky/retrodecky-development-architecture/) --- diff --git a/assets/logo/icon-RetroDECK.svg b/assets/logo/icon-RetroDECK.svg index 8acc0c3..185f9d6 100755 --- a/assets/logo/icon-RetroDECK.svg +++ b/assets/logo/icon-RetroDECK.svg @@ -1 +1,53 @@ - \ No newline at end of file + + diff --git a/assets/logo/icon-RetroDECKY.svg b/assets/logo/icon-RetroDECKY.svg index 144320c..852cdf5 100755 --- a/assets/logo/icon-RetroDECKY.svg +++ b/assets/logo/icon-RetroDECKY.svg @@ -8,7 +8,7 @@ style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;" id="svg1" sodipodi:docname="icon-RetroDECKY.svg" - inkscape:version="1.4.3 (0d15f75042, 2025-12-25)" + inkscape:version="1.4.4 (dcaf3e7d9e, 2026-05-05)" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns:xlink="http://www.w3.org/1999/xlink" @@ -23,8 +23,8 @@ inkscape:pagecheckerboard="0" inkscape:deskcolor="#d1d1d1" inkscape:zoom="1.0977553" - inkscape:cx="292.87038" - inkscape:cy="516.50857" + inkscape:cx="281.02802" + inkscape:cy="516.50855" inkscape:window-width="3840" inkscape:window-height="2082" inkscape:window-x="0" @@ -33,7 +33,7 @@ inkscape:current-layer="svg1" showguides="true" />