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.

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, M1 evidence, M2 record and M3 record. 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, art direction, and the append-only M4 update.

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 and decisions. 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 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, 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.

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.

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. 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 and original art contracts. 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 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. 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.

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. 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. The bounded generator, consent command and checkpoint/timing callbacks are implemented in 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.