nuzlocke-tracker/.beans/nuzlocke-tracker-25mh--genlocke-tracking.md

title, status, type, priority, created_at, updated_at

title	status	type	priority	created_at	updated_at
Genlocke tracking	todo	epic	normal	2026-02-08T12:17:19Z	2026-02-09T07:45:10Z

Track a genlocke — a series of linked nuzlocke runs, typically one per generation or region. The player picks one game per generation/region and surviving Pokemon carry over between legs.

User Flow

1. Create Genlocke

The user starts a new genlocke and gives it a name.

2. Select Games (Legs)

The user picks which games to play, in order. The UI offers preset templates to speed this up, but the user can always customize:

• True Genlocke — One original game per generation (Red/Blue/Yellow → Gold/Silver/Crystal → Ruby/Sapphire/Emerald → ...). Uses the original releases only.
• Normal Genlocke — Uses the latest remake or enhanced version for each region (FireRed/LeafGreen → HeartGold/SoulSilver → Emerald → Platinum → ...). This is the most common format.
• Custom — The user picks any games in any order. No restrictions on which games or how many.

For the preset templates, the user still picks which game within each generation/region slot (e.g., FireRed vs LeafGreen for Gen 1). The template just determines which slots are shown. The user can add/remove/reorder legs after selecting a template.

Games are grouped by region (not release generation) for the purpose of presets, since that's how genlocke players think about it (e.g., FireRed is a "Kanto" leg, not a "Gen 3" leg).

3. Configure Rules

Two categories of rules are configured:

Per-game nuzlocke rules — The standard nuzlocke ruleset (first encounter only, permadeath, duplicates clause, level caps, etc.). These are set once and apply uniformly to all legs. Uses the existing NuzlockeRules interface.

Genlocke-specific rules — Overarching rules that govern how legs connect:

• Keep HoF (default) — Pokemon that enter the Hall of Fame at the end of a leg are transferred to the next leg as eggs (breed at level 1). This is the standard genlocke mechanic.
• Retire HoF — Pokemon that enter the Hall of Fame are retired. They (and their evolutionary families) become unavailable in future legs (added to a cumulative dupe list). This is also known as the "Gauntlet" rule. Increases difficulty by forcing new Pokemon each leg.
• Potentially more rules in the future (e.g., item carry-over restrictions, level scaling).

4. Sequential Run Progression

• When the genlocke is created, the first leg is automatically started as a new nuzlocke run.
• Each leg is a full nuzlocke run, tracked exactly like any standalone run (encounters, team, bosses, graveyard, etc.).
• When a leg is marked as completed (Hall of Fame), the next leg is started. A transfer step happens between legs where the user selects which surviving Pokemon to carry forward.
• When a leg is marked as failed (wipe), the genlocke itself is marked as failed (game over).
• The final leg's completion marks the entire genlocke as completed.

5. Genlocke Overview Page

A dedicated page showing:

• Progress — Which leg is active, which are completed, which are upcoming. Visual timeline or step indicator.
• Configuration — Selected games, rules, genlocke-specific rules.
• Cumulative Stats — Total encounters, total deaths, total HoF entries across all legs.
• Lineage Tracking — Show Pokemon that have carried over across multiple legs (their journey through the genlocke).
• Cumulative Graveyard — All deaths across all legs in one view.

Data Model

New entities:

• Genlocke — Top-level entity: name, status (active/completed/failed), genlocke rules (JSONB), created_at.
• GenlockeLeg — Join table linking a Genlocke to a NuzlockeRun: genlocke_id, run_id, leg_order. Defines the sequence.

Changes to existing entities:

• NuzlockeRun — No schema changes needed. A run that's part of a genlocke is just a normal run that happens to be referenced by a GenlockeLeg. The genlocke-level rules are stored on the Genlocke, not duplicated per run.

Transfer tracking:

• GenlockeTransfer — Records which Pokemon were carried between legs: from_leg_id, to_leg_id, encounter_id (the source encounter from the completed leg), to_encounter_id (the egg/gift encounter created in the next leg).

Child Features (suggested breakdown)

1. Genlocke creation wizard — Multi-step UI: name → game selection (with presets) → rules → confirm
2. Genlocke overview page — Dashboard with progress, stats, configuration
3. Leg progression — Auto-start next leg when current completes, transfer step
4. Transfer UI — Select surviving Pokemon to carry forward between legs
5. Lineage tracking — Show a Pokemon's journey across legs
6. Cumulative graveyard — Deaths across all legs in one view
7. Gauntlet/Retire HoF rule — Enforce the "retire" mechanic with cumulative dupe list

Success Criteria

• A user can create a new genlocke via a multi-step wizard (name, game selection with presets, rules)
• Games can be selected using True Genlocke, Normal Genlocke, or Custom presets, grouped by region
• Nuzlocke rules are configured once and applied uniformly to all legs
• Genlocke-specific rules (Keep HoF / Retire HoF) can be selected
• The first leg starts automatically upon genlocke creation
• Each leg is a full nuzlocke run, tracked identically to standalone runs
• Completing a leg triggers a transfer step where surviving Pokemon can be carried forward
• Failing a leg marks the entire genlocke as failed
• Completing the final leg marks the genlocke as completed
• A genlocke overview page shows progress, configuration, cumulative stats, lineage, and graveyard
• Transferred Pokemon appear as eggs (base form, level 1) in the next leg
• Pokemon lineage is trackable across multiple legs
• A cumulative graveyard shows all deaths across the entire genlocke
• The Retire HoF / Gauntlet rule correctly retires HoF Pokemon and adds their families to the dupe list