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 — nix eval .#lib.games --json gives you the full catalog as JSON, ready for a web frontend
• 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/yor/roms/yoshis.new.island.3ds;
};

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

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

Browse the catalog

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
  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
docs/
  PHILOSOPHY.md                  — why gamenix exists
  PLATFORMS.md                   — supported platforms and runners
  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
• Contributing — adding games to the catalog
• Future — use cases and what gamenix could become