readme

2026-03-15 19:45:50 -05:00
parent 3c54fd5412
commit 7992804701
1 changed files with 246 additions and 34 deletions
--- 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 = {
-  "<hostname>" = nixpkgs-unstable.lib.nixosSystem {
-    system = "x86_64-linux";
-    modules = [
-      home-manager.nixosModules.home-manager
-      {
-        home-manager.users.<username> = { 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."<hostname>" = nixpkgs.lib.nixosSystem {
+  system = "x86_64-linux";
+  modules = [
+    home-manager.nixosModules.home-manager
+    {
+      home-manager.users.<username> = { pkgs, ... }: {
+        imports = [ steam-rom-manager.homeManagerModules.default ];
+        # ... your programs.steam-rom-manager config here
+      };
+    }
+  ];
+};
+```
+
+#### Standalone Home Manager
+
+```nix
+homeConfigurations."<username>" = 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 = "<steam username>";
+  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/<username>/.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;
  };
 };
-~~~
+```
+
+## Emulator options
+
+Each entry under `emulators.<name>` 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.<name>` 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.