Retromind

Built by human creativity, powered by artificial intelligence. Dedicated to the digital spark that helped compile this reality.

Retromind is a Linux-first, portable media manager for organizing and launching your media library (games, movies, books, comics, ...).

Built with C# + Avalonia.

Project homepage (GitHub Pages):

• https://dark574.github.io/Retromind/

IMPORTANT:

Retromind is still in early alpha, but regular updates are intended to preserve existing libraries and settings. In most cases, updating is as simple as replacing the AppImage. Data formats (retromind_tree.json, app_settings.json) may still evolve, and exceptional releases can require a migration or manual adjustment. Such changes will be documented in the release notes and docs/CHANGELOG.md.

Retromind is primarily developed and tested on CachyOS. The AppImage is built on Debian 12 and requires glibc 2.36 or newer. Other Linux distributions are expected to work, but have not all been tested yet. Reports and contributions from users of other distributions are welcome.

Retromind remains a work in progress. Keeping a current backup is recommended, especially before installing a new release.

• One library for more than games. Organize games, movies, books, comics and other media in a flexible tree, with drag-and-drop editing and smart folder imports.
• Rich metadata without losing control. Scrape metadata and artwork from multiple providers, process whole categories in bulk, and decide which fields and images to keep.
• Find what matters. Use global search, favorites, saved filters, missing-media filters, an optional query language, interactive statistics and a read-only library health check.

• A flexible Linux launch pipeline. Start native applications, scripts and emulators, or combine Wine, Proton, UMU, wrappers and environment overrides while preserving portable paths.
• Integrated game-library workflows. Import Steam and Heroic titles, download GE-Proton versions, reuse emulator profiles, and manage GOG offline installations, updates and DLCs through the experimental GOG integration.
• Diagnostics you can actually share. Retromind records the latest launch command, resolved runner, environment, output, runtime and exit result for easier troubleshooting.
• Experimental RetroAchievements support. Identify supported ROM and disc images, view cached progress and badges, and keep Casual and Hardcore summaries separate.

• A controller-friendly BigMode. Jump between recently played titles, favorites and the library from the Home screen, then return to the same selection after a game exits.
• Media-rich, customizable themes. Combine artwork, logos, music and video previews with runtime themes, system themes and optional artwork-derived accent colors.

• Move the library, not every path. Relative paths let a complete Retromind setup travel between Linux systems on an external drive; optional portable HOME/XDG isolation is available when needed.
• Built-in safety nets. Automatic and manual metadata backups, restore support, atomic persistence and library diagnostics help protect a growing collection.

Note: The screenshots are for demonstration purposes only.
All product names, logos, and brands shown are property of their respective owners.

• Library tree on the left (areas / categories)
• Cover grid in the center
• Details panel on the right

• Large, readable layout for couch / TV usage
• Gamepad input support
• Design and add your own themes through AXAML files

• Linux x86_64 with glibc 2.36 or newer
• X11/XWayland desktop session by default; native Wayland is available as an experimental opt-in

The AppImage is self-contained: a system-wide .NET runtime and LibVLC installation are not required.

• .NET SDK 10.0
• C compiler (cc, GCC or Clang) for the bundled rcheevos/libchdr hash library
• LibVLC runtime

1. Download the latest AppImage from the GitHub Releases page and make it executable.
2. Start the AppImage. Retromind creates app_settings.json in the directory containing the AppImage.
3. Configure optional metadata providers and API credentials in the settings dialog.

To update, simply replace the AppImage file in the same directory. Check the release notes for any migration instructions.

Developers running from source can use the commands under “Build & Run”. In that case, the portable data root is the application output directory. To preconfigure a source build, copy app_settings.sample.json there as app_settings.json and adjust it before starting Retromind.

This project ships a build script that creates a portable AppImage containing:

• a self-contained .NET build (no system .NET required)
• bundled LibVLC + plugins (video playback required)
• helper/runtime libraries exported from a Debian 12 (bookworm) build container
• a checksum-pinned, statically linked AppImage runtime
• embedded GitHub Releases update information and matching .zsync metadata for delta updates

