Game World: a walkable RPG view of your finances

## Motivation

Pocket Pixel already frames budgeting as an RPG (Vaults, Recurring Quests, Adventures), but the aesthetic stops at the UI chrome — the actual interaction is still lists and forms. This feature closes the loop: a **top-down, walkable town** where your real financial state _is_ the world.

The core idea that makes this more than a skin: **the world reflects your data**, so exploring the town is a way of reading your finances. A vault that's over budget looks run-down; a healthy one looks prosperous. Walking up to the landlord NPC shows next month's rent. Reaching a savings goal fills a treasure chest with a fanfare.

Buildings = Vaults. Each vault is a structure you enter — the Food Tavern, Rent Keep, Subscriptions Guild. Inside, transactions become items on shelves or a ledger on the wall. A vault over budget looks run-down (cracked walls, storm overhead); a healthy one looks prosperous and lit. That one mechanic turns your whole budget into a glanceable landscape.

NPCs = Recurring Quests. Landlord, Netflix, the gym — each a character who appears on schedule. Talk to them to see the upcoming charge, mark it paid, or snooze it. Month-end, they come to collect.

Treasure chests = Savings goals. A goal is a chest (or half-built castle) that fills in as you save, with a fanfare when you hit it.

Tags = banners/torches decorating the world that double as filters — light a tag's torch to highlight everything tagged with it.

Overworld map = Analytics. Zoom out to a kingdom view where regions scale with spending. And your planned Adventures feature becomes literal — leave town on a journey, enter a "dungeon" that holds that trip's expenses.

A few things to add game juice:

A day/night + month cycle, with month-end as a tally or "boss" screen.
XP and levels for staying on budget; streaks unlock cosmetic tiles, avatar skins, building upgrades.
Weather/seasons that shift with your overall financial health.

**Design principle (non-negotiable):** the Game World is a _view_, not the only way in. Logging a coffee should never require walking across town. There is always a one-tap toggle back to the fast list mode. The world is for motivation and glanceable insight; the existing forms are for speed.

---

## Concept mapping

| Game element | Maps to |
| ---------------------------------------------- | ---------------------------- |
| **Buildings** | Vaults |
| **Building condition** (prosperous → run-down) | Vault budget health |
| **NPCs** | Recurring Quests |
| **Treasure chests / half-built castle** | Savings goals |
| **Banners / torches** | Tags |
| **Overworld / kingdom map** | Analytics |
| **Dungeons / journeys** | Adventures |
| **Player XP / level / streak** | Budget-adherence progression |

---

## Building condition

A building's look is driven by how the vault's month-to-date spending compares to its budget — the further over, the worse it looks. Roughly: comfortably under budget reads as bright and decorated, close to the limit reads as overcast and dim, over the limit reads as cracked with a storm overhead, and a vault with no budget set reads as neutral.

Vaults without a budget should never look like failure — absence of a budget is not overspending.

---

## Open questions

- Does the world stay a static, tap-to-enter scene, or does free movement with a player character earn its complexity?
- Progression (XP, levels, streaks) has to be trustworthy — it should reflect real spending behaviour rather than anything the player can nudge.
- How much of the town's arrangement should the user control versus being generated for them?
- What does the world look like for a brand-new user with one vault and no history?

---

## Staging

Ship incrementally so this doesn't balloon:

**MVP (v1)** — Static town, no free movement. Buildings = vaults, tap to enter. Building appearance reflects budget health. Toggle back to list view.

**v2** — Player character with movement. Recurring Quests as NPCs you walk up to and talk to. Tags as lightable torches/filters. Persist how the user arranges the town.

**v3 (juice)** — XP/level/streak progression surfaced, cosmetic unlocks, day/night + month cycle, month-end tally ("boss") screen, weather/season tied to overall financial health, kingdom/overworld analytics map.

---

## Out of scope (for this issue)

- **Savings goals / treasure chests** — depends on a savings-goal feature that doesn't exist yet; track separately.
- **Adventures/dungeons integration** — wait until the Adventures feature lands, then extend the map.
- **Multiplayer / shared worlds / leaderboards.**
- **Custom map editing by users** (beyond rearranging building positions).
- **Mobile-native gestures beyond tap/drag** — assume the existing PWA touch surface.