Pokémon ROM Hacks

Curated knowledge base + tooling for the Pokémon ROM-hack collection in the valhalla homelab library. Spun off from the homelabstack repo on 2026-06-06 to keep that repo focused on infrastructure.

The ROM-hacks themselves live on valhalla under the EmuDeck/RomM tree at /storage1/Emulation/roms/<platform>/Hacks/ and are served by the RomM stack (roms.ginnoir.com) — that deployment stays in homelabstack (stacks/roms/). This repo is the catalog + pipeline, not the ROMs.

Layout

Path	What
pokemon-romhack-vault/	Obsidian vault — one note per hack (75), plus Index/Types/Platform MOCs. Open this folder as an Obsidian vault. Generated by scripts/build-romhack-vault.py.
pokemon-romhacks-wanted.md	Manual-acquisition list — worthwhile hacks gated behind Discord/hackdex/Drive that can't be auto-fetched.
scripts/build-romhack-vault.py	Regenerates pokemon-romhack-vault/ from the in-script HACKS dataset. Edit the dataset, re-run.
scripts/romhack-import.py	Import a drop folder of mixed ROMs/patches/docs into the valhalla library (validate, clean-name, apply patches, archive). Runs on valhalla.
scripts/romhack-fetch.py	Acquire + patch + place worthwhile hacks from direct (non-gated) sources. Manifest-driven. Runs on valhalla.
scripts/romhack-apply.py	Apply a single IPS/BPS/UPS patch to a base ROM with checksum verification.
drop/	gitignored staging area (~1.3 GB) of ROM/patch binaries pending import. Never committed.

Regenerating the vault

python scripts/build-romhack-vault.py

Writes the vault to pokemon-romhack-vault/ (the output path is resolved relative to scripts/, so keep scripts/ a sibling of the vault dir). The in-script HACKS dataset is the single source of truth — add a row and re-run to add a hack.

Vault schema

Each hack note carries Obsidian properties (platform, base, version, status, type, generation, source) so the Dataview/Bases plugins work, and tags (#platform/gba, #type/difficulty, #status/complete, #base/firered) so search/graph work with zero plugins. library_path points at the file under roms/<platform>/Hacks/ on valhalla.

Live Obsidian vault

A richer working copy of this catalog lives in ginnoir's self-hosted Obsidian vault (CouchDB / obsidian-livesync, obsidian.ginnoir.com) under Pokémon ROM Hacks/:

Pokémon ROM Hacks/
  _Claude.md     — ROM-hack vault ops: schema, update patterns, new-hack checklist
  Index.md       — all 75 hacks (Dataview + static)
  Play Queue.md  — play-tracking dashboard
  Hacks/         — 75 notes, one per hack
  Bases/         — per-base MOCs (FireRed / Emerald / Crystal / Ruby / NDS)
  Platforms/     — per-system MOCs (GBA / GBC / GB / NDS)

Access it via the Obsidian MCP (mcp__obsidian__*). The CouchDB sync stack itself is deployed from homelabstack (stacks/notes/).

Acquisition policy

Pre-3DS handhelds (gb/gbc/gba/nds) + pre-Wii consoles. Direct, non-anti-bot sources only for auto-fetch; gated hacks go in pokemon-romhacks-wanted.md for manual hand-off. No offensive/"shitpost" content (e.g. Clover excluded).