nuzlocke-tracker/.beans/nuzlocke-tracker-oqfo--improve-encounter-rate-display-for-timeweather-var.md

title, status, type, priority, created_at, updated_at

title	status	type	priority	created_at	updated_at
Improve encounter rate display for time/weather variants	todo	feature	normal	2026-02-10T14:04:27Z	2026-02-14T21:17:00Z

Problem

PokeDB data reveals that encounter rates vary by context across many games:

• Gen 2/4 (G/S/C, HG/SS, D/P/Pt, BDSP): morning/day/night
• Gen 5 (B/W, B2/W2): spring/summer/autumn/winter
• Gen 8 (Sw/Sh): weather (clear, cloudy, rain, thunderstorm, snow, etc.)
• Gen 8 (Legends Arceus): time + weather boolean conditions
• Gen 9 (Sc/Vi): overworld probability weights

Currently the seed format and RouteEncounter model have a single encounter_rate field, which flattens all of this into one number.

Goal

Extend the data model and UI to support conditional encounter rates, so users can see which Pokemon appear under which conditions.

Design

Seed data format

Add an optional conditions field to encounter entries. When absent, the encounter has a flat rate (Gen 1/3/6 — no change needed). When present, it replaces encounter_rate with per-condition rates:

{
  "pokeapi_id": 163,
  "pokemon_name": "Hoothoot",
  "method": "walk",
  "encounter_rate": null,
  "conditions": {
    "night": 50,
    "morning": 10,
    "day": 0
  },
  "min_level": 2,
  "max_level": 5
}

For games without variant rates, the existing flat encounter_rate field is used unchanged.

Backend changes

1. New model RouteEncounterCondition (one-to-many from RouteEncounter):
   • id, route_encounter_id (FK), condition (string), encounter_rate (int)
   • Conditions are free-form strings: "morning", "day", "night", "rain", "spring", etc.
2. RouteEncounter model: keep encounter_rate as nullable — null when conditions exist, populated when flat.
3. Seed loader: detect conditions key in JSON, create RouteEncounterCondition rows accordingly.
4. API: include conditions in route encounter responses (nested array under each encounter).

Frontend changes

1. AdminRouteDetail: show conditions as sub-rows or a tooltip when hovering the rate column.
2. EncounterModal: group by condition context when relevant (e.g. tabs for morning/day/night).
3. Type updates: extend RouteEncounter type with optional conditions: { condition: string, encounterRate: number }[].

Checklist

• Update seed JSON schema: add optional conditions field to encounter entries
• Create RouteEncounterCondition model with migration
• Make RouteEncounter.encounter_rate nullable
• Update seed loader to handle conditions entries
• Update API serialization to include conditions
• Update frontend types (RouteEncounter)
• Update AdminRouteDetail to display condition-based rates
• Update EncounterModal to show conditions contextually
• Update seed data for at least one game per variant type (HG/SS, B/W, Sw/Sh) as proof of concept
• Keep simple display for games with flat rates (no regression)

Considerations

• For Nuzlocke play, availability ("appears during rain") matters more than exact percentages — consider a simplified view option
• Keep UI uncluttered for simple cases (Gen 1/3/6)
• Condition strings should use a consistent vocabulary (define an enum or reference list)
• Seed data updates for all games can be done incrementally after the infrastructure is in place