Lots of content

docs/roadmap.md

@@ -0,0 +1,430 @@
+# 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.