e77dd7c413
The client reads 161 ACDREAM_* environment variables across 79 files. Only about 25 were written down, and the audit found the documentation drifting in both directions: CLAUDE.md still advertised ACDREAM_RUN_SKILL / ACDREAM_JUMP_SKILL (deleted; skills are server-authoritative now, and the jump fallback is 300, not the documented 200), while flags with real side effects had no description at all. docs/launch-options.md documents every one by lifecycle — production, command line, measurement, automation, permanent diagnostics, temporary probes, deprecated, retired — with a mandatory side-effects column. That column is the point: #432 cost three days of taxed measurements because ACDREAM_AUTOMATION_ARTIFACT_DIR reads like an output path and also builds a per-frame diagnostics referee, and ACDREAM_STREAM_RADIUS silently measures a streaming window production never uses. Rows now say so. Other surprises the audit surfaced and recorded: ACDREAM_DUMP_SCENERY_Z swaps in a duplicate scenery-placement path rather than only logging, ACDREAM_PROBE_VIS silently also enables ACDREAM_PROBE_ENVCELL, and ACDREAM_DUMP_ENTITY's id list doubles as an unrelated probe's watchlist. LaunchOptionsDocumentationTests enforces it, because a hand-maintained list of 161 flags is stale within a week: an undocumented flag fails, and so does a documented row whose read site was deleted. It scans string literals rather than GetEnvironmentVariable call shapes — the startup path reads through an injected delegate, so a call-shaped pattern silently missed ACDREAM_LIVE, ACDREAM_PAK_PATH and every other production flag. A third test freezes per-file direct-read debt by exact count (20 files outside the owner classes), so structure rules 4 and 5 can be paid down but not regressed. CLAUDE.md's 94-line env-var section becomes a 16-line pointer, and its stale test-character paragraph is corrected. Also fixed, all doc-vs-code mismatches the audit proved: - RenderingDiagnostics.FrameProfEnabled described a GPU-query self-disable that Campaign V slice V11 deleted. - Two comments named ACDREAM_RENDER_BACKEND as a live co-requisite; it died with the OpenGL backend. - EnvCellRenderer.CollectCellAuditLines and its ACDREAM_A8_AUDIT doc: the method had no caller anywhere and its documented caller never existed. Filed rather than fixed, to keep this a documentation change: #434 (the DebugPanel/DebugVM surface is never constructed, so ~40 "runtime-toggleable" comments are false and 35 env reads are unreachable) and #435 (17 temporary probes outlived their closed investigations; 14 more name no owner). Full hermetic suite 12,202 passed / 0 failed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
132 lines
7.3 KiB
Markdown
132 lines
7.3 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.
|
||
- [`ci-and-releases.md`](ci-and-releases.md) is the SSOT for the Gitea CI
|
||
pipeline, the self-hosted runners, and how alpha releases are published.
|
||
Load-sensitive tests live in `Lane=Timing`; see
|
||
[`release-gate.md`](release-gate.md) before adding to it.
|
||
- [`launch-options.md`](launch-options.md) is the SSOT for every environment
|
||
variable and command-line argument the client reads, including what each one
|
||
changes about the run beyond its obvious effect. Read the side-effects column
|
||
before trusting any measurement. Enforced by
|
||
`LaunchOptionsDocumentationTests`: a flag without a row fails the build, and
|
||
so does a row whose read site was deleted.
|
||
- [`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.
|