From 79928047019d4fb325d272bcb34ac9b47e0fe05a Mon Sep 17 00:00:00 2001 From: mjallen18 Date: Sun, 15 Mar 2026 19:45:50 -0500 Subject: [PATCH] readme --- README.md | 280 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 246 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 218e8b1..8b913ce 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,258 @@ -# Steam Rom Manager NixOS Home Manager Configuration +# Steam ROM Manager — NixOS Home Manager Module -## Usage +A Home Manager module that installs and configures [Steam ROM Manager](https://github.com/SteamGridDB/steam-rom-manager) (SRM) declaratively. It manages the SRM AppImage, desktop entry, `userSettings.json`, and `userConfigurations.json` from your Nix configuration. -### Nix Flake -Inputs: steam-rom-manager.url = "github:mjallen18/nix-steam-rom-manager"; -~~~ -nixosConfigurations = { - "" = nixpkgs-unstable.lib.nixosSystem { - system = "x86_64-linux"; - modules = [ - home-manager.nixosModules.home-manager - { - home-manager.users. = { pkgs, ...}: { - imports = [ - steam-rom-manager.homeManagerModules.default - ]; - }; - } - ]; +## Requirements + +- NixOS with Home Manager +- `x86_64-linux` or `aarch64-linux` + +## Installation + +### 1. Add the flake input + +```nix +inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + home-manager = { + url = "github:nix-community/home-manager"; + inputs.nixpkgs.follows = "nixpkgs"; + }; + steam-rom-manager = { + url = "github:mjallen18/nix-steam-rom-manager"; + inputs.nixpkgs.follows = "nixpkgs"; + inputs.home-manager.follows = "home-manager"; }; }; -~~~ +``` -### Configuration -~~~ +### 2. Import the module + +#### Via NixOS + Home Manager + +```nix +nixosConfigurations."" = nixpkgs.lib.nixosSystem { + system = "x86_64-linux"; + modules = [ + home-manager.nixosModules.home-manager + { + home-manager.users. = { pkgs, ... }: { + imports = [ steam-rom-manager.homeManagerModules.default ]; + # ... your programs.steam-rom-manager config here + }; + } + ]; +}; +``` + +#### Standalone Home Manager + +```nix +homeConfigurations."" = home-manager.lib.homeManagerConfiguration { + pkgs = nixpkgs.legacyPackages.x86_64-linux; + modules = [ + steam-rom-manager.homeManagerModules.default + # ... your programs.steam-rom-manager config here + ]; +}; +``` + +## Minimal configuration + +```nix programs.steam-rom-manager = { - enable = true; - steamUsername = ""; - + enable = true; + steamUsername = "your-steam-username"; # account name, not display name +}; +``` + +This installs SRM and writes default config files. No emulators are enabled by default. + +## Full configuration example + +```nix +programs.steam-rom-manager = { + enable = true; + steamUsername = "your-steam-username"; + environmentVariables = { - romsDirectory = "/path/to/your/roms"; - steamDirectory = "/home//.local/share/Steam"; + steamDirectory = "/home/alice/.local/share/Steam"; + romsDirectory = "/home/alice/Emulation/roms"; + retroarchPath = ""; # set if using RetroArch + raCoresDirectory = ""; + localImagesDirectory = ""; + }; + + # Global image provider settings + enabledProviders = [ "sgdb" "steamCDN" ]; + imageProviderSettings.sgdb = { + nsfw = false; + humor = false; + imageMotionTypes = [ "static" ]; }; emulators = { - ryujinx = { - enable = true; - }; - pcsx2 = { - enable = true; - }; - # Add other emulators as needed + # --- Nintendo --- + ryujinx.enable = true; # Switch (ryubing fork) + yuzu.enable = true; # Switch (eden fork) + mesen.enable = true; # NES + snes9x.enable = true; # SNES + mupen64plus.enable = true; # N64 + dolphin-emu.enable = true; # GameCube / Wii + cemu.enable = true; # Wii U + melonDS.enable = true; # DS + citra.enable = true; # 3DS (azahar fork) + mgba.enable = true; # Game Boy / GBC + mgba-gba.enable = true; # Game Boy Advance + + # --- Sony --- + duckstation.enable = true; # PS1 + pcsx2.enable = true; # PS2 + rpcs3.enable = true; # PS3 + ppsspp.enable = true; # PSP + + # --- Sega --- + blastem.enable = true; # Genesis / Mega Drive + flycast.enable = true; # Dreamcast + mednaffe.enable = true; # Saturn + + # --- Microsoft --- + xemu.enable = true; # Xbox + dosbox.enable = true; # DOS + dosbox-staging.enable = true; + + # --- Arcade / Multi-system --- + mame.enable = true; + retroarch.enable = true; + ares.enable = true; + + # --- Other --- + scummvm.enable = true; + stella.enable = true; # Atari 2600 + "fs-uae".enable = true; # Amiga + + # --- Platform parsers (no ROM scanning; artwork only / launcher integration) --- + "Non-SRM Shortcuts".enable = true; + epic.enable = true; + legendary.enable = true; # Epic via legendary-gl CLI + gog.enable = true; + "itch.io".enable = true; }; }; -~~~ \ No newline at end of file +``` + +## Emulator options + +Each entry under `emulators.` supports the following options: + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `enable` | bool | `false` | Include this parser in the generated config | +| `disabled` | bool | `false` | Write the parser but mark it inactive inside SRM | +| `package` | package \| null | per-emulator | Nix package providing the binary; `null` for platform parsers | +| `parserType` | string | `"Glob"` | SRM parser type (see below) | +| `configTitle` | string | attr name | Label shown in SRM | +| `romFolder` | string | per-emulator | Sub-folder under `romsDirectory` | +| `steamCategories` | list of string | per-emulator | Steam collection tags | +| `extraArgs` | string | per-emulator | Arguments passed to the emulator | +| `executableModifier` | string | `"\"${exePath}\""` | SRM executable modifier expression | +| `titleModifier` | string | `"${fuzzyTitle}"` | SRM title modifier expression | +| `fileTypes` | list of string | per-emulator | File extensions for the glob pattern | +| `steamInputEnabled` | bool | `false` | Enable Steam Input for shortcuts | +| `onlineImageQueries` | list of string | `["${fuzzyTitle}"]` | Artwork search terms | +| `imagePool` | string | `"${fuzzyTitle}"` | Artwork cache key | +| `userAccounts` | list of string | `["Global"]` | Target Steam accounts | +| `drmProtected` | bool | `false` | Mark shortcuts as DRM-protected | +| `shortcutPassthrough` | bool | `false` | Pass through existing shortcuts | +| `appendArgsToExecutable` | bool | `true` | Append args to the executable | +| `parserInputs` | attrs | per-emulator | Extra parser-specific inputs | + +### Parser types + +| `parserType` | Use case | +|---|---| +| `Glob` | Standard ROM files matched by extension (default) | +| `Glob-regex` | ROM files matched by regex | +| `Manual` | Manually-specified manifest directory | +| `Non-SRM Shortcuts` | Artwork for shortcuts added by other tools | +| `Steam` | Artwork for existing Steam library entries | +| `Epic` | Epic Games Launcher integration | +| `Legendary` | Legendary CLI (Epic) integration | +| `GOG Galaxy` | GOG Galaxy integration | +| `itch.io` | itch.io integration | +| `EA Desktop` | EA app integration | +| `Battle.net` | Battle.net integration | +| `UPlay` | Ubisoft Connect integration | +| `Amazon Games` | Amazon Games integration | + +### Overriding a built-in emulator + +```nix +emulators.dolphin-emu = { + enable = true; + romFolder = "wii"; # override the default "gc" folder + steamCategories = [ "Wii" ]; + extraArgs = "-b -e \"\${filePath}\""; +}; +``` + +### Custom emulator + +Any key not in the built-in list falls back to `pkgs.` for the package. Set `romFolder` and `fileTypes` explicitly: + +```nix +emulators.mist = { + enable = true; + package = pkgs.mist; + romFolder = "fpga"; + fileTypes = [ ".rbf" ".RBF" ]; + extraArgs = "\"\${filePath}\""; + steamCategories = [ "FPGA" ]; +}; +``` + +## Options reference + +### Top-level + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `enable` | bool | — | Enable the module | +| `steamUsername` | string | — | Steam account name (not display name) | +| `theme` | string | `"Deck"` | SRM UI theme | +| `language` | string | `"en-US"` | UI language (BCP-47) | +| `autoUpdate` | bool | `false` | Let SRM update itself (not recommended in Nix) | +| `offlineMode` | bool | `false` | Skip remote artwork fetching | +| `emudeckInstall` | bool | `false` | EmuDeck compatibility mode | +| `batchDownloadSize` | int | `50` | Images downloaded per batch | +| `dnsServers` | list of string | `[]` | Custom DNS for artwork downloads | +| `navigationWidth` | int | `0` | Sidebar width in pixels | +| `clearLogOnTest` | bool | `true` | Clear log on each parser test | + +### `environmentVariables` + +| Option | Default | +|--------|---------| +| `steamDirectory` | `~/.local/share/Steam` | +| `romsDirectory` | `~/Emulation/roms` | +| `retroarchPath` | `""` | +| `raCoresDirectory` | `""` | +| `localImagesDirectory` | `""` | + +### `previewSettings` + +| Option | Default | +|--------|---------| +| `retrieveCurrentSteamImages` | `true` | +| `disableCategories` | `false` | +| `deleteDisabledShortcuts` | `false` | +| `imageZoomPercentage` | `30` | +| `preload` | `false` | +| `hideUserAccount` | `false` | + +## Notes + +- **SRM is installed as an AppImage** wrapped with `appimage-run`. The module fetches the AppImage at build time; a working internet connection or binary cache is required on first activation. +- **`autoUpdate = false` is strongly recommended** under Nix — letting SRM self-update would replace the managed AppImage with an untracked version. +- The generated `userConfigurations.json` preserves SRM's required key ordering via manual JSON construction (SRM is sensitive to field order in some versions). +- `steamUsername` must match the Steam **account name** (the login name), not the display name shown in the Steam UI.