Note: When using the AppImage, you do not need a system-wide VLC installation because LibVLC is bundled. The Wayland/X11 note below still applies because it affects how video is embedded into the Avalonia window.

• Docker with the Buildx plugin (for the full reproducible BuildKit/bookworm build pipeline)
• curl (to download appimagetool if missing)
• sha256sum (normally provided by GNU coreutils)

Verify that Buildx is available:

docker buildx version

On CachyOS and Arch Linux, install the plugin with:

sudo pacman -S docker-buildx

The generated AppImage does not depend on the host libfuse2 userspace library. Normal execution still requires Linux kernel FUSE support; AppImage's extract-and-run fallback remains available on systems where mounting through FUSE is unavailable.

chmod +x build/AppRun build/build-appimage.sh 
./build/build-appimage.sh

Official builds provide Retromind's ScreenScraper application credentials through two environment variables. They are passed to BuildKit as secrets and embedded in the resulting assembly without being written to the repository or printed by the build script:

RETROMIND_SCREENSCRAPER_DEVELOPER_ID=... \
RETROMIND_SCREENSCRAPER_DEVELOPER_PASSWORD=... \
./build/build-appimage.sh

For repeatable local builds, the values can instead be stored as individual files in the Git-ignored .build-secrets/ directory:

.build-secrets/RETROMIND_SCREENSCRAPER_DEVELOPER_ID
.build-secrets/RETROMIND_SCREENSCRAPER_DEVELOPER_PASSWORD

