⌂ HearthHold

From v1.0 onward

Roadmap

HearthHold ships in milestones — each one a player-facing slice of value. There is no final version; the game's design intent is endless.

v1.0 Tech Demo

Place a House, Farm, and Trading Post. Assign workers. Watch food and gold tick up. Reach pop 50 to see the first milestone. Single map, single run, no save.

 v1.5 Persist + Prologue

Save and resume. Settings menu. A short framing intro for first-time players. Tooltip pass complete.

 v2.0 Building Progression ★

The headline feature. Buildings earn XP as they produce, the player spends skill points on upgrades, and fully-upgraded buildings Prestige into V2 forms with new visuals and mechanics.

 v2.5 Visible Citizens

Animated passive walkers wander between buildings. Decorative-only. The town finally looks alive.

 v3.0 Endless Ladder

Milestones at pop 100, 250, 500 — each unlocking visual world changes and new building types. Months of progression headroom.

 v3.5 Procedural Worlds

Procedurally generated maps with named scenarios. Replay value scales from "play to milestones" to "play with seeds."

 v3.7 Living World

Visitors, farm animals, wildlife. The town is no longer alone — it's part of an ecosystem.

 v3.8 Multiple Cities + Trade

Found and manage multiple settlements. Establish trade routes between them. From town builder to kingdom builder.

 v4.0 Mods & Themes

Community mods add buildings, milestones, and visual themes. Data-driven from the foundation up.
Read the full roadmap document

Strategic roadmap by milestone — what slice of player-facing value lands when. Pairs with VISION.md (the WHY). This doc is the WHAT. Replaces the original phase-based ROADMAP.md (still kept as historical build-order reference). Authored 2026-06-02. Updated at every milestone close.

How this roadmap works

  • Milestones are release-shaped slices of player-facing value (not engineering phases).
  • Each milestone delivers a coherent player experience that's playable end-to-end.
  • Epics under each milestone group related work; tasks are derived from epics in t0ggles.
  • Milestones execute roughly in order, but later ones can be partially explored sooner if they unblock or de-risk.

v1.0 — "Tech Demo" (in flight — closing soon)

What the player can do: place a House, Farm, and Trading Post on a 40×40 grid; assign workers; watch food/gold tick up; reach pop 50 to see the first milestone banner. No save, no advancement, no story. Single map, single run.

Status: Phases 1-4 complete. Phase 5 (Art Swap & Polish Leaves) in flight. ~90% to ship.

Epics

  • ✅ Foundation, building runtime, core loop (Phases 1-3)
  • ✅ HUD, feedback, win banner, speed controls (Phase 4)
  • 🟡 Art swap — Kenney GLB visuals via Asset Forge composition (tasks -39, -42, -43)
  • 🟡 Juice polish — camera ease, placement scale-in, hover outline, counter tweens, goal toasts, starter city
  • ⬜ v1.0 ship gate — final UAT pass, perf smoke at 50 buildings, README + screenshots

Ship criteria: all of the above done + the player can play 3-8 minutes to pop 50 without bugs.

v1.5 — "Persist + Prologue"

What the player can do: everything in v1.0, plus save and resume their run. The first time they launch the game, they see a short framing intro ("you arrive at a clearing…"). Tooltips everywhere. Settings menu for volume + keybinds.

Why this milestone before v2.0: Save/load is a hard prerequisite for v2.0 (building progression has per-building state that must persist between sessions). Settings + intro are small enablers that round out the v1 experience.

Epics

  • Save/Load v1 — ResourceSaver-based snapshot of GameState + placed buildings + economy state. user://save.tres. Single autosave slot.
  • Prologue intro — first-launch flavor text card: "displaced settler arrives at a clearing." Skippable. Light prose, no engine work.
  • Settings menu — volume sliders (Master/Music/SFX), keybind remapping, fullscreen toggle. Persisted via ConfigFile.
  • Tooltip pass complete — verify every interactive Control has a tooltip (most done in v1.0, audit + fill gaps).
  • Polish pass — anything that surfaced from v1.0 ship that didn't block release.

Player experience target: a returning player loads their save, sees their existing town, picks up where they left off.

v2.0 — "Building Progression" ★ (headline feature — needs design pass before planning)

What the player can do: their buildings gain experience as they produce; the player spends earned skill points on per-building upgrades; fully-upgraded buildings "Prestige" into V2 forms with new visuals and new mechanics. Decisions about which upgrades to take first matter for the early game, but all upgrades are eventually unlockable.

Why this milestone: the differentiating feature of HearthHold. Without it, the game is "another small city builder." With it, the game has replay value that scales with player skill and choice.

Design questions to resolve before slicing tasks (separate design doc):

  • How many upgrade nodes per building? (3? 5? 8?)
  • How does XP scale? (linear per output? threshold-based? logarithmic?)
  • What does Prestige V2 change mechanically? (new building type entirely? same mechanics with multipliers? mid-ground?)
  • Skill upgrade UI: opens from BuildingInfoPanel, or separate window?
  • Can V2 buildings further Prestige to V3? (open question — likely defer to v3.0)
  • Are skill points per-building or pooled cross-building? (per-building keeps decisions local; pooled enables strategy)

Epics (provisional — will sharpen during v2.0 design pass)

  • Per-building XP runtime — Building class extended with xp, skill_points, upgrades_unlocked, prestige_level state.
  • BuildingDef skill tree definition — extend BuildingDef.tres with skill node list (name, cost, effect type, effect magnitude).
  • Skill upgrade UI — new panel that opens from BuildingInfoPanel showing the skill tree + spendable points.
  • Prestige system — V2 mesh swap, V2 mechanics, transition animation/feedback.
  • Per-building XP feedback — small +N XP popup on production tick alongside resource popup.
  • Save/load extension — persist per-building progression (depends on v1.5 save infrastructure).

Player experience target: the player who keeps playing past pop 50 (no longer the end) has new things to do — upgrade buildings, hit Prestige, see V2 forms appear in their town.

v2.5 — "Visible Citizens"

What the player can do: see animated citizens walking between buildings — purely decorative, no interaction surface. The town feels alive instead of static.

Why this milestone: v2.0 adds depth to systems; v2.5 adds visual life so the world matches the depth. Decorative-only keeps scope bounded.

Epics

  • Citizen scene + script — Citizen.tscn with Node3D root, walking animation, no AI beyond waypoint pathing.
  • Spawn from buildings — citizens spawn from Houses, walk to assigned workplaces, return on tick boundaries.
  • LOD culling — cap visible citizens (e.g. closest 30 to camera); abstract the rest as counters as today.
  • No interaction — citizens are passive walkers; clicking them does nothing. Buildings remain the sole interactive surface.

Player experience target: the town visibly breathes. Indirect-control purity preserved (citizens never click-able).

v3.0 — "Endless Ladder"

What the player can do: chase milestones beyond pop 50 — pop 100, pop 250, pop 500, etc. Each milestone unlocks new visual changes to the world (terrain transforms, new ambient effects) and new building types. The game now has months of progression headroom.

Epics

  • Milestone framework — milestones defined as .tres Resources with trigger condition + reward bundle.
  • Visual world changes — milestone triggers WorldEnvironment shifts, terrain modifications, particle effects.
  • New building types — at least 4-6 additional building types beyond v1's 3. Building variety enabled by BuildingDef.requires (tech-tree-style unlocks already lock-in-aware per VISION.md).
  • Milestone progress UI — a permanent HUD widget showing progress to next milestone.
  • Save format extension — track which milestones reached.

Player experience target: a player who's played for an hour has a town visibly transformed by the milestones they've passed.

v3.5 — "Procedural Worlds"

What the player can do: start a new run on a procedurally generated map with a unique seed. Multiple starter scenarios with different terrain shapes, resource availability, climate, etc.

Why this milestone: the procedural-sandbox pillar (per VISION.md). Replay value scales from "play to milestones" to "play with different seeds and biomes."

Epics

  • Map generation — replace fixed 40×40 with procedural generation (Perlin/Simplex noise terrain, varied tile types).
  • Scenario seeds — named scenarios (e.g. "The Valley," "The Coast," "The Highlands") that pin generation parameters.
  • Map size config — small / medium / large options at new-game time.
  • Starting conditions variance — different starting resources / pre-placed buildings per scenario.

Player experience target: infinite map variety, structured by scenarios.

v3.7 — "Living World" (horizon — slot tentative)

What the player can do: the world has visible life beyond citizens — customers/visitors flow through the Trading Post, animals appear on Farms, wildlife in the Nature borders. The environment is no longer static dressing.

Why this milestone: completes the "town feels alive" arc. v2.5 added citizens; this adds the rest of the ecosystem.

Epics (provisional)

  • Visiting customers — non-citizen visitors arrive at Trading Posts, walk in/out, leave gold. Visualizes commerce.
  • Farm animals — chickens / cows / sheep wandering Farm tiles based on Farm tier or upgrades.
  • Nature wildlife — passive deer / rabbits in the nature-decal border. Pure decoration.
  • Environmental events (stretch) — seasonal visuals (snow in winter, blossoms in spring) tied to milestone progression.

Player experience target: the town feels like a place people visit, not just a place that exists in isolation.

v3.8 — "Multiple Cities + Inter-City Commerce" (horizon — major scope)

What the player can do: found and manage multiple settlements on the same map (or across linked maps). Trade resources between cities via routes — surplus food from one feeds another, gold flows back along the trade lane.

Why this milestone: scales the game from "build one town" to "build a region." This is when HearthHold becomes a kingdom builder, not a town builder.

Epics (provisional — heavy design work needed)

  • Multi-city architecture — GameState extended to track N cities; UI for switching focus between them.
  • Trade routes — establish routes between cities (or trading posts within a region); resources flow along routes per tick.
  • Inter-city economy balance — preventing degenerate "infinite loop" or "single mega-city" strategies; each city must contribute meaningfully.
  • Region map — zoom-out view showing all cities + trade routes.
  • City specialization (stretch) — buildings or upgrades unique to a city based on its terrain / starting conditions.

Player experience target: the player who's mastered one city has a new game: orchestrating multiple. Replay value scales 10×.

Lock-in risk to watch: this milestone is the one that most stresses the v1 single-GameState architecture. Be ready to refactor GameState into per-city + global state structures.

v4.0 — "Mods & Themes"

What the player can do: install mods that add new buildings, new milestones, or visual themes (e.g. winter, desert, fantasy variants). All gameplay data is data-driven; mods don't require code changes.

Why this milestone: community-driven longevity. Long-horizon and contingent on traction.

Epics

  • Mod loader — load BuildingDef/MilestoneDef/ThemeDef from user://mods/<mod>/ at startup.
  • Theme system — ThemeDef Resource maps building type → mesh + material overrides. Switchable from settings.
  • Mod validation — safe-resource-loader pattern (.tres files can embed scripts; sanitize).
  • Workshop integration (optional, post-v4) — Steam Workshop / itch.io API for one-click mod install.

Player experience target: the game has a community ecosystem, players can customize and extend without modding the codebase.

Status snapshot (2026-06-02)

v1.0  ████████░░  ~90%  — Phase 5 art swap in progress
v1.5  ░░░░░░░░░░    0%  — not started
v2.0  ░░░░░░░░░░    0%  — needs design pass first
v2.5  ░░░░░░░░░░    0%  — gated on v2.0
v3.0  ░░░░░░░░░░    0%  — gated on v2.0
v3.5  ░░░░░░░░░░    0%  — gated on v3.0
v3.7  ░░░░░░░░░░    0%  — "Living World" (customers, animals, wildlife)
v3.8  ░░░░░░░░░░    0%  — "Multiple Cities + Inter-City Commerce" (major scope)
v4.0  ░░░░░░░░░░    0%  — long-horizon (mods, themes)

How tasks derive from this roadmap

  1. VISION.md defines pillars + anti-pillars (the why).
  2. This doc defines milestones + epics (the what).
  3. Each epic is broken into t0ggles tasks at milestone-planning time (the how + when).
  4. Don't pre-plan tasks for milestones >1 release out — the further future, the more design changes. Slice tasks just-in-time per milestone, not all at once.

Currently active task batch (v1.0):

  • -39 ART-WIRE (gated on -42 + -43)
  • -40 ART-CLEANUP (gated on -39)
  • -41 HUD-FIX-COMMIT
  • -38 AF-DOC
  • -42 ART-AUTHOR-FARM (user)
  • -43 ART-AUTHOR-HOUSE (user)

When those land, slice the v1.0 juice tasks (camera ease, placement pop, etc.) and the v1.5 epic tasks.

Living-doc rules

  • Amend this doc whenever a milestone scope shifts or a new milestone is added.
  • Don't delete past milestones — strike-through with a date if removed.
  • VISION.md changes are heavyweight; this doc changes per milestone close.