diff --git a/CLAUDE.md b/CLAUDE.md index f4a9fcd..f1b8e6e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -202,7 +202,10 @@ retail. Everything else is your call. - Continue to the next planned sub-step of a phase after the previous one lands clean — including immediately starting work on the next phase if the - current one is done + current one is done. **You pick what comes next** per the Milestone + discipline section — never present the user a menu like "should we do X + or Y?" or ask "what next?". Just choose and announce the choice in one + sentence. Work-order selection is Claude's job, not the user's. - Pick between two roughly equivalent implementations; justify the choice in the commit message - Refactor small amounts of surrounding code when genuinely needed to land a @@ -526,6 +529,78 @@ spec path, the files it should read, the acceptance criteria (build + test green), and the commit message style. Subagents inherit CLAUDE.md so they follow the same rules. +## Milestone discipline + +acdream operates at **two altitudes** above the daily commit: + +- **`docs/plans/2026-05-12-milestones.md`** — the morale + scope layer. + Seven milestones (M0–M7) from "Connect & explore" to "v1.0", each + defined by a concrete playable scenario and ~6–10 weeks of work. This + is where you orient when the project feels half-built and you're not + sure what to work on. Phases are too granular to feel like progress; + this doc is the multi-week target. +- **`docs/plans/2026-04-11-roadmap.md`** — the strategic roadmap (next + section). Phase-level index. This is where you orient when you know + the milestone and need the next concrete sub-phase. + +**Currently working toward: M1 — Walkable + clickable world.** L.2 +collision + B.4 interaction. Demo target: walk through Holtburg without +getting stuck, open the inn door, click an NPC, pick up an item. +Estimated 4–6 weeks from 2026-05-12. + +**Work-order autonomy — the meta-rule.** You decide what to work on +next, always. **The user does NOT pick between phases, milestones, or +"what's next?" alternatives.** The milestone discipline + the +per-milestone phase list + the roadmap IS the work order — drive it. +Never ask the user "want me to start X or Y?" or present a menu of +options. If two next steps are genuinely equivalent, state which one +you picked and why in one sentence and start — don't ask. The user +retains the right to redirect if they think you're wrong, but the +default is **Claude drives, user reviews**. The user finds decision +fatigue from constant work-order choices draining — that's literally +what triggered the milestones doc on 2026-05-12. Honoring this rule is +the single biggest morale lever. This is the meta-rule that makes the +four below actually work. + +**The four motivation-keeping rules:** + +1. **One active milestone at a time.** Work that isn't on the critical + path to M1 gets filed in `docs/ISSUES.md` with a `post-M1` tag and + muted. This is the single rule that kills the "jumping between + things" feeling. If a phase isn't part of the current milestone, it + doesn't get touched — even if it's tempting, even if it would be + "quick", even if it would be "while I'm here." + +2. **Frozen phases are off-limits.** M0's ~25 shipped phases are frozen + until M7's polish pass. Concretely: no rework on streaming, chat, + input, the WB rendering migration, sky/lighting, the particle + system, or the network handshake. Those are done. Don't revisit them + — even if you see something that could be 10% better. Visual + nice-to-haves and architecture second-guesses on frozen phases are + explicitly post-M7. The freeze list per milestone lives in the + milestones doc. + +3. **Each milestone hit gets a recorded demo video.** When M1 lands, + record ~30 seconds of the demo scenario, drop it at + `docs/milestones/M1-walkable-clickable.mp4`, and pin a still + a + one-paragraph writeup at the top of `2026-05-12-milestones.md`. The + freeze list updates. The "currently working toward" line in this + CLAUDE.md updates to M2. **Crossing a milestone is a real event with + an artifact** — that's the morale instrument. Phases ship; milestones + land. + +4. **State both altitudes at session start.** First action of any + session: "Currently working toward M1 — Walkable + clickable world. + Current phase: L.2. Next concrete step: [whatever]." This keeps the + high-level orientation visible alongside the immediate task and + makes mid-session drift obvious. + +When reality and the milestones diverge — a phase grows beyond the +milestone's scope, a demo scenario turns out to be unreachable without +a new sub-phase, the order needs reshuffling — update the milestones +doc in the same session you discover the divergence. Same rule as the +roadmap. + ## Roadmap discipline acdream's plan lives in two files committed to the repo: diff --git a/docs/plans/2026-05-12-milestones.md b/docs/plans/2026-05-12-milestones.md new file mode 100644 index 0000000..97816be --- /dev/null +++ b/docs/plans/2026-05-12-milestones.md @@ -0,0 +1,310 @@ +# acdream — milestones (morale + scope layer) + +**Status:** Living document. Created 2026-05-12. +**Sits above:** [`docs/plans/2026-04-11-roadmap.md`](2026-04-11-roadmap.md) (the strategic phase index). +**Currently working toward:** **M1 — Walkable + clickable world.** + +--- + +## Why this document exists + +The roadmap is a phase index — week- to month-scale, ~50 phases by the time +v1.0 lands. Phases ship in vertical slices (architecture-first, horizontal +completion deferred), which is the right strategy for a solo open-source +project at this scale — but it leaves a chronic "everything is half-built" +feeling because no single phase ship feels like a real milestone. + +This document sits **one altitude above** the roadmap. Each milestone is: + +- **~6–10 weeks of focused work** (not a single phase, not a whole year). +- Defined by a **concrete playable scenario** that gets recorded as a demo + video when the milestone hits. +- A **scope-freeze event**: when a milestone lands, the phases it covers go + off-limits until v1.0's final polish pass (M7). + +Crossing a milestone is a real event with an artifact. Phases ship; milestones +**land**. + +--- + +## Operating rules + +1. **One active milestone at a time.** Everything not on the critical path to + the current milestone gets filed in `docs/ISSUES.md` with a `post-MN` tag + and explicitly muted until the milestone hits. This is what kills the + jumping-between-things feeling. + +2. **Frozen phases are off-limits.** "Frozen" means no rework, no polish, no + follow-up commits unless something is actively broken (player crash, + regression). Visual nice-to-haves, "while I'm here" cleanups, and + architecture second-guesses are all post-M7. The freeze is the discipline + mechanism that makes the milestone meaningful — without it, M0's many + shipped phases keep silently consuming attention. + +3. **The milestone log is the morale instrument.** When a milestone hits: + - Record a ~30-second demo video showing the scenario end-to-end. + - Drop it in `docs/milestones/MN-.mp4` (create the directory on + first hit). + - Pin a still frame + one-paragraph writeup at the top of this doc. + - Update the freeze list. Update CLAUDE.md's "currently working toward" + line to the next milestone. + +4. **State both altitudes at session start.** "Currently working toward M1. + Current phase: L.2 collision. Next concrete step: L.2d slice 1 spec." This + keeps the high-level orientation visible alongside the immediate task and + makes mid-session drift obvious. + +--- + +## The milestones + +### M0 — "Connect & explore" — ✅ DONE (crossed months ago) + +**Demo scenario:** Log in, walk Holtburg in chase camera, see other characters +animate, send a chat message and see the echo, watch day turn to night, +listen to footsteps and ambient audio. + +**Phases included (frozen):** + +| Phase | What landed | +|---|---| +| 1–3 | Terrain + per-vertex normals + per-cell texture blending | +| 4 | UDP codec + handshake + character login + WorldSession | +| 5 | ObjDesc: AnimPartChange + TextureChanges + SubPalettes + ObjScale | +| 6.1–6.7 | Motion + animation foundation (idle, frame playback, slerp, UpdateMotion, UpdatePosition) | +| 7.1 | EnvCell room geometry — walls/floors/ceilings | +| 9.1–9.2 | Translucent render pass + back-face culling | +| A.1–A.5 | Streaming landblock loader → two-tier streaming | +| B.1–B.3 | Outbound ack pump + player movement + physics MVP resolver | +| D.1, D.2a | 2D overlay + ImGui scaffold + `AcDream.UI.Abstractions` layer | +| E.1–E.5 | Motion hooks + audio + particles + combat wire + spell wire | +| F.1, F.2 | GameEvent dispatcher + item model + Appraise | +| G.1, G.2 | Sky + day/night + weather + dynamic lighting | +| H.1, I.1–I.8 | Chat wire + UI consolidation + holtburger inbound parity + combat translator | +| K, L.0 | Input architecture + retail bindings + Settings panel | +| N.0–N.6.1 | WB rendering migration (modern path mandatory) | +| C.1, C.1.5a/b | Particle system + portal/EnvCell static-script wiring | +| R.1–R.3 | Retail research infrastructure (PDB extract + named decomp) | + +**Status:** This is everything shipped through 2026-05-12. ~25 phase ships. +**Worth saying out loud: this is the hard half of the project.** The engine +runs, the world renders correctly, the network connects, the input is wired, +the data layers for combat/spells/items/audio/particles all exist. What's +missing is the gameplay loop on top. + +--- + +### M1 — "Walkable + clickable world" — 🟡 CURRENT (~4–6 weeks) + +**Demo scenario:** Walk through Holtburg without getting stuck on the inn +doorway. Open the inn door. Click an NPC and see selection feedback. Pick +up an item from the ground. + +**Phases to ship:** +- **L.2 (all sub-lanes a–f)** — Movement & Collision Conformance. Currently + active; L.2a slices 1+2+3 shipped 2026-05-12. +- **B.4** — `Use` / `UseWithTarget` / `PickUp` outbound messages. + +**Freeze on landing:** +- L.2 zone (collision, cell ownership, transition parity, wire authority) +- B.4 zone (interaction outbound) + +**What "M1 lands" looks like:** the existing Holtburg traversal works as a +retail player would expect. Doorways are walkable. Buildings have solid +walls. Outdoor cell seams report the right cell. Clicking an NPC selects it +and sends a usable selection state to the server. The Use action opens doors. + +--- + +### M2 — "Kill a drudge" — 🔵 NEXT (~6–10 weeks after M1) + +**Demo scenario:** Equip a sword. Walk to a drudge. Swing. See "You hit +Drudge for 12 slashing damage (87%)" in chat. Watch the swing animation +play. Drudge dies, drops loot. Pick up the loot. Open the inventory panel +and see it. + +**Phases to ship:** +- **F.2 (panels)** — Inventory panel reading `ItemRepository` (data already + shipped in F.2 base; M2 ships the visual surface). +- **F.3** — Combat math + damage flow. +- **F.5a** — Visible-at-login dev panels (Attributes, Skills, Equipped, + Inventory list) — minimal ImGui surfaces, retail-skin deferred to M5. +- **L.1c** — Combat animation wiring (draw/sheath, attack swings by + stance/power/height, hit reactions, evades). +- **L.1b** — Command router + motion-state cleanup (prereq for L.1c). + +**Freeze on landing:** +- Combat math zone +- Inventory zone (data + dev panel; retail-skin reopens in M5) +- L.1b/c combat-animation zone + +**What "M2 lands" looks like:** the gameplay loop is real. You can fight, +take damage, kill things, see loot, manage your inventory. The game becomes +a game. + +--- + +### M3 — "Cast a spell" — 🔵 (~3–4 weeks after M2) + +**Demo scenario:** Cast Flame Bolt at a drudge. Watch the cast animation, +the projectile, the impact. Self-cast a buff (Strength Self). See the +enchantment in a buff list. Recall to lifestone — full recall animation, +correct teleport, correct re-spawn. + +**Phases to ship:** +- **F.4** — Spell cast state machine (buffs + recalls first, projectile + spells second). +- **L.1d** — Spell-casting animation wiring (cast command classification, + windup, release, fizzle/interruption, recoil). +- **F.5 (Spellbook panel)** — dev-skin surface for learned spells + active + enchantments. + +**Freeze on landing:** +- F.4 spell zone +- L.1d cast-animation zone +- Spellbook dev-panel surface + +**What "M3 lands" looks like:** mages are real characters. Buffs work, +recalls work, the first projectile spells work. Combat from M2 + casting +from M3 = retail-equivalent gameplay loop for melee and casters. + +--- + +### M4 — "Live in the world" — 🔵 (~6–10 weeks) + +**Demo scenario:** Create a fresh character from scratch (no ACE admin). +Spawn. Talk to an NPC. Accept a quest. Walk to a dungeon entrance. Portal +in (pink-bubble loading). Walk through the dungeon. Complete the quest. +Walk back out. + +**Phases to ship:** +- **H.3** — Emote scripts + quests + dialogs (122 EmoteType × 39 Trigger + mini-VM). +- **G.3** — Dungeon streaming + portal space + `PlayerTeleport` handling. + (Unblocked by L.2e from M1.) +- **H.4** — Character creation (`0xE000002 CharGen` + heritages + appearance + picker + preview). +- **L.1e** — Emote + posture animation wiring. + +**Freeze on landing:** +- H.3 dialog/quest zone +- G.3 dungeon zone +- H.4 character-creation zone +- L.1e emote-animation zone + +**What "M4 lands" looks like:** the world feels populated and interactive. +You can do quests, enter dungeons, create characters. Combined with M2/M3, +the client is **functionally playable** — minus visual polish. + +--- + +### M5 — "Looks like retail" — 🟢 PARALLELIZABLE WITH M3/M4 (~4–8 weeks) + +**Demo scenario:** Side-by-side screenshot of acdream vs retail at the same +location, same time of day, same character. Hard to tell apart at a glance. +Open the inventory panel — retail-skinned with the right font, icons, and +9-slice panel borders. + +**Phases to ship:** +- **C.1.5c** — Sky-PES dispatch chain (closes #2 lightning, #28 aurora, + #29 cloud thinness). +- **C.2** — Dynamic point lights (fireplaces, lamps, torches with proper + local lighting). +- **C.3** — Palette range tuning (skin/hair/eye colors match retail). +- **C.4** — Double-sided translucent polys. +- **D.2b** — Custom retail-look UI backend. +- **D.3–D.7** — AcFont + dat sprites + core panels reskinned + HUD orbs + + cursor manager. +- **L.1f** — NPC/monster + item-use animation coverage. + +**Freeze on landing:** +- Visual polish zone (C.1.5c, C.2, C.3, C.4) +- D.2b → D.7 UI-skin zone +- L.1f NPC-anim zone + +**What "M5 lands" looks like:** the client visually convinces. Screenshots +become postable. The "old / broken vs retail" feeling that drives most of +the chronic ISSUES.md entries is gone. + +--- + +### M6 — "Plugins ship" — 🟢 (~4 weeks) + +**Demo scenario:** A third party (not you) writes a small plugin against +the published API — XP tracker, loot logger, simple chat filter — and it +loads cleanly. Sample plugin lives in the repo with documented build steps. + +**Phases to ship:** +- Plugin API surface: stable contract over `AcDream.Core` + `AcDream.UI.Abstractions`, + versioned, with the world-state interfaces exposed. +- Plugin host: load isolation, lifecycle, error containment. +- Sample plugin (XP tracker or loot logger) — proves the API by using it. +- Plugin docs page. + +**Freeze on landing:** +- Plugin API v1 surface (additive changes only post-freeze). + +**What "M6 lands" looks like:** the differentiator vs the retail client is +real. acdream offers something retail never did, and the API is documented +well enough that other people can build on it. + +--- + +### M7 — "v1.0" — 🟢 (open-ended polish) + +**Demo scenario:** Long-running stress test: log in, play for 4 hours +across outdoor + dungeon + portal + combat + spell + chat scenarios, +reconnect once mid-session, log out clean. No crashes, no protocol errors, +no visual regressions, no audio dropouts. + +**Phases to ship:** +- **Phase M** — Network stack conformance (retransmit, ACK piggybacking, + echo/keepalive, fragment splitting, typed actions). Deferred until now + because ACE handles loss gracefully — but v1.0 needs proper network + hardening. +- **H.2** — Allegiance. +- **N.6 slice 2 + N.7–N.10** — Finish WB rendering migration (EnvCells, + sky/particles via WB, visibility manager, GL infrastructure + consolidation). +- **Phase J long-tail** — Player rig polish, group/fellowship UI, trade + window, salvage/tinker UI, house ownership, society UI, dev-mode tools. +- **L.1g** — Animation polish + conformance. +- Final visual + audio polish pass against ISSUES.md chronic backlog. + +**What "M7 lands" looks like:** v1.0. Ship. + +--- + +## Estimated timeline + +| Milestone | Effort | Cumulative | +|---|---|---| +| M0 | DONE | DONE | +| M1 | ~4–6 wk | ~5 wk | +| M2 | ~6–10 wk | ~13 wk | +| M3 | ~3–4 wk | ~17 wk | +| M4 | ~6–10 wk | ~25 wk | +| M5 | ~4–8 wk (parallel) | overlaps M3/M4 | +| M6 | ~4 wk | ~29 wk | +| M7 | open-ended | v1.0 | + +**Roughly 9–12 months of focused solo work from 2026-05-12 to v1.0.** That's +honest for an open-source project of this scale. The biggest single rock is +M2 (combat math + animations + inventory panels lining up); M5 can be +chipped at in parallel by subagents while you drive M3/M4. + +--- + +## What this document is **not** + +- **Not a release schedule.** Internal morale + scope layer only. If acdream + goes public-alpha at some point, that's a separate decision built on top + of one of these milestones. +- **Not immutable.** When reality and the milestones diverge, update the + milestones in the same session you discover the divergence. Same rule as + the roadmap. +- **Not a replacement for the roadmap.** Phases are still where the + implementation details live. This doc is the orientation layer above them. +- **Not granular enough for daily work.** Daily work happens at the phase / + sub-phase / commit level. The milestone is the multi-week target you're + aiming at.