Each file contains only its value. Restrict the directory and files to the local user (chmod 700 .build-secrets and chmod 600 .build-secrets/*). Explicit environment variables take precedence over these files. Debug builds also read the local files at runtime when started with the repository root as their working directory; release builds receive the values only through the AppImage build script and embed them in the assembly.

Both credentials are optional for local builds, but ScreenScraper is unavailable when neither embedded credentials, runtime variables nor local Debug credentials are present. Never embed ScreenScraper's separate developer-debug password.

The version is read from InformationalVersion in Retromind.csproj. The build creates the primary release assets:

• dist/Retromind-<version>-x86_64.AppImage
• dist/Retromind-<version>-x86_64.AppImage.zsync

It also creates the small compatibility metadata file dist/Retromind-<version>-linux-x86_64.AppImage.zsync. Upload it with the primary assets so AppImageUpdate clients from 0.1.9 and earlier can discover releases after the filename transition; it does not duplicate the AppImage itself.

The script uses an isolated Buildx builder named retromind-appimage. After every build attempt, including a failed or interrupted one, it removes its temporary export container and limits this builder's cache to 20 GB. Obsolete Retromind builder images are removed after a successful build. The cache limit can be changed for a single build without affecting other Docker builders:

RETROMIND_BUILDX_CACHE_LIMIT=10gb ./build/build-appimage.sh

Open Retromind.sln in your preferred .NET-compatible IDE, select Retromind as the startup project, and build and run it.

dotnet restore
dotnet run --project Retromind.csproj

Start directly in BigMode:

dotnet run --project Retromind.csproj -- --bigmode

Or (if you run the built app directly):

./Retromind --bigmode

The automated test suite is intentionally small and risk-focused. It protects the GOG install/uninstall directory boundary, Retromind's portable path contract, prefix-path handling, category-scoped metadata suggestions, and deterministic search-query matching. The tests use isolated temporary directories under /tmp and include Linux symbolic-link, case-sensitivity, path-containment, migration, library-relocation, and played/not-played filter cases.

Run the complete solution test suite:

dotnet test Retromind.sln

The test project lives in tests/Retromind.Tests/. New tests should preferably target deterministic business rules, persistence behavior, path safety, multi-disc recognition, and scraper matching rather than Avalonia view details.

Retromind stores data under its portable data root for portability:

• AppImage: directory of the AppImage file (ENV: APPIMAGE)
• Otherwise: app base directory (build output folder)

Make sure the folder is writable.

Ignored runtime files (not committed):

• Library/
• Backups/
• app_settings.json
• retromind_tree.json (+ .bak / .tmp)

A sample settings file is provided:

• app_settings.sample.json

Retromind can create versioned ZIP backups under Backups/ next to the AppImage. Each archive contains retromind_tree.json, app_settings.json, and a checksum-protected manifest. Open Settings -> Misc -> Metadata backups to create, restore, or delete backups.

Automatic backups can be enabled globally and configured separately for application startup, accepted bulk metadata edits, bulk scraping, and backup restore. Startup backups are disabled by default; the other three triggers are enabled by default. Manual backups remain available when automatic backups are disabled. The ten newest valid startup, bulk-edit, and bulk-scrape backups are retained together. Damaged archives are marked invalid and neither count toward this limit nor get deleted automatically. Manual backups and pre-restore safety backups are never removed automatically. After a restore, Retromind closes so the preceding in-memory state cannot overwrite the restored files.

Restore defaults to Library only, which keeps the target system's emulator profiles, runner paths, scraper configuration, UI preferences, and parental-control password. Library and settings restores the complete archived application configuration as well. Item protection flags belong to the library and are therefore restored in either mode.

Metadata backups intentionally exclude Library/, games, artwork, videos, music, manuals, themes, portable Home/ data, external save files, and credentials stored in the host secret service. They are quick rollback points, not a replacement for copying the complete portable Retromind directory to another drive.

Retromind uses LibVLC for video previews in BigMode.
The hardware decoding mode is configurable via app_settings.json:

"VlcHardwareDecodeMode": "none" // or "auto", "vaapi"

Supported values (depend on the host system / VLC build):

• "none"
  Always use software decoding.
  Safest default for unknown systems and portable AppImage builds.

• "auto"
  Let VLC/FFmpeg pick a suitable hardware backend if available.
  Good compromise on well-configured desktop systems.

• "vaapi"
  Force VAAPI hardware decoding on compatible Linux systems (Intel/AMD iGPU).
  Can noticeably reduce CPU usage and make high-resolution videos smoother, but may fail on systems with broken/incomplete VAAPI setups.

If the value is missing or invalid, Retromind falls back to "none".

For the AppImage, "none" is recommended as default for maximum compatibility.
On your own machine you can set "vaapi" in app_settings.json if VAAPI works well (e.g. smoother BigMode videos, lower CPU load).

Retromind can optionally redirect HOME and the XDG_* paths into a local Home/ folder next to the AppImage.

Important behavior:

• This setting affects the Retromind AppImage process itself.
• External launches (native apps, emulators, scripts, Steam/UMU/Proton wrappers) default to host HOME/XDG for compatibility.
• If you want portable child-process storage, set emulator/item overrides (XDG_*, optional HOME) explicitly.
• Portable mode is therefore two-step:
  1. Retromind itself is portable via UsePortableHomeInAppImage
  2. each launched tool/app is portable via emulator/item XDG_*/HOME overrides

The recommended way to enable this mode is Settings -> Misc -> Use portable HOME/XDG for AppImage. After confirmation, Retromind enables forced mode so existing host values are redirected as well.

For equivalent manual configuration in app_settings.json, set both values:

"UsePortableHomeInAppImage": true,
"ForcePortableHomeInAppImage": true

Notes:

• Only applies when running as AppImage.
• Requires a restart to take effect.
• With ForcePortableHomeInAppImage set to false, only environment variables that are currently unset are redirected.
• New emulator profiles default to Host XDG context for compatibility.
• In emulator settings, you can use presets to quickly set portable XDG_* (and optional HOME) per profile.

Switching back to normal mode:

• Set "UsePortableHomeInAppImage": false and restart Retromind.
• Retromind and external launches will use the host defaults again (unless you set explicit per-emulator/per-item overrides).
• Existing files under Retromind/Home/ are kept as-is; they are not deleted automatically.

Retromind is designed to work well from a single portable folder (e.g. on a USB stick) together with your ROMs and native games. The core idea:

• The directory that contains the Retromind binary/AppImage is treated as the portable data root.
• Any files inside this directory (or subdirectories) are stored as relative paths in the library.
• On another Linux system, as long as you copy/mount the entire directory tree, Retromind will resolve these relative paths correctly, regardless of the exact mountpoint or user name.

To enable relative launch paths, turn on Prefer portable launch paths in settings. This will:

• store new imports under the data root as LibraryRelative paths
• migrate existing item launch paths during library saves
• normalize emulator settings paths (emulator executable, XDG_*, and known path-like env vars such as HOME/DOTNET_CLI_HOME/PROTONPATH) to data-root-relative values when possible

You can also trigger a one-time migration from the settings dialog.

A practical layout might look like this:

Retromind/
├── Retromind-<version>-x86_64.AppImage
├── Library/
│   └── Prefixes/
├── ROMs/
│   ├── SNES/
│   └── PSX/
├── NativeGames/
└── Themes/

If you add ROMs or native games from anywhere inside the Retromind/ folder:

• Retromind will detect that their absolute paths are under the portable root,
• convert them once to library-relative paths in the JSON database,
• and resolve them at runtime against the current AppImage directory.

This means:

• Moving the entire Retromind/ folder to another machine or mounting it under a different path will not break those entries.
• Only data stored outside of Retromind/ (e.g. /home/user/Downloads/…) is saved as an absolute path and depends on the original mountpoint.

When launching items that use Wine/Proton/UMU, Retromind can automatically create and remember a per-item Wine prefix in the library:

• Prefixes are stored under Library/Prefixes/… (inside the portable root).
• The stored prefix path is relative to the library root.
• On another system, as long as the whole Retromind/ folder moves together, the same prefixes will be reused.
• Broken absolute runtime links created internally by Proton are repaired against the currently selected Proton version before launch and before later GOG update/DLC installer runs.

Note:

• The prefix itself is portable within Retromind’s folder.
• Game saves/configs remain host-user specific by default.
• If needed, you can override XDG_* (and optionally HOME) per emulator/item.
• Even with overrides, full portability is launcher-dependent; some tools still rely on host state.

Retromind supports managed Wine/Proton runtime versions and lets you select them on:

• emulator level (default for all items using that emulator)
• item level (optional override)

In Settings -> Runner you can:

• add external Wine/Proton directories manually
• download/install GE-Proton releases (stored under Emulators/ProtonVersions in the portable root)
• remove versions (with replacement selection when still in use)

GE-Proton source:

• Repository: https://github.com/GloriousEggroll/proton-ge-custom
• Releases API used by Retromind: https://api.github.com/repos/GloriousEggroll/proton-ge-custom/releases

Retromind does not claim ownership of GE-Proton. Names, trademarks, and licenses remain with their respective owners. Thanks to GloriousEggroll and all contributors for maintaining and publishing GE-Proton.

In Settings -> Emulators -> Advanced:

• enable Use per-game prefix (WINEPREFIX) for the emulator profile
• set Runner type (Auto, UmuProton, Wine, Generic)
• choose Default runner version

Notes:

• If Use per-game prefix (WINEPREFIX) is disabled, emulator-level default runner selection is disabled.
• Auto keeps compatibility heuristics; explicit types (UmuProton/Wine) are recommended for fixed setups.

In Edit Item -> Prefix (Wine/Proton/UMU):

• select a per-item Wine/Proton version to override the emulator default
• leave it on None to inherit the emulator default
• the dialog shows which runner is currently inherited from the emulator

Effective priority:

1. Item runner version (if set)
2. Emulator default runner version
3. No explicit runner version (launcher/env behavior only)

Native games that live under the Retromind/ directory tree (e.g. Retromind/NativeGames/MyGame/...) are resolved the same way as ROMs:

• Internally, Retromind stores their launch paths relative to the portable root.
• On a different Linux system, launching still works as long as:
  • the game files remain in the same relative position under Retromind/,
  • system-level dependencies (e.g. libraries, drivers) required by the game are available.

Game-specific saves/configs stored under the user’s home directory are not moved automatically; they will behave like any regular native Linux game when run on a different machine.

When configuring emulator profiles or per-item launch arguments, Retromind supports a few simple placeholders that are expanded at launch time:

• {file}
  Full path to the primary launch file (quoted when needed).
• {fileDir}
  Directory of the primary launch file (no trailing slash).
• {fileName}
  File name including extension (e.g. cabal.zip).
• {fileBase}
  File name without extension (e.g. cabal).

These placeholders can be used in both:

• Emulator profile arguments (EmulatorConfig.Arguments)
• Per-item arguments (MediaItem.LauncherArgs), which are combined with the profile arguments.

To launch the Flatpak MAME build using ROM short names derived from the file path:

• Executable path:
  flatpak
• Default arguments:
  run org.mamedev.MAME {fileBase}

With a ROM stored as:

/run/media/…/MAME/NameOfROM.zip

Retromind expands {fileBase} to NameOfROM and starts:

flatpak run org.mamedev.MAME NameOfROM

Make sure the ROM directory is part of MAME’s rompath, or pass it explicitly:

run org.mamedev.MAME -rompath "{fileDir}" {fileBase}

which yields, for the example above:

flatpak run org.mamedev.MAME -rompath "/run/media/…/MAME" NameOfROM 

For Wine-based games (e.g. via UMU) you can keep most logic in the emulator profile:

umu-run --some-default-options {file} 

and use per-item arguments only for game-specific flags, e.g.:

--use-special-mode 

Retromind combines profile + item arguments into a single command line while expanding the placeholders as described above.

Retromind does not bundle personal user API keys. Providers that require personal credentials read them from the scraper configuration in the settings dialog. Official builds do embed Retromind's application-level ScreenScraper access, while an optional personal ScreenScraper account is configured separately by the user. OpenLibrary does not require credentials, and the Google Books API key is optional.

Scraper secrets are not written to app_settings.json as plain text. Retromind stores them using portable application-level encryption (for example, EncryptedApiKey). Because its encryption key ships with the open-source application, this prevents casual disclosure but is not protection against a targeted attack.

The table below shows which metadata fields are currently populated by each provider. Source is populated for all providers.

• CustomFields are provider-specific key/value pairs and may vary by API response quality.
• Missing values are normal when the upstream provider does not return that field for a specific item.
• SteamGridDB is an artwork-focused provider and currently supplies cover, wallpaper and logo assets.
• ScreenScraper automatically attempts exact ROM identification during manual and bulk metadata searches when a supported technical game system and an existing primary game file are available. It sends the file size plus CRC32, MD5 and SHA-1 in one API request. A successful match avoids a separate title request; unknown ROMs fall back to a system-constrained title search, while unsupported or incomplete items use ordinary title search. ScreenScraper bulk jobs run sequentially to respect conservative account limits.
• Providers can expose optional preview and result-enrichment capabilities. The manual dialog loads lightweight result previews first and requests fuller data only for the selected result; bulk scraping enriches only an accepted match.
• TheGamesDB bulk searches use only the first probability-ranked result page, resolve supplemental names and artwork only for accepted matches, and reuse resolved names during the current session. The operation runs sequentially and stops when TheGamesDB reports that the configured key's request allowance has been exhausted.
• Manual scraping lets you choose individual changed metadata fields. Existing artwork is retained and selected new artwork is added instead of replacing it.
• EmuMovies is currently not listed here because its API is being reworked.

You need to create your own API keys on the respective provider pages:

• TMDB (The Movie Database)
  Create a free account at:
  https://www.themoviedb.org/
  Then go to Settings → API in your profile and request an API key (v3 auth). Enter this key in the TMDB scraper configuration in Retromind.

• IGDB (via Twitch Developer)

  1. Create a Twitch Developer account:
     https://dev.twitch.tv/
  2. In the Developer Console, create an application to obtain:
  • Client ID
  • Client Secret
  3. Enter both values in the IGDB scraper configuration in Retromind.

• TheGamesDB

  1. Create an account at https://thegamesdb.net/.
  2. Log in and obtain your key from https://api.thegamesdb.net/key.php.
  3. Enter the key in the TheGamesDB scraper configuration in Retromind.

• SteamGridDB

  1. Create an account at: https://www.steamgriddb.com/
  2. Generate a personal API key under Preferences → API: https://www.steamgriddb.com/profile/preferences/api
  3. Enter the key in the SteamGridDB scraper configuration in Retromind.

• ComicVine

  1. Create a ComicVine account.
  2. Log in and obtain your key from https://comicvine.gamespot.com/api/.
  3. Enter the key in the ComicVine scraper configuration in Retromind.

• Google Books (optional)
  The Google Books API can be used without a key in many cases, but you may configure an API key to raise limits:
  https://console.cloud.google.com/apis/library/books.googleapis.com
  Create a project, enable the Books API, and create an API key. Enter it in the Google Books scraper configuration in Retromind.

• ScreenScraper (recommended)

  1. Create a personal account at https://www.screenscraper.fr/.
  2. Enter your ScreenScraper username and password in Retromind.

  Official Retromind builds already contain the separate application credentials approved for Retromind. A personal account is therefore not an application key, but it provides the user's own quota and makes access more reliable when anonymous API access is restricted. Both account fields must be entered together or both left empty.

Each user is responsible for their own API keys and must comply with the respective provider terms of service.

The RetroAchievements integration is currently experimental and has not yet been broadly tested across the many supported systems, game-file formats, and emulator configurations. Existing functionality should be usable, but identification or progress display may still expose compatibility gaps. Test reports are welcome.

Retromind can identify compatible game files through RetroAchievements and show the configured user's achievement progress, badges, points, unlock times, and separate Casual/Hardcore summaries in the desktop detail panel. BigMode themes can additionally provide a compact progress summary; this can be disabled independently in the RetroAchievements settings.

Retromind does not unlock achievements itself. Achievement unlocking is handled by a compatible emulator with RetroAchievements enabled. Configure the same RetroAchievements account in the emulator if you want the progress shown by Retromind to reflect your gameplay.

1. Create an account at https://retroachievements.org/.
2. While signed in, open the account control panel and copy the Web API key from its Keys section: https://retroachievements.org/controlpanel.php
3. In Retromind, open Settings -> Integrations -> RetroAchievements.
4. Enable the integration and enter your username and Web API key.
5. Select Test connection, then save the settings.

Use the Web API key, not an emulator password, Connect API token, or another API credential. The official RetroAchievements API guide also explains where to find this key and recommends treating it like a password.

When a system keyring is available, Retromind stores the key there. It is never written to app_settings.json, the library, metadata backups, or the RetroAchievements cache. Without an available keyring, the key remains available only for the current Retromind session.

RetroAchievements identification needs the technical game system in addition to the ROM/disc file:

1. Right-click the category containing the games and open Settings.
2. Under Integrations, select the correct Game system and save.

The assignment is inherited by child categories and games unless they override it. It is independent of the free-text platform metadata and the selected emulator. Only systems supported by Retromind's bundled RetroAchievements hashing library are eligible; the mass-identification menu is disabled for unsupported system assignments.

There are three supported workflows:

• Single game: Open Edit media -> General, select or inherit the game system, then choose Identify game in the RetroAchievements section. Save the media entry to retain the match.
• Existing category: Right-click the category and choose Search RetroAchievements (All).... The scan includes descendant categories, skips games already identified, and retains completed matches if canceled.
• ROM folder import: When importing through Import -> Local folder (ROMs), identification runs automatically if the integration is configured and the target category has a supported game system.

Identification uses the game file's system-specific RetroAchievements hash rather than its filename. A compatible dump is therefore required; a correct title alone is not sufficient. Disc images in CHD format are supported through the bundled decoder.

Select an identified game to see its progress in the right-hand detail panel. The achievement list can be expanded to show badges, descriptions, points, unlock state, and unlock time. The Default and Prism BigMode themes show a compact Casual/Hardcore summary after the selection has settled. In BigMode, press X / Square on a controller or I on the keyboard to open the detailed achievement browser. Navigate badges with the D-pad or arrow keys and close it with X / Square, B / Circle, or Esc. Badge images are downloaded lazily when the detailed view is opened. Retromind refreshes the selected game after a normally tracked play session; Refresh can also be used manually in the desktop view.

Successful progress responses and badge images are cached locally. If RetroAchievements is temporarily unavailable, Retromind can display the latest cached progress and marks it as cached data. The cache is stored under Cache/RetroAchievements in the portable data root, or under Home/.cache/retromind/RetroAchievements when portable AppImage HOME is enabled.

Thanks to the RetroAchievements team and community for providing the achievement database, Web API, artwork, and rcheevos library that make Retromind's RetroAchievements integration possible.

Retromind uses X11/XWayland by default. Avalonia 12.1's native Wayland backend is available as an experimental opt-in:

./Retromind-<version>-x86_64.AppImage --avalonia-platform=wayland

For source builds, pass the Retromind argument after the dotnet run separator:

dotnet run --project Retromind.csproj -- --avalonia-platform=wayland

When Wayland is requested, Retromind uses Avalonia's Wayland initialization fallback and starts with X11 if the native backend cannot be initialized. Omit the option or pass --avalonia-platform=x11 to select X11 explicitly. --avalonia-platform=auto intentionally keeps the stable X11 default; Wayland always requires an explicit opt-in.

The Wayland backend is still classified as experimental by Avalonia. Retromind also depends on native integration for LibVLC video embedding, so this path needs additional real-world testing. The embedded GOG login uses WPE WebKit's offscreen renderer and is independent of the selected Avalonia X11/Wayland backend.

Source: https://docs.avaloniaui.net/docs/platform-specific-guides/linux#wayland

• Retromind sorts media entries by SortTitle attribute if it is set.
• If SortTitle is empty, Retromind falls back to Title.
• This is useful for series ordering (for example: Series 001 - ..., Series 002 - ...).

• Available in both search fields: global search and local node search.
• Plain text terms search title by default.
• Field terms: key:value or key=value.
• Metadata and media completeness terms: has:<field> and missing:<field>.
• Year comparisons: year:>=YYYY, year:>YYYY, year:<=YYYY, year:<YYYY (or exact year:YYYY / year=YYYY).
• Logical operators: AND, OR, NOT, and parentheses ( ).
• Space between terms is treated as AND.
• In mixed queries, plain terms still search title (example: zelda AND platform:switch).
• Use quotes for values with spaces (example: developer:"Treasure Co. Ltd.").

Supported keys (aliases included):

• title, sorttitle, description/notes, developer, publisher, platform, source
• genre, series, releasetype, playmode, players/maxplayers
• status/state, year, date/released, tag/tags, id, favorite, played/started, store, gogupdate
• Media fields: cover, wallpaper, logo, video, marquee, music, banner, bezel, controlpanel, manual, screenshot
• played:true matches an item when it has a launch count, recorded play time, or a last-played timestamp; played:false matches items without any of that play evidence.
• Custom fields:
  • cf:<text> searches custom field keys and values.
  • cfk:<text> searches only custom field keys.
  • cfv:<text> searches only custom field values.
  • cf.<fieldname>:<text> searches a specific custom field key (example: cf.rating:5).

Examples:

• zelda -> title-only search
• platform:snes AND developer:nintendo
• maxplayers:2 AND status:completed
• year=1998 favorite=true
• status:incomplete AND played:true
• status:incomplete AND played:false
• year:>=1995 AND year:<2000
• missing:genre OR missing:developer
• missing:logo OR missing:music
• has:genre AND NOT genre:unknown
• store:gog AND gogupdate:true (or the shorthand has:gogupdate)
• (genre:platformer OR genre:metroidvania) AND NOT missing:rating
• cf.rating:5
• zelda AND platform:switch

The native GOG integration is currently experimental. Please test it carefully and expect rough edges or breaking behavior between alpha releases.

• Linux desktop session with X11/XWayland, or native Wayland through the experimental opt-in described above.
• Secret store support:
  • preferred: Secret Service (secret-tool, GNOME Keyring/KWallet/libsecret backend)
  • fallback: in-memory session storage (non-persistent)
• For embedded OAuth login dialogs: host WPE WebKit runtime available (Arch/CachyOS: sudo pacman -S wpewebkit).
  • WebKitGTK is not required for GOG authentication.
  • If WPE WebKit is unavailable, Retromind falls back to system browser login with manual callback URL input.
  • After GOG finishes loading its final callback page, copy the URL from the browser address bar and paste it into Retromind.
  • Set RETROMIND_GOG_FORCE_BROWSER_LOGIN=1 to force this fallback for testing or troubleshooting.

• Import full GOG library into a dedicated node:

  1. Create a new node.
  2. Open node settings and mark it as a GOG node (StoreProviderId = gog).
  3. Run Add GOG media on that node.
  4. Retromind syncs owned GOG titles additively into that node.

• Add individual GOG items into any node:

  1. Run Add GOG media on any target node.
  2. Use the picker dialog and select only the titles you want to add.

• Install a linked title without a launch configuration by using its main Install action. Retromind downloads the selected Linux or Windows installer, supports resumable downloads, runs the installer, and derives a launch configuration where possible.

• Uninstall actions remove an installation only when the directory passes the path-safety policy and contains a matching Retromind ownership marker. Files outside the owned install directory are not treated as disposable application data.

• With Prefer portable launch paths enabled, GOG installations inside Retromind store their install root relative to the portable data root. Existing and deliberately external absolute install paths remain supported.

• Update checks are only performed for installed GOG-linked items.
• Checks are triggered automatically:
  • when selecting an installed GOG item in the UI
  • and by a background sweep (currently every 24 hours)
• If an update is detected, Retromind shows:
  • an update badge in the media details
  • an Update action button (same panel as install/reinstall actions)
• Running Update installs the current main-game package in place. It never deletes the existing game folder and does not offer the destructive Clean install option.
• After an update, Retromind automatically reinstalls every DLC previously installed through Retromind with its current package for the selected platform. Owned but uninstalled DLCs are not added. Failed or unavailable DLCs do not stop the remaining DLCs and keep the GOG update indicator active. The installer's staging-data choice applies to both the main-game package and every automatically reinstalled DLC package.
• Use Reinstall when you deliberately want a clean installation. Its optional Clean install mode deletes the contents of the Retromind-managed game folder, including mods and other files stored there, after an explicit confirmation. A separate Wine/Proton prefix and its Winetricks changes are preserved. A collapsed checklist lets you choose which previously installed DLCs are restored afterwards; all are selected by default. Without Clean install, Retromind forces all installed DLCs to be reapplied because deselected DLC files would otherwise remain in place.
• Important baseline note:
  • reliable version/signature comparison requires an install fingerprint from Retromind.
  • If a title was installed outside Retromind or before this metadata existed, run one reinstall via Retromind to establish the baseline.

See docs/architecture.md. For native GOG provider status and design notes, see docs/gog-provider.md.

Contributions are welcome!
Before opening issues or pull requests, please have a look at:

• CONTRIBUTING.md – contribution guidelines
• CODE_OF_CONDUCT.md – expected behavior in the project community

• Bug reports and feature requests: GitHub Issues
• Questions and general discussion: GitHub Discussions
• Private contact: retromind.project@proton.me
• Security vulnerabilities: private vulnerability reporting

GPL-3.0-only (see COPYING).

Third-party product names and trademarks are used only to identify the systems and services that Retromind supports. They remain the property of their respective owners.

“Super Nintendo Entertainment System” and “SNES” are trademarks of Nintendo. Retromind is an independent project and is not affiliated with, sponsored by, or endorsed by Nintendo.

“PlayStation” is a trademark of Sony Interactive Entertainment. Retromind is an independent project and is not affiliated with, sponsored by, or endorsed by Sony.