History

Erik 24834a6478 fix(render): Campaign V slice V6g — the Vulkan frame stops lying to the driver V6f ran the bring-up host once under VK_LAYER_KHRONOS_validation and found seven VUIDs, every one of them on the path any world frame takes (plan §5.5.7). This closes all of them, plus a fourth defect in the same log that §5.5.7 did not call out. The host now runs validation-clean: zero errors and zero warnings over 39,855 frames. Nothing outside Gpu/Vk/ is touched, so the GL backend executes not one changed statement. The offline pixel gate says so too — 4.08e-05 differing fraction against `f8dbe2ee`, which is exactly the value the campaign recorded as its own same-commit control (§5.1's 15–23 pixel band). The dynamic-descriptor limit was a decision, not a patch. V6b declared all ten of set 0's bindings STORAGE_BUFFER_DYNAMIC on the reasoning that the contract lets a renderer bind any range per draw. That is true and still cost nothing to honour for four of them: a dynamic descriptor buys exactly one thing, the ability to address the SAME buffer at a DIFFERENT offset without a descriptor write, which is the shape of a ring allocation and of nothing else. So the ring-fed bindings — instances, batches, clip slots, instance light sets — stay dynamic, and the ones pointing at a long-lived buffer written whole and bound once per pass carry their offset in the descriptor instead. Binding 9 is the clearest of those: it is the GL-only uvec2 handle table, which the Vulkan backend never binds at all. That lands on four dynamic storage descriptors. The RX 9070 XT allows eight, so eight would have worked here — but four is Vulkan's GUARANTEED minimum, which means no conformant device can fail this layout, and V9's lavapipe row and the deferred physical Linux row both depend on that. The count is asserted against maxDescriptorSetStorageBuffersDynamic in the capability record, so a device that cannot serve it is rejected at startup in the report under the same exit-code-4 contract as every other requirement, rather than failing silently at vkCreatePipelineLayout the way this one did. Depth-off pipelines were malformed in any pass that has depth. Dynamic rendering bakes the depth/stencil attachment format into the pipeline and requires it to equal the pass's; V6c set it only when the pipeline itself tested or wrote depth. Debug lines, the retained UI and the sky are all depth-off and all composite over the main pass, so this was not an edge case. The same GpuPipelineDescription is legitimately used both ways — ui-text opens its own depth-less pass — so the description cannot answer the question and the backend builds both variants, binding whichever matches what vkCmdBeginRendering was actually handed rather than what the pass asked for. Both are built at startup against the persisted cache, so no frame compiles one. A slice entitled to change the contract should add a depth-format field the way V6d added ColorFormat; this is the honest expression of the gap until then. vk-backbuffer-depth and vk-backbuffer-msaa-color were created UNDEFINED and never moved. Both now barrier on every backbuffer pass — from UNDEFINED on the first use after Configure, from attachment-optimal with a write-after-write dependency thereafter. The dependency matters on its own account, not just the layout: two passes in one frame write both images and so does the next frame, and Vulkan orders nothing between render-pass instances. The fourth defect is the one worth reading twice. CaptureBackbuffer transitioned the LAST PRESENTED swapchain image to TRANSFER_SRC and copied out of it. After vkQueuePresentKHR that image belongs to the presentation engine and its contents are not ours to read — and the pixels were usually right, which is precisely the problem. This campaign spent three sections of its own plan (§5.5.1–§5.5.3) discovering how much a capture instrument that is "usually right" can cost, and shipping that shape on the new backend would have made every Vulkan PNG, and the V7 differential built on them, formally undefined. The frame now copies its own output into a host-readable buffer while it still owns the image, and the capture reads that. Retention is opt-in, armed when an artifact directory exists: one full-resolution copy per frame is worth nothing to a player and is the entire instrument to a gate. The old one-shot command pool, device-idle wait and per-capture readback buffer go with it. Two gaps found and recorded in §5.5.8 rather than fixed, both outside this slice's brief. UniformSkyParams (set 1, binding 4) is not in the uniform set layout, so whoever first draws sky on Vulkan must add it. And a binding pointed at two different buffers within one frame silently corrupts the earlier draws, on dynamic and plain descriptors alike, because descriptor contents are read at execution time — no consumer does that today, but WbDrawDispatcher and EnvCellRenderer each own their own instance and batch buffers and both bind bindings 0, 1, 3, 4 and 5 in one frame, so the Vulkan world arm has to know before it is written. Gates: Release build; App tests 4,075 passed / 3 skipped (baseline 4,073 + the two new capability cases); GL offline pixel gate PASS at 4.08e-05; one validation-layer Vulkan run, clean, with the captured PNG inspected and correct in orientation, colour and glyph coverage. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>		2026-07-28 10:47:52 +02:00
..
architecture	docs: reconcile project state and refresh README	2026-07-27 12:53:31 +02:00
audit	docs: update audit — Sprint 1 items verified (sequence counters + scenery LCG)	2026-04-13 13:51:39 +02:00
plans	fix(render): Campaign V slice V6g — the Vulkan frame stops lying to the driver	2026-07-28 10:47:52 +02:00
reference	docs(reference): preserve local ACE command catalog	2026-07-27 00:03:58 +02:00
research	docs(linux): park Slice L at L1 checkpoint	2026-07-27 12:35:47 +02:00
superpowers	fix(world): remove non-retail portal exit fade	2026-07-15 23:20:52 +02:00
bugs.md	docs: reconcile project status and navigation	2026-07-20 13:00:41 +02:00
ISSUES.md	docs(render): close V6f's shader obligation; record why the Vulkan world path is blocked	2026-07-28 10:22:57 +02:00
README.md	docs: reconcile project state and refresh README	2026-07-27 12:53:31 +02:00

README.md

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. 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:

plans/2026-05-12-milestones.md — the active playable outcome, freeze boundaries, and visual gates.
plans/2026-04-11-roadmap.md — strategic phase ledger: shipped, active, deferred, and future work.
ISSUES.md — tactical defects and small follow-ups. The status inside an issue is authoritative; physical order is not.
architecture/retail-divergence-register.md — every known place runtime behavior can differ from retail.
architecture/acdream-architecture.md and architecture/code-structure.md — ownership, dependency, update-thread, and extraction rules.
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/ is the primary retail oracle: named pseudo-C, headers, symbols, and types from the Sept 2013 build.
research/decompiled/ is the older Ghidra fallback.
research/ contains focused pseudocode, traces, fixtures, and gate reports. A dated research note records evidence; it does not become a new roadmap.
superpowers/specs/ and superpowers/plans/ are per-slice design and execution records. Completed plans remain historical.
audit/ contains completion and conformance audits.
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 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/ 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 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.

README.md Unescape Escape