122 lines
6.7 KiB
Markdown
122 lines
6.7 KiB
Markdown
# acdream documentation map
|
||
|
||
This page is the entry point for project documentation. It distinguishes
|
||
current sources of truth from implementation history so an old plan or issue
|
||
banner cannot silently override the current program state.
|
||
|
||
## Current snapshot — 2026-07-27
|
||
|
||
- **Milestone state:** M3, “Cast a spell,” landed 2026-07-21. M4, “Live in the
|
||
world,” is active.
|
||
- **M4 gameplay program:** resume the pre-M4
|
||
[world-interaction completion program](plans/2026-07-23-world-interaction-completion.md).
|
||
Favorite-spell overflow, status Use/Assess, and the complete assessment
|
||
surface are user-accepted. Equipped-child picking and vendor
|
||
browse/transactions remain Slices 4–6.
|
||
- **Structural/runtime state:** all eight `GameWindow` decomposition slices,
|
||
Modern Runtime Slices A–J, and the connected visual/lifecycle gates are
|
||
complete. `GameWindow` is a 1,622-line composition/callback shell.
|
||
`AcDream.Runtime.GameRuntime` owns canonical session, entity/object,
|
||
gameplay, movement, physics, projectile, environment, and portal state;
|
||
graphical and no-window hosts borrow the same owner graph.
|
||
- **Headless state:** Slice K is complete. `AcDream.Headless` is a
|
||
presentation-free Windows/Linux host with deterministic commands/events,
|
||
shared immutable content, multi-session isolation, reconnect, resource
|
||
telemetry, and 1/5/10/30-session gates. The final two-account native-Linux
|
||
soak completed ten minutes, logged out through ACE, and converged every
|
||
ownership ledger.
|
||
- **Linux graphical state:** Slice L0 and the L1 implementation checkpoint are
|
||
complete at `66f114b2` and `11501d52`. Native Windows passes the active
|
||
modern-GL/audio/window smoke. WSLg X11/Wayland correctly reject their
|
||
missing `GL_ARB_bindless_texture`. Physical-Linux validation and L2–L6 are
|
||
explicitly deferred; resume at the supported AMD/NVIDIA L1 gate.
|
||
- **Completed gameplay gates:** R6 locomotion/collision/projectile/teleport/
|
||
radar, two-client portal-out/materialization, indoor prepared collision,
|
||
loot ordering, local/remote ground drops, and selection-marker lifetime.
|
||
- **Separate visual verification:** issue `#225`, the shared-alpha
|
||
lifestone/particle result; its connected resource-lifetime and performance
|
||
routes pass.
|
||
- **Carried behaviour debt:** issue `#153` (far teleport onto an unstreamed
|
||
edge), `#116` (narrowed slide response), `#235` (capped/RDP jump cadence),
|
||
and the active temporary-stopgap rows in the divergence register.
|
||
- **Divergence audit:** 189 active rows — IA 18, AD 38, AP 91, TS 38, and
|
||
UN 4 — plus retained struck/retired historical rows such as TS-37.
|
||
- **Latest automated baseline:** the Release build succeeds with the 17
|
||
test-project warnings tracked by issue `#228`; 8,826 tests pass and five are
|
||
intentionally skipped. App passes 3,763 / 3 skips. The L1 Windows supported
|
||
smoke and WSLg X11/Wayland negative-capability reports all end with zero
|
||
window/GL/input/audio ownership.
|
||
|
||
## Sources of truth
|
||
|
||
Read these in this order when deciding what to do next:
|
||
|
||
1. [`plans/2026-05-12-milestones.md`](plans/2026-05-12-milestones.md) — the
|
||
active playable outcome, freeze boundaries, and visual gates.
|
||
2. [`plans/2026-04-11-roadmap.md`](plans/2026-04-11-roadmap.md) — strategic
|
||
phase ledger: shipped, active, deferred, and future work.
|
||
3. [`ISSUES.md`](ISSUES.md) — tactical defects and small follow-ups. The status
|
||
inside an issue is authoritative; physical order is not.
|
||
4. [`architecture/retail-divergence-register.md`](architecture/retail-divergence-register.md)
|
||
— every known place runtime behavior can differ from retail.
|
||
5. [`architecture/acdream-architecture.md`](architecture/acdream-architecture.md)
|
||
and [`architecture/code-structure.md`](architecture/code-structure.md) —
|
||
ownership, dependency, update-thread, and extraction rules.
|
||
6. [`architecture/worldbuilder-inventory.md`](architecture/worldbuilder-inventory.md)
|
||
— rendering/DAT code already owned in-tree versus mechanisms still ours to
|
||
port.
|
||
|
||
If these disagree, milestones control the current outcome, the roadmap controls
|
||
work ordering, the issue status controls the individual defect, and the
|
||
architecture documents control implementation shape. Reconcile the stale
|
||
document in the same change; do not leave both claims standing.
|
||
|
||
## Research and implementation records
|
||
|
||
- [`research/named-retail/`](research/named-retail/) is the primary retail
|
||
oracle: named pseudo-C, headers, symbols, and types from the Sept 2013 build.
|
||
- [`research/decompiled/`](research/decompiled/) is the older Ghidra fallback.
|
||
- [`research/`](research/) contains focused pseudocode, traces, fixtures, and
|
||
gate reports. A dated research note records evidence; it does not become a
|
||
new roadmap.
|
||
- [`superpowers/specs/`](superpowers/specs/) and
|
||
[`superpowers/plans/`](superpowers/plans/) are per-slice design and execution
|
||
records. Completed plans remain historical.
|
||
- [`audit/`](audit/) contains completion and conformance audits.
|
||
- [`reference/ace-commands.md`](reference/ace-commands.md) preserves the local
|
||
ACE server's complete in-game command catalog and points to the authoritative
|
||
per-command help surface.
|
||
|
||
## Durable memory
|
||
|
||
- [`../claude-memory/MEMORY.md`](../claude-memory/MEMORY.md) indexes the live
|
||
subsystem memories and the render/physics digests. Read a domain digest
|
||
before changing that subsystem, especially its DO-NOT-RETRY table.
|
||
- [`../memory/`](../memory/) contains stable engineering references such as the
|
||
modern rendering pipeline, two-tier streaming, and toolchain notes.
|
||
|
||
Memory accelerates recall; it does not outrank the canonical documents above.
|
||
When current truth changes, update the relevant canonical document and distill
|
||
only the durable lesson into memory.
|
||
|
||
## Historical and deprecated documents
|
||
|
||
- [`bugs.md`](bugs.md) is the April 2026 bug snapshot. It is preserved for
|
||
archaeology and is not an active ledger.
|
||
- Dated plans and specs describe the decision at that time. Their completion
|
||
wording is historical unless the current milestone/roadmap explicitly links
|
||
the item as active.
|
||
- Old `R1→R8` architecture sequencing is superseded. Current execution comes
|
||
from the milestones and strategic roadmap.
|
||
|
||
## Documentation maintenance rules
|
||
|
||
- Update milestone, roadmap, issue, divergence, architecture, and memory claims
|
||
in the same commit when a shipped change affects them.
|
||
- Keep one issue ID per defect. Narrow an issue in place; do not reuse another
|
||
issue's number as a shorthand.
|
||
- Mark automated, connected, and visual gates separately. An automated pass is
|
||
not a visual acceptance, and an RDP throughput sample is not a local-display
|
||
visual comparison.
|
||
- Preserve research history, but remove stale “current/next” claims from living
|
||
documents once the state advances.
|