# Steam ROM Manager — NixOS Home Manager Module

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.

## 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";
  };
};
```

### 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 = "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 = {
    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 = {
    # --- 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.