gamenix

Games as Data.

gamenix is a structured catalog of games. Each game is a TOML file describing its identity, platform, metadata, and artwork — nothing more. No game files, no emulator config, no distro-specific packaging.

The actual game files come from you. gamenix supplies the structure.

---

Philosophy

Games are cultural artifacts. Their metadata — name, platform, description, artwork — is stable and should be expressible in a format that outlasts any specific tool, distro, or packaging convention.

gamenix separates three things that are usually conflated:

Layer	What	Who owns it
Catalog	What the game is (metadata, platform, assets)	gamenix
Runner	How to run it (emulator, Wine, native)	your system
Source	The actual game file	you

Each layer can change independently. Emulators come and go (citra → lime3ds → azahar). Package managers come and go. The fact that Yoshi's New Island is a Nintendo 3DS game from 2014 does not.

See docs/PHILOSOPHY.md for the full design rationale.

---

What You Can Build With This

• Declarative game library — your whole gaming setup expressed as reproducible NixOS/home-manager config
• Frontend configs — generate EmulationStation, Pegasus, or RetroArch playlists from the same TOML files
• Static catalog site — included: nix run .#site renders the whole catalog as a browsable website (docs/SITE.md)
• CLI tooling — add games, list your library, export to any format
• ROM integrity checker — pair the catalog with known-good hashes to verify dumps

See docs/FUTURE.md for more directions.

---

Using the Catalog

Add gamenix to your flake:

inputs.gamenix.url = "git+https://git.hydrar.de/jmarya/gamenix";

Install a game

gamenix.enable = true;
gamenix.games.yoshis-new-island = {
  game = inputs.gamenix.lib.games.nintendo."3ds".yoshis-new-island;
  src  = "/home/you/roms/yoshis.new.island.3ds";
};

This installs a launcher script, desktop entry, and icons. The game file stays where you put it.

src is a string, not a Nix path literal. A path literal is rejected in a flake's pure evaluation, and would copy the game file into the Nix store if it resolved.

Or directly via mkGame without the module:

home.packages = [
  (inputs.gamenix.lib.mkGame pkgs {
    game = inputs.gamenix.lib.games.nintendo."3ds".yoshis-new-island;
    src  = "/home/you/roms/yoshis.new.island.3ds";
  })
];

Override the runner

gamenix.games.yoshis-new-island = {
  game   = inputs.gamenix.lib.games.nintendo."3ds".yoshis-new-island;
  src    = "/home/you/roms/yoshis.new.island.3ds";
  runner = "azahar";
};

Inspect the resolved game library (NixOS)

The NixOS module exposes the fully resolved game records during evaluation at
config.gamenix.resolvedGames. This is derived from gamenix.games; it adds
runtime details such as the selected runner, source path, launcher, and icon:

config.gamenix.resolvedGames."yoshis-new-island"

It also writes the same records as a versioned TOML manifest at
/etc/gamenix.toml. Tools can read that file at runtime instead of evaluating
Nix configuration:

format_version = 1

[[games]]
id = "yoshis-new-island"
name = "yoshis.new.island"
display_name = "Yoshi's New Island"
platform = "3ds"
runner = "azahar"
source = "/home/you/roms/yoshis.new.island.3ds"
launcher = "/nix/store/.../bin/yoshis.new.island"

The manifest is generated and must not be edited by hand.

Provision emulator prerequisites

The Home Manager module can provision runner requirements, such as emulator
keys or firmware, from user-controlled runtime paths or permitted Nix packages.
See Runner resources for the security model and Ryujinx
example.

Put them in your Steam library

gamenix.steam.enable = true;

Every game becomes a non-Steam shortcut carrying its catalog artwork, grouped
into a collection per platform. Built for the Steam Deck, where the games then
appear in Gaming Mode. See docs/STEAM.md.

Browse the catalog

The catalog also renders as a website — every entry, platform, genre and series,
generated from the same TOML files:

nix run .#site   # → http://127.0.0.1:8080

See docs/SITE.md. Artwork is linked at its origin, never
rehosted.

From the command line:

nix eval .#lib.games --apply builtins.attrNames       # list vendors
nix eval .#lib.games.nintendo."3ds"                   # list 3DS games
nix eval .#lib.games.nintendo."3ds".yoshis-new-island # inspect a game
nix eval .#lib.platforms."3ds"                        # inspect a platform
nix eval .#lib.games --json                           # full catalog as JSON

---

Repo Structure

flake.nix                        — entry point
lib/
  default.nix                    — lib exports (games, platforms, mkGame)
  mkGame.nix                     — derivation builder
  steam.nix                      — Steam shortcut manifest builder
  platforms/
    default.nix                  — merges all platform files
    nintendo.toml
    sony.toml
    pc.toml
games/
  nintendo/
    3ds/
      yoshis.new.island/
        game.toml                — game definition (TOML)
    gba/ gc/ n64/ nds/ nes/ switch/ wii/ wiiu/
  sony/
    ps2/ ps3/ ps4/
  pc/
    pc/ windows/
modules/
  nixos.nix                      — NixOS module
  home-manager.nix               — home-manager module (+ Steam integration)
site/
  conf.nix                       — site identity and artwork mode
  site.nix                       — page list and data wiring
  lib/catalog.nix                — catalog → site records
  themes/gamenix/                — templates and static files
scripts/
  gamenix-add                    — interactive catalog entry creator
  gamenix-validate               — schema validation
  gamenix-steam-sync             — merge games into Steam's shortcuts.vdf
tests/
  nixos.nix                      — end-to-end test module
docs/
  PHILOSOPHY.md                  — why gamenix exists
  PLATFORMS.md                   — supported platforms and runners
  STEAM.md                       — Steam library integration
  CONTRIBUTING.md                — how to add games
  FUTURE.md                      — use cases and roadmap
schema/
  game.json                      — JSON Schema for game.toml
  platform.json                  — JSON Schema for platform entries

---

Documentation

• Philosophy — the ideas behind gamenix
• Schema — game.toml structure (machine-validated JSON Schema)
• Platforms — supported platforms and runners
• Steam — Steam library and Steam Deck integration
• Runner resources — declarative emulator keys and firmware
• Site — the catalog website
• Contributing — adding games to the catalog
• Future — use cases and what gamenix could become