last-hearth/docs/roadmap.md

# Season VI implementation roadmap — The Last Hearth

Updated: 2026-11-02. Carried forward from the authoritative engine-checkout
document, doc/season-vi-roadmap.md, into this standalone game repository. Links
are adapted locally; the delivery strategy, M0–M6 scope, dependencies and gates
are retained. Status distinguishes implementation, automated evidence and
operator/human acceptance; it does not invent tester feedback or approval.
Feature IDs refer to the [launch checklist](launch-features.md).

**Current state: M0 technical gates complete; M1 implementation and automated /
native preflight complete, human acceptance pending; M2 implementation and
automated technical verification complete, human acceptance pending; M3
implementation and automated verification complete, two-player acceptance
pending; M4 technical implementation and automated verification are complete,
with its week-long group acceptance pending.** M2/M3 progress does not waive the
open M1 human gate. See
the [M0 evidence ledger](m0-decisions.md#verification-and-acceptance-ledger),
[M1 evidence](m1-verification.md), [M2 record](m2-verification.md) and [M3 record](m3-verification.md).
Windows checks ran on the existing development host, not a clean machine.
Linux/macOS paths are unit-tested only; native execution is unverified. Browser
launch readiness is not promised. Current release candidate contract is Luanti
**5.18.0**, game **0.5.0-m4**, save schema **1**. M4's human exit gate and all
earlier human/operator gates remain open.

**New ecosystem and journal/art pass:** original Dynamic Life-inspired succession
and the eom.dev Mocha botanical field journal are implemented as a further working
increment, not a new release. Main integrated tests and native visual validation
for this increment remain pending; earlier automated results below are historical
evidence, not validation of the new tree. See [living ecosystems](ecosystems.md),
[art direction](art-direction.md), and the [append-only M4 update](m4-verification.md#botanical-journal-and-ecosystem-survey--pending-main-validation).

## Delivery strategy

Build small playable increments, with a working saved world at each milestone.
First establish feel and a satisfying evening; then progression and sustainability;
then a safe public service. Presentation, accessibility, tests and performance are
part of each increment, not a final cleanup phase.

There is **no launch date commitment** yet. The breadth of original art, animation,
game systems and possible engine changes warrants milestone-based planning.
Estimate calendar dates after M1 establishes scope and available contributor time.
Treat effort as implementation + assets + tests + playtest revision, not Lua alone.

## Current baseline: M0 foundation through M3 home-building slice

Already present: standalone game loading, gathering/crafting, first-night needs and
queued hearth jobs, a versioned home and safe arrival, bounded room/vent shelter,
a small structural palette with refused unsafe support removal, shared claim roles
and protected storage, smooth movement/stamina, animated player/tools, material
feedback, opt-in sparring, a disposable movement course, and approximate solar/
climate behavior. M1 and M3 human acceptance and performance measurement remain open.

M0 adds an independent versioned game package, split module responsibilities,
schema validation/legacy migration, offline snapshot/restore/recovery tooling,
runtime isolation and fixture/production guards. See the
[actual module contracts](architecture.md) and [decisions](m0-decisions.md).
Integrated checks, fresh exports and Windows GUI play are verified; retained
old-save recovery evidence is qualified by its earlier package digest. M0 technical
completion is not operator acceptance or launch readiness.

Not established: fun progression, production-quality controls/combat/art, renewable
settlement economy, complete offline simulation, public multiplayer security,
browser parity, or clean-machine releases. Do not equate passing tests with launch
readiness.

## M0 — Establish a maintainable game and a shared rules contract

**Goal:** make subsequent work reproducible and prevent expensive incompatible choices.

Primary features: F11, F12, F17–F19. Prerequisite: P0.

1. Extract the game into its own content repository/package while preserving history
   and keeping a reproducible engine integration. Do not discard the current world.
2. Pin the stock engine baseline and document local/staging/production data paths;
   make the launcher/install process work on the intended development platforms.
3. Split responsibilities: player state, clock/climate, construction, interactions,
   inventory/processes, UI, encounters and persistence. Preserve behavior with tests.
4. Introduce schema/version identifiers, validation and migrations before new saved
   item/process formats. Add pre-migration backup and restore fixtures.
5. Agree on minimum supported hardware, concurrent-player test target, client
   platforms, browser launch status, and measured latency/performance budgets.
6. Record decisions on death/recovery, initial progression ceiling, calendar display,
   offline processing and claim boundaries. Select the community location before
   staging climate balancing; local worlds retain their own selection.
7. Preserve a deterministic first-session fixture and explicit summer/winter/date
   fixtures. Production configuration cannot accidentally enable test shortcuts.

**Exit gate:** a clean checkout runs tests and opens a versioned prototype;
the old save restores; scope decisions and unresolved risks have owners.

**Status qualification:** M0 technical exit gates are complete for the verified
Windows development path: integrated tests, clean temporary package exports,
isolated GUI play, retained copy-only recovery and owned decisions/risks. This is
not a clean-checkout/new-machine or Linux/macOS native certification, and no
user/operator sign-off is invented. Hardware/network figures are
[provisional acceptance targets, not measurements](m0-decisions.md#provisional-performance-acceptance-targets--not-measurements)
and remain M1 measurement/review work, not an open M0 performance gate.
User/operator approval of the community location is required before shared-world
climate staging; the M0 synthetic 45°N, 0°E fixture is not production selection.
M2 changes do not alter the historical M0 evidence or approval status.

## M1 — Make five minutes of interaction feel good

**Goal:** make moving, gathering, placing and one encounter enjoyable before adding grind.

Primary features: F01, F02, F09, F14, F15; F17 client decision. Prerequisite: M0.

**Implementation:** movement/stamina model, fresh isolated course, original skinned
and animated player/tool meshes, material/attack audio, contextual target and
placement feedback, and opt-in mobile sparring are implemented. The stationary
practice target remains for comparison. The stock engine is the deliberate M1
baseline: current features do not justify a custom client/protocol fork, though
future measured playtest evidence may change that decision. Browser launch remains
unpromised.

**Automated/native preflight evidence:** 31 Node tooling/asset tests pass; the real
engine compiles 36 Lua files and passes 13 isolated suites totalling 228 checks;
native check/smoke passes. The separate headless course preflight verifies staging
and observes 41,041 untouched volume nodes before player consent. Mock course tests
verify generator geometry/checkpoints. Neither constitutes human traversal or fun.

**Human acceptance remains open:** the user/regular testers should use the
[M1 playtest instructions and evidence](m1-verification.md), run the route and
moving spar repeatedly, and record actual FPS, server-step, corrections and
latency on the documented envelope. No group playtest or performance measurement
is claimed. M2 implementation proceeds only by explicit user direction; this does
not mark M1 accepted.

## M2 — Make the first night a complete game

**Goal:** a satisfying arrival → tools → fire → food/water → temporary shelter loop.

Primary features: F03, F06, F08, F10, F11, F14, F15. Prerequisite: M1.

**Implementation:** bounded safe-arrival/home revalidation; home points restricted
to the player's own claim; inventory-preserving death with partial needs recovery;
firestarter ignition, craftable torch, queued six-second cooking/four-second
boiling, persistent output collection, bedroll rest, searchable recipe/process
guide and an eight-seed real-engine mapgen check were delivered in **0.3.0-m2**.
Player needs remain paused offline; fuel/jobs expire by absolute real-time deadline.
No crop, spoilage, comprehensive shelter, or civil-timezone system is implied.
The M1 human gate remains open; implementation proceeds under explicit user direction.

**Technical verification:** compilation, integrated real-engine checks, Node tooling
tests and all eight fixed-seed starts pass on the documented Windows setup. Named
results and limits are in [M2 verification](m2-verification.md).

1. Implement safe arrival/home validation and multi-seed resource checks. Remove
   inappropriate underground auto-teleport and handle pending/failed emergence.
2. Add contextual harvesting and a searchable recipe/process guide; rebalance
   ingredient costs from observed play rather than arbitrary scarcity.
3. Add ignition, torches/lamps, timed cooking and boiling with visible process state.
4. Make a lean-to, bedroll, first meal and clean water achievable; include useful
   nighttime activities because real-world time is not accelerated.
5. Tune need rates and recovery, initial grace and death consequences. No free
   survival refill exploit and no punitive tutorial-death loop.
6. Validate date/location, season extremes, sky approximation and timezone labeling;
   add weather transitions and clearly disclosed synthetic conditions.

**Exit gate:** five unfamiliar testers attempt the first 30–60 minutes without
coaching. Most can identify a danger and correct it; failures reveal actionable
feedback, not hidden recipes. Summer and winter versions both have feasible starts.

**Operator prerequisite:** approve shared community coordinates and explicitly
configure `hearth_latitude`/`hearth_longitude` before community climate staging.
Do not silently promote M0 fixture coordinates. Civil timezone policy/display
also needs an explicit decision when implemented; none is invented here.

**Human acceptance remains open:** five unfamiliar testers must attempt the first
30–60 minutes without coaching, across summer/winter starts, and report actionable
feedback. M2 implementation supports moving into M3 engineering, but M2 is not
accepted until that gate and operator review are recorded. Community coordinates
still require explicit operator selection before shared climate staging.

## M3 — Make a home worth improving

**Goal:** construction solves practical survival problems and supports personal expression.

Primary features: F04, F05, F08, F13, F15. Prerequisite: M2.

**Implementation:** bounded 7 × 7 × 5 room flood-fill with one-second cache and
structure-edit invalidation; roof/door/vent shelter and smoke classification;
stone foundations, timber frames, stairs, doors, windows, roof vents; support-aware
refusal of unsafe removals; household resident/storekeeper roles; private storage,
drying rack and a reusable rain cloak. The historical M3 release was **0.4.0-m3**. Details and
named technical evidence are in [M3 verification](m3-verification.md).

**Technical verification:** the pinned real-engine smoke, isolated room/access/
construction/storage/schema/persistence suites, and Node tooling/assets tests pass.
M3 adds versioned access data under schema 1; old saves receive an empty access
map. No separate migration format is claimed.

Decision boundaries: support removal is refused, not cascaded. Room probing fails
exposed for unloaded/unknown cells and is limited to 245 voxels. Windows and
materials are prototype approximations, not a fully simulated cabin or structure.

**Human/operator acceptance remains open:** the exit gate needs two real players to
build and share a cabin, confirm room/vent feedback and verify outsider denial; it
has not been performed in this technical session. The M1 repeat-play/performance
gate remains separate. This implementation proceeds under the user's explicit
direction so M4 engineering may begin, but M3 is not marked accepted until observed
two-player results are recorded.

1. Introduce foundations/frames and the small complete architectural palette.
   Add preview, rotation, stairs, doors, windows and a functional vent/chimney.
2. Replace the ray heuristic with bounded room/roof detection and cached invalidation
   when relevant blocks change. Verify correctness before adding more simulation.
3. Implement useful material/weather protection, clothing and drying, and a
   dependable relationship between ventilation, fire and indoor comfort.
4. Apply support rules to additions/removals consistently. Prevent hazardous
   cross-claim effects and test restart/unloaded structural changes.
5. Add protected storage/workstations, household roles and visible claim boundaries.
6. Complete the first cohesive set of building textures, sounds and animation.

**Exit gate:** two players build and share a small functional cabin without an admin;
its protection and comfort outperform a lean-to for explainable reasons. Another
player cannot steal, flood or undermine it through an unhandled interaction.

## M4 — Make the next week worth playing

**Goal:** complete a small, sustainable survival progression rather than an infinite checklist.

Primary features: F03, F07–F09, F11, F12; extend F15. Prerequisite: M3.

1. Add renewable forage/timber, a few crops, wildlife population limits and a
   noncombat food path. Test community harvesting pressure near arrival.
2. Implement pottery/storage and preservation before enabling consequential
   spoilage. Preserve age and quantities through every inventory operation.
3. Add the first useful metal tier: find source material → prepare fuel → process
   at a workstation → make a visibly better tool. Keep the chain short enough
   to finish and maintain without mandatory specialist classes.
4. Add modest material/climate variation to make ordinary journeys worthwhile;
   give players preparation and route choices without authored adventure content.
5. Finalize bounded offline/unloaded processing, historic climate accounting and
   process-completion idempotency. Publish the exact offline contract.
6. Tune temporary shelter, established home and seasonal preparation together.
   Do not require daily maintenance or real months to test winter.

**Exit gate:** a small group plays several sessions over at least a week, returns
after absences and chooses new personal goals. Preservation works before harsh
decay is enabled. Loaded/unloaded outcomes agree and economic conservation holds.

**Technical status:** implementation and automated engine, ecology/process,
tooling/assets and eight fixed-seed checks are complete on the existing Windows
host. See [M4 evidence and the offline contract](m4-verification.md). This permits
M5 engineering to begin under the user's direction; it does not mark M4 human-
accepted or claim the loaded/unloaded group observations have occurred.

**Further ecosystem/presentation implementation (validation pending):** the guide
now prioritizes Living ecosystems over the optional Riverward goal. Original
loaded-only succession connects light/moisture competition, meadow/flower/fern
niches, slow tree stages and nutrient/decomposer feedback to bounded wildlife.
`/ecosystem` and the guide's Ecosystem survey observe a fixed habitat patch and
active global species totals, without mutation, spawning or force-loading.
Fishing recipes/process entries remain searchable for compatibility; fishing
mechanics and nodes are unchanged by this UI pass.

The shared journal treatment follows local eom.dev Mocha anchors with restrained
mauve/teal/yellow accents, pressed-sprig dividers, consistent buttons/fields/lists/
tooltips, seven bounded sidebar entries and readable content/footer spacing.
Inventory lists, transfer rings and permissions retain their behavior. The HUD
adds labeled percentages and colored reserve tracks on a dark panel; the hotbar
tiles one authored slot ten times and uses the matching selection outline.
See [ecosystem contracts](ecosystems.md) and [original art contracts](art-direction.md).
Focused journal regression results are recorded in the M4 appendix; full main
validation, native visual review and every human acceptance gate remain open.

**Landscape/diversity integration:** the [content expansion](content-expansion.md)
installs seasons → diversity → succession, then biome-owned terrain/species
registrations → diversity canonical nodes → seasonal variants → wildlife.
The old duplicate mapgen block is replaced, not stacked. Copper tool inputs and
a quartz window alternative extend resource utility; coal fuel/copper smelting
remain with the process integration owner. New worlds receive explicit broad
v7 relief and a ±4096 bound; saved mapgen/seed/bounds and generated chunks are
not rewritten. New ungenerated chunks in old worlds may have visible seams.
Focused tests cover registration/art/recipe contracts and unchanged saved metadata.
The earlier eight-seed evidence is historical, not certification of this preset:
native high-altitude emergence, species-aware resource/spawn checks, saved preset
verification, visual review and human acceptance remain required.

## M5 — Closed community alpha on the real deployment path

**Engineering status:** the first M5 slice now defines a private, digest-pinned
Kubernetes staging contract in [ansible-role-luanti](../../ansible-role-luanti/README.md).
Its direct Jinja render and fail-closed configuration checks pass offline. No
server image has been built, no cluster has been contacted, and no deployment is
claimed. See [M5 engineering verification](m5-verification.md).

**Goal:** prove the game can be shared, operated and recovered—not merely run locally.

Primary features: F12, F13, F16–F19. Prerequisite: M4.

1. Build pinned game/server/client artifacts and a non-destructive staging
   deployment. Adapt or replace the old server role rather than assuming it fits.
2. Configure shared coordinates/timezone and access policy; remove debug grants
   and test-only privileges. Preserve native game credentials initially if linking
   is not yet ready; never ask players to reuse platform passwords.
3. Add moderation/reporting, production validation, security review, performance
   telemetry and resource budgets. Exercise invalid/malicious client inputs.
4. Test restart, outage, disconnect, concurrent workstation use, full storage,
   migrations and representative sustained multiplayer load.
5. Implement platform account linking and optional moderated Matrix bridge with
   outage/loop tests. Add a minimal Play page and season feedback thread.
6. Take a consistent backup, deliberately break a staging instance, and restore
   the complete world/player/process state. Record measured recovery objectives.

**Exit gate:** invited regulars can install/join from clean clients; no critical
data-loss/duplication/protection defect; recovery is demonstrated, not theoretical.

## M6 — Release candidate and public Season VI launch

**Goal:** ship an honest, polished and supportable experience.

Primary features: acceptance of all required F01–F19. Prerequisite: M5.

1. Freeze features; fix blockers, balance and usability rather than introduce new
   mechanics. Complete asset attribution, controls, accessibility and UI review.
2. Repeat first-night, nighttime, winter-arrival, week-away and clean-install
   tests on the release artifacts, not just development builds.
3. Publish supported hardware/clients, installation/join guide, survival/offline
   rules, moderation/privacy policies and incident/support channels.
4. Prepare screenshots and a short authentic gameplay trailer. Schedule an
   optional community first-evening stream; the game must not depend on the stream.
5. Verify production storage/backups, rollback, secrets and location configuration.
   Keep the previous season archived/available under an explicit transition policy.
6. Announce launch only after signing off the checklist with recorded evidence.

**Exit gate:** no unresolved critical defects; a self-directed fun first session;
repeat-session evidence; measured performance at the declared target; a rehearsed
operational recovery. A calendar deadline never overrides those gates.

## Dependency summary and safe parallel work

**Critical path:** M0 → M1 → M2 → M3 → M4 → M5 → M6.

- Art/audio and UI can progress alongside each milestone using the current playable
  loop; do not produce a large asset library before scale/style are validated.
- Deployment/backup scaffolding starts in M0 and can develop alongside gameplay;
  public-server signoff waits for actual state/process schemas and exploits tests.
- Identity/Play-page work can begin after M0's platform decision, but integrations
  must not delay proving that survival is fun or become gameplay dependencies.
- Conservation/persistence testing starts in M0 and expands with every new item,
  process and permission; it is not deferred until M5.
- Defer worldgen-breaking changes until a migration/new-world decision is documented.
  Do not silently regenerate regions containing player work.

## M1 status and remaining acceptance

M1 implementation and automated verification are complete for this slice. See
[M1 evidence and playtest instructions](m1-verification.md). The 31 Node tests,
228 Lua checks, pinned-engine smoke, and native no-consent course preflight pass.
M1 is **not human-accepted**: real route traversal, several voluntary repeat
testers, measured frame-time/network/load data, and the stock/custom decision
remain outstanding. M2 implementation is proceeding by explicit user direction;
this does not mark M1 accepted. M0 extraction and save/recovery work are not
repeated.

## M1 course fixture specification (implemented; human runs pending)

**Fixture identity:** a versioned, isolated staging course, separate from M0
seed/date scenarios in [scenario definitions](../tests/fixtures/scenarios.json).
The bounded generator, consent command and checkpoint/timing callbacks are
implemented in [course.lua](../mods/hearth/course.lua). The launcher always creates
a fresh nonce-marked `course` world; production and the preserved play world are
not eligible. Headless `test:course` is a no-consent preflight only. To generate
the route and kit, launch `node scripts/run.mjs course` and opt in with `/course`.
Never build the course in the preserved world.

- **Isolation and repeatability:** separate absolute `HEARTH_HOME`, explicit engine
  executable, dedicated `staging` configuration when network testing, fixed seed
  731104, recorded layout revision and exact start/end positions. Use synthetic
  45°N, 0°E clear summer conditions for the reference run; repeat winter/rain as
  a variant. This choice is only a course fixture, not community location approval.
  Fuel still follows real time even when climate preview time is fixed.
- **Reset contract:** the launcher creates a fresh world and nonce for each course
   session; `/course retry` resets only the current participant's timer/kit/route.
   For *measured repeats*, launch a fresh course world to avoid terrain/entity
   accumulation. No original survival-world snapshot is used or modified. Fixture
   gear and test shortcuts remain unavailable in production. Record cold asset load
   separately from warm traversal.
- **Route (about five minutes, not a measured result):** level walk/start/stop and
  turning; long sprint to exhaustion/recovery; jump and 0.6-step-height boundary;
  rough terrain/slopes; one-node and two-node doorway widths, corners, stairs and
  low ceilings; water entry/exit/swimming and shore edges; controlled short falls
  and recovery; repeat the route in reverse. Label geometry dimensions and record
  any expected obstruction separately from a collision trap. Doors/stairs here
  are test geometry, not a claim that new craftable building parts exist.
- **Interaction stations:** gather flint/stick/timber samples; compare
  knife/axe/spear use, targeting/reach/occlusion, supported and intentionally
  unsupported placement, protected-edge denials and full-inventory behavior.
   Use the stationary target as a control and opt in to `/spar` for the moving
   training opponent. Neither one is wildlife AI or a PvP mode.
- **Controls/accessibility:** record bindings, sensitivity, camera/FOV settings,
  camera-motion preferences and input devices. Evaluate keyboard/mouse first;
  additional devices/platforms get explicit results, not assumed parity.
- **Load/network matrix:** run an unshaped reference and RTT 0/80/150 ms with
  20 ms jitter and 1% loss; document actual achieved shaping and direction.
  Traverse alone, then with up to 10 concurrent real clients on 4 vCPU/8 GB.
  Fake sessions do not satisfy multiplayer evidence. Use the provisional
  4-core/8 GB/integrated OpenGL 3.3 client at 1080p low/view 96; target 60 FPS,
  p95 frame time ≤25 ms and p95 server step ≤50 ms. These are targets, not data.
- **Evidence:** record revision/package inventory, host/OS/GPU/driver/settings,
  warmup and timed sample duration, frame-time distribution, server steps, memory,
  corrections/stalls and invalid action handling. Keep an issue log with route
  station, reproduction, observed versus expected behavior and severity. Use
  opt-in anonymized observations; private coordinates/account data stay out of
  public reports. Report failed and incomplete runs, not just averages.
- **Telemetry limit:** `/course report` exposes checkpoint/time progress, engine
   globalstep `dt` p95 and course-callback wall duration p95. It explicitly does
   **not** profile client FPS, rendered frames, or CPU usage. Obtain those using
   client instrumentation and record the actual network shaper configuration/results.
- **Acceptance:** several testers choose to repeat the loop; no known collision
  traps or timing exploits, readable distinct tool/encounter feedback, and a
  written stock-versus-custom decision supported by measurements. Performance
  target revisions must be explicit, not relabeled passes. Browser testing is
  conditional on a separate launch-scope decision, never assumed from native tests.
No human route run or performance matrix is currently recorded. The M1 evidence
document explains safe use of `/course`, `/course report` limitations and the
remaining user/operator gate.

## How progress is tracked

For each feature, record: owner, milestone, dependency IDs, code/asset changes,
save impact, automated test evidence, playtest observations and open defects.
Statuses: planned → implementation → automated verification → playtest → accepted.

After every milestone, decide **continue, revise, or reduce scope**. Reduce breadth
(creature count, material count, decorative variants) before cutting movement feel,
clear feedback, sustainable play or save safety. Any change to a required feature
must be reflected in the checklist, not hidden by marking the milestone complete.