Light_And_Dark/light_and_dark/ROADMAP.md

Light & Dark — Roadmap

Destination: polished vertical slice — Regions 1–2, save system, skill upgrades. Proves the core loop is fun before scaling to the full vision.

Design decisions (locked)

• Death penalty: on death, coins drop into a corpse (faded player model) at the death spot; touch it to reclaim them. Dying again without reclaiming keeps only 50% (a new corpse appears, the old one vanishes). Butterfly jars are lost for good on death. Void deaths (falling out of the world) leave no corpse.
• Skill upgrades:
  • Vendor (smith/trainer) gives direct linear power upgrades. Upgrades one selected spell; changing selection costs coins.
  • Gems / rings give alternate behaviors / sidegrades.
• Ranged identity: keep the bolt, add upgrades (no charge-up / homing rework).
• Bosses: after the player first enters a boss's detection range (Light form), it tracks them permanently — ignoring range and Shade. The flying boss (Sky Terror, boss_02) casts a limited number of skills per slam-cycle: normal 1 (2 at ≤33% HP), Hard 2 (all 3 at ≤20% HP). Bosses drop a per-boss token that feeds the Boss Diary.
• Fairy (in slice): guide + ambient light source (bonus flow regen near player). Scout mode, teleport, fairy holes deferred to regions 3+.
• Ascended armor: cut for now. Awakened is good enough at the start; less balancing needed.

Milestones

M0 — Foundation (the game remembers)

Item	Effort	Notes
Save/persistence system	L	DONE (2026-09-28): JSON save to saves/, save via pause menu. Stores player state, room, coins, equipment, inventory, quests, tokens, boss diary, defeated bosses, broken doors.
Charge -> Flow rename	S	Code + UI + configs.
Main menu	M	DONE (2026-09-28): Select Game (greyed with no saves), New Game (name entry), Settings (rebinding), Quit. Wipe-all-saves button (bottom right) with confirmation dialog.
Lantern save points	M	DONE (2026-09-29): Lanterns are explicit save points — walk up and press F to save; you respawn at your last lantern. Visible radius removed.

M1 — Region 1 complete loop

Item	Effort	Notes
Death penalty (drop coins, reclaim at death spot; fairy marks it; lose on 2nd death)	M	DONE (2026-09-29): corpse at death spot holds 100% of coins; a repeat death before reclaiming keeps only 50% and the old corpse vanishes. Butterfly jars are lost for good on death.
Fairy companion (guide + ambient light source -> bonus flow regen)	M	DONE (2026-09-29): fairy follows behind the player's head; flips with facing.
Flying boss + boss tokens	M	DONE (2026-10-05): Sky Terror (boss_02) in room_08 — 51 HP, poison-free slam, skill-cycle phases (2 at ≤33%). Drops a per-boss token feeding the Boss Diary; Hard refight (room_boss_fly_refight) starts at 2 skills/cycle and hits all 3 at ≤20% HP.
More quests (repeatable + one-time; system exists)	S	Just content.
Lore dialogue for fairy / NPCs	S	Needs written copy.

M2 — Skill upgrades

Item	Effort	Notes
Vendor (smith/trainer) NPC	M	Reuses NPC + coin systems.
Vendor upgrades (linear): Dash = lower cooldown, Ranged = more damage, Tether = longer bind/fear	S	Data + UI.
Ring slot + gems (sidegrades): Dash = speed-stacks / refund-on-kill / afterimage taunt; Ranged = pierce (light) / aoe (shade) / kill-stacks; Tether = boss effects / higher threshold	L	New slot, new item type, build UI.

M3 — Region 2: shade matters

Item	Effort	Notes
Shade-gated interactions (doors, an NPC, an area)	S-M	Room JSON + existing toggle.
New enemy behaviors (patrol, dodge-and-leap, burrow-shooter)	M	Enemy system supports it.
Enemy line-of-sight detection (radius -> raycast)	S-M	Replace/augment the euclidean aggro in Enemy.update with a Rect.clipline raycast against solid platforms so walls block vision. Per-type "detection": radius/los config in enemy_types.json + editor toggle. Edge cases: skip the enemy's own support platform, sample player center+feet for tolerance, apply LOS to boss slam trigger_close/far.
Quick recharge pickup	S	DONE (2026-09-29): butterfly jars — collect up to 3, press G to instantly refill Charge. Lost on death; respawn at their points after saving at a lantern in a different room or reloading.
Ability tweaks: ranged upgrades, ground-slam knockback/iframe, light-step buffs	M	Picks up remaining notes ideas.
Region-2 boss + ability pacing	M	Re-align pacing (Ranged already exists).

Stretch / core (post-slice, in order)

• Map system (current-room minimap -> world graph -> lantern fast travel) — see below
• Fast travel (rune stones)
• Fairy scout + bond teleport + fairy holes
• Regions 3-5 per pacing notes
• World-change weapon (stretch-end, decide variant)

Cut

• Ascended armor (removed).

Map system (deferred — brainstorm, not started)

Feels huge; split into two independent features rather than one.

1. Current-room minimap — cheap and self-contained: scale room_bounds + platform rects + a player arrow into a corner/overlay panel. No new data, no persistence. Good first slice.
2. World map / region graph — nodes = rooms, edges = exits[] (derivable automatically from room JSON rather than hand-authored).

Design notes

• Layout: add meta.map_x / meta.map_y (+ optional meta.region) per room and place nodes in the editor; fall back to auto-layout from exit topology if absent.
• Discovery: persist visited_rooms and discovered_links alongside the existing lantern-only save data. Undiscovered = "?" / fog.
• Theme hook: map clear in Light, fogged/faded in Shade, or fog dispelled by lanterns — reinforces the light/shade identity (keep it cosmetic).
• Fairy as cartographer: she fills in rooms and comments on new ones; reuses her room-aware voice lines and mirrors the Boss Diary UI pattern.
• Fast travel: discovered lanterns become warp nodes; overlaps with the deferred "rune stones" / "fairy bond teleport" items.
• Edge cases: one-way exits, boss-refight rooms, the missing room_town_gloomreach.json, exits with empty to (ignore), multiple entry spawns = one node.

Phasing

1. Current-room minimap overlay.
2. visited_rooms + world map from auto-derived exit links (auto-positioned).
3. Manual map_x/map_y layout in the editor.
4. Lantern fast travel + fairy-bond teleport.

Dependencies

• Save is the keystone: death penalty, main menu, and any progress feature hang off it.
• Fairy and Flow rename can run in parallel with M0.