From e4030cb2a3f72b60f79e8cece3ea7cb563217a6b Mon Sep 17 00:00:00 2001 From: Ael Date: Tue, 21 Jul 2026 17:47:58 +0200 Subject: [PATCH] Docs: add pre-feature polish train roadmap --- docs/design/roadmap.md | 4 + .../warpkeep-pre-feature-polish-roadmap.md | 124 ++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 docs/planning/warpkeep-pre-feature-polish-roadmap.md diff --git a/docs/design/roadmap.md b/docs/design/roadmap.md index e4ec225..122ad14 100644 --- a/docs/design/roadmap.md +++ b/docs/design/roadmap.md @@ -1,5 +1,9 @@ # Warpkeep roadmap +The current pre-feature polish train is maintained in the [pre-feature polish +roadmap](../planning/warpkeep-pre-feature-polish-roadmap.md). Follow its serial +dependency order and guardrails before starting new horizontal systems. + Warpkeep is building a persistent strategy world one playable loop at a time. Dates and feature order may change as the Alpha is tested. diff --git a/docs/planning/warpkeep-pre-feature-polish-roadmap.md b/docs/planning/warpkeep-pre-feature-polish-roadmap.md new file mode 100644 index 0000000..a71f0d3 --- /dev/null +++ b/docs/planning/warpkeep-pre-feature-polish-roadmap.md @@ -0,0 +1,124 @@ +# Warpkeep pre-feature polish roadmap + +This document defines the reviewable polish train for the Alpha before new +horizontal gameplay features are added. It is planning guidance, not an +authorization to merge, publish, seed, deploy, activate, or mutate production. +Each implementation PR must refresh repository state, open PRs, tags/releases, +worktrees, and production status before editing. + +## Baseline + +- Repository: `ael-dev3/Warpkeep` +- Planning checkpoint: `main` at `582441671f7ad41158ef7117d28985608d3fa96a` +- Checkpoint release: Alpha 0.3.13 — The Living Lowlands +- Backend protocol: 3 +- Schema tail: `realm_water_revision_v1` at append-only reference 46 +- Renderer: React + TypeScript + Three.js r185 with a custom WebGL scene + +The checkpoint is historical. Implementation branches must verify the current +remote `main` and production state again; no version, deployment, or backend +assumption in this document is permanent. + +## Why this train comes first + +The current Alpha has a substantial world and rendering surface, but several +player-facing systems are still architectural prototypes: + +1. A Realm graphics, model, or context failure can still expose a terminal + illustrated fallback instead of recovering the real scene. The fallback + should remain a bounded compatibility surface, never a post-ready renderer + state. +2. Food, Wood, Stone, and Gold are presented as resource-specific singleton + expeditions rather than four stable workers. The world has no public worker + ID, ordinal, roster, dedicated worker inspector, individual recall, or + recall-all command. +3. Resource accrual still exposes pending balances and explicit collection. + Completed server time appears as “ready to collect,” which feels like + confirming a database deposit instead of commanding workers. +4. Water topology is strong, but Water v1/v11 is early visual work: wave + brightness modulation does not displace the surface or provide analytic + normals, shore/crest/river foam, or an inspectable Water record. +5. Heath blooms and purple semantic tint are intentional renderer content, but + conflict with the desired lush Lowlands art direction. +6. The immutable shared forest is sparse for a 10,000-cell world. Denser + presentation needs camera-local, bounded ecology rather than an unbounded + global tree increase. + +The next feature after this train should return to the published product loop: + +`resources → one durable keep improvement → visible persistent result → return testing` + +## Serial PR sequence + +Prefer this integration order. A draft may be stacked on the exact predecessor +head when parallel work is necessary, but its dependency must be explicit and +it must not merge out of order. + +| Order | Title | Invariant | Prompt | +| --- | --- | --- | --- | +| 1 | Fix Realm renderer recovery and remove the terminal world fallback | A real renderer recovers or fails explicitly without replacing a ready world with a full-world SVG | `01_Warpkeep_Realm_Renderer_Recovery_PR_Prompt.txt` | +| 2 | Gameplay: add four generic castle workers and automatic settlement | Four durable worker identities gather and settle server-authoritative resources automatically | `02_Warpkeep_Generic_Four_Worker_Authority_Automatic_Settlement_PR_Prompt.txt` | +| 3 | UX: give workers a dedicated command center and world identity | Worker roster, IDs, commands, recall, and world markers are coherent and inspectable | `03_Warpkeep_Worker_Command_Center_World_UX_PR_Prompt.txt` | +| 4 | UX: make visible Water cells selectable and inspectable | Water selection and records use the same identity-safe interaction model as other world targets | `04_Warpkeep_Selectable_Water_Cells_Inspector_PR_Prompt.txt` | +| 5 | Visual: add real Water motion, foam, and atmospheric fog | Water motion and atmosphere are layered, bounded, and compatible with fallback, mobile, and reduced motion | `05_Warpkeep_Layered_Water_Foam_Fog_PR_Prompt.txt` | +| 6 | Visual: remove purple ground clutter and unify the lush Lowlands | Heath, grass, terrain, and lighting share one readable Lowlands palette | `06_Warpkeep_Lush_Lowlands_Palette_Grass_PR_Prompt.txt` | +| 7 | Visual: add dense bounded forest ecology | Forest density increases locally and deterministically without changing shared authority or exhausting budgets | `07_Warpkeep_Dense_Forest_Ecology_PR_Prompt.txt` | + +PR 1 is currently represented by open renderer-recovery PR #80 and its focused +follow-up #82; neither is part of this documentation-only change. Do not +duplicate that diff. Any follow-up should state whether it is stacked on that +branch and should preserve its exact dependency. + +## Dependency and conflict model + +Use a serial train: + +`PR 1 → PR 2 → PR 3 → PR 4 → PR 5 → PR 6 → PR 7` + +PRs 1, 3, 4, and 5 touch shared Realm interaction and rendering surfaces. +PRs 3 and 4 both extend pick arbitration and inspector state. PRs 5, 6, and 7 +share environment, terrain, vegetation, and rendered QA surfaces. Independent +large branches would recreate the integration risk that motivated this train. + +Do not use open PR #79 as a base. It is an unrelated README restoration. Do not +close, retarget, or modify it without explicit owner instruction. Keep the +renderer PRs and this planning document independent. + +## Reviewability limits + +Each PR should target one independently understandable invariant and preferably +stay below 80 changed files and 8,000 net new lines. Do not mix backend +authority with a major visual redesign unless the prompt explicitly requires +the boundary. Every PR body must state its exact base and head, what changed, +what did not change, checks run, and residual risks. + +If an implementation exceeds these limits, split it at the architecture +boundary rather than compressing a release megadiff into one review. + +## Guardrails for every implementation PR + +- Refresh `main`, open PRs, tags/releases, worktrees, repository instructions, + and production state before editing. +- Distinguish source readiness from deployed, seeded, activated, or verified + production state. +- Preserve auth version 2 unless a separate security review requires a change. +- Preserve append-only SpacetimeDB schema order and generated-binding checks. +- Use `--delete-data=never` for any separately authorized publication. +- Keep browser presentation non-authoritative; FIDs, balances, cargo, + idempotency, ownership, and operator data remain private and server-owned. +- Preserve non-WebGL, keyboard, touch, reduced-motion, and mobile paths. +- Run the full repository check, focused tests, and rendered QA appropriate to + the change. +- Report residual risks honestly. +- State explicitly that no merge, deploy, publish, seed, or activation occurred. + +## Out of scope during this train + +Do not add keep construction or upgrade queues, combat, armies, raids, +alliances, trade, chat, boats, swimming, fishing, naval mechanics, another +resource family, a second world-generation expansion, wallet/token/Marks +spending, a second renderer or animation scheduler, destructive migrations, +generic open image proxies, or unreviewed external art. + +The purpose of this train is to make the existing Alpha coherent, legible, +recoverable, and satisfying before it becomes broader.