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 four 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
Host	Where it runs (local, home server, stream)	your hardware

Each layer can change independently, and the same game record works at every scale — one laptop, a home server, a stream to the couch. 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 — included: your declared library in Pegasus and ES-DE, every game started through its gamenix launcher (docs/FRONTENDS.md)
• 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 also lists each game's save locations. The Home Manager module
writes the same format to ~/.config/gamenix/games.toml, with save paths
expanded for that user. See Save data.

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.

Serve them to other devices

imports = [ inputs.gamenix.nixosModules.server ];
services.gamenix-server.enable = true;

# Optional: games kept in S3-compatible storage, streamed by the server.
gamenix.games.carrion = {
  game = inputs.gamenix.lib.games.pc.windows.carrion;
  src  = "s3://games/pc/carrion.tar.zst";
};
services.gamenix-server.objectStore = {
  endpoint        = "http://minio.lan:9000";
  credentialsFile = "/run/secrets/gamenix-s3";
};

A library server with a web UI and a native app that installs, launches and
streams games, navigable with a controller. Sources can be files, directories
or archives on its disks or in an object store; clients only ever see the
server. See docs/SERVER.md.

Keep their saves

Games run through the game manager by default: each plays sandboxed in its own
session home, and its saves are committed to git after every session —
independent save lines you can branch, restore and mix:

super.mario.sunshine                  # play
super.mario.sunshine saves list       # save lines
super.mario.sunshine saves new alex   # another, independent save

With a saves hub — a gamenix server — save lines follow you between devices;
progress made on two devices at once becomes a fork you settle, never an
overwrite:

gamenix.saves.hub.url = "http://server.lan:8090/api/v1/saves";
gamenix.saves.hub.tokenFile = "/run/secrets/gamenix-token";

Set gamenix.games.<id>.managed = false to run a game directly in your home
instead. See docs/MANAGER.md.

Use Gamenix as a local console

imports = [ inputs.gamenix.nixosModules.default inputs.gamenix.nixosModules.console ];
gamenix.enable = true;
gamenix.console.enable = true;

Select Gamenix in your existing session selector: Hyprland starts the native
UI fullscreen, with controller-first Settings and quick audio/brightness/power
controls where supported. This is opt-in: it preserves Steam/desktop sessions
and does not change your login manager, autologin or default session.
For explicit boot-to-Gamenix adoption with an existing SDDM/GDM login manager,
optionally set gamenix.console.autoLogin = { enable = true; user = "player"; };
using your existing normal user. This bypasses the login password prompt;
SDDM relogin is disabled so exit or a UI crash loop can return to its greeter (a single UI crash only restarts the shell).
See docs/CONSOLE.md for capabilities, recovery and Deck testing.

Stream them

services.sunshine.enable = true;
gamenix.streaming.sunshine.enable = true;

Every declared game becomes a Sunshine application with its box art, playable
from any Moonlight client. See docs/STREAMING.md.

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
  frontends.nix                  — Pegasus and ES-DE config generators
  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)
  options.nix                    — game options shared by both modules
  server.nix                     — services.gamenix-server
  console.nix                    — opt-in Gamenix (Hyprland) session
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
app/
  core/ manager/ server/ ui/     — the game manager, gamenix-server and its web/native client (Rust)
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
  saves.nix                      — save resolution and manifest checks
  streaming.nix                  — Sunshine application checks
  frontends.nix                  — Pegasus and ES-DE generated text and files
  session.nix                    — session specs and managed launchers
  sources.nix                    — source options, formats and object-store launchers
  server.nix                     — gamenix-server module options
  object-store.nix               — VM test: large object-store downloads under a memory limit
  home-manager.nix               — firmware provisioning and save checks
docs/
  PHILOSOPHY.md                  — why gamenix exists
  VISION.md                      — where gamenix is going: the hub
  MANAGER.md                     — the game manager and save lines in git
  PLATFORMS.md                   — supported platforms and runners
  STEAM.md                       — Steam library integration
  FRONTENDS.md                   — Pegasus and ES-DE configs
  SAVES.md                       — save locations and the runtime manifest
  STREAMING.md                   — Sunshine streaming and the server roadmap
  SERVER.md                      — gamenix-server and its clients
  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
• Vision — the app as the hub where declared and lived state meet
• Console — controller-first shell, local console foundation and acceptance boundaries
• Game manager — sandboxed sessions and save lines in git
• Schema — game.toml structure (machine-validated JSON Schema)
• Platforms — supported platforms and runners
• Steam — Steam library and Steam Deck integration
• Frontends — Pegasus and ES-DE configs generated from the declared library
• Runner resources — declarative emulator keys and firmware
• Save data — where each game keeps its saves, for backup and sync
• Server and clients — gamenix-server, the web UI and the native app
• Streaming — play declared games from a server via Sunshine and Moonlight
• Site — the catalog website
• Contributing — adding games to the catalog
• Future — use cases and what gamenix could become