erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
acdream/docs/research/2026-08-02-collision-throughput-handoff/NEXT-AGENT-PROMPT.md

13 KiB
Raw Permalink Blame History

Next-agent prompt — finish the retail placement/collision campaign

Continue acdream from the 2026-08-03 stabilization checkpoint. The code is modern; behavior must remain retail-faithful. The campaign is playable again, but it is not closed.

Start here

Use the merged local main worktree:

C:\Users\erikn\source\repos\acdream

The completed fixes originated on codex/port-claude-agents and are merged into local main. Confirm the exact starting commit with git rev-parse HEAD and read the operator's handoff message for the merge SHA. Do not reset, clean, or overwrite the main worktree's untracked research/reference files. The original feature worktree remains at:

C:\Users\erikn\.codex\worktrees\af5e\acdream

That feature worktree contains protected user-local modifications and is not the preferred continuation workspace.

Read these files in order before editing:

  1. CLAUDE.md and AGENTS.md.
  2. docs/plans/2026-08-02-placement-cutover.md — canonical placement-cutover plan and the 2026-08-03 checkpoint.
  3. This prompt.
  4. docs/research/2026-08-02-collision-throughput-handoff/implementer-progress.md — especially ## P1 and the final stabilization checkpoint.
  5. docs/research/2026-08-02-collision-throughput-handoff/p1-retirement-receipt-loop.md.
  6. docs/research/2026-08-02-c3c-cutover-closeout.md.
  7. docs/ISSUES.md #269 and #276–#280.
  8. docs/architecture/retail-divergence-register.md rows AP-1, AP-22, AP-131, AD-1, AD-10, AD-60, and TS-28.

docs-drafts.md is now explicitly historical. Do not apply it wholesale: it predates the final fixes and incorrectly tries to reuse issue number #280.

Binding rules

  • Grep docs/research/named-retail/acclient_2013_pseudo_c.txt by named class::method before fresh decompilation. Retail behavior is the oracle.
  • Preserve the modern Runtime-owned, presentation-independent architecture. Graphical and headless hosts must use the same canonical gameplay owners.
  • Root causes only. Do not add timeouts, grace periods, suppression flags, catch-and-swallow paths, duplicated placement writers, or compatibility bypasses to make a test green.
  • The user's connected observations are acceptance facts. A green automated test cannot overrule a live regression.
  • Never use git add -A, git add ., git reset --hard, or git checkout -- <path>. Stage exact paths only.
  • Do not delete or normalize unrelated/untracked worktree content.
  • Each independent fix must be a bisectable commit whose message records the root cause and evidence.
  • Update the divergence register and issues in the same commit that changes their truth. Retire a row only when its exact legacy mechanism is gone.
  • Do not push unless the user explicitly asks.
  • Connected tests require the user's ACE server at 127.0.0.1:9000. Close the client gracefully before reconnecting so ACE releases the session.

What has been completed

C3c and collision-publication checkpoint

  • 529e0e9d — C3c production first-entry cutover for graphical and headless hosts.
  • 71604331 — O(changed) per-landblock collision publication checkpoint. Its original commit was deliberately marked WIP after the first feel test; do not treat that old label as the current product status. The following fixes addressed the observed failures.

Stabilization fixes, all user-verified where visual behavior applies

  1. 01f4791e — retirement-receipt replay loop fixed.

    • Root cause: a pending-only live-projection bucket was promoted to a second full landblock cleanup receipt after the first detach had already committed. The duplicate guard threw; a broad resumable path replayed the detach 243 times.
    • Fix: retain pending identities without manufacturing another receipt; post-commit receipt invariants are terminal, not resumable.
    • Evidence: focused recenter tests; complete Release suite 10,815 passed / 4 skipped; lifecycle report logs/connected-world-gate-20260802-203751/report.json; nine-stop report logs/connected-r6-soak-20260802-204309.report.json with Passed=true, nine checkpoints, zero failures, zero wait cues, zero pending retirements, and no recurrence of the 243x exception.

  2. 670f307c — remote placement and targeting share one world frame.

    • Root cause: CreateObject positions are landblock-local, but Runtime submitted remote first-entry placement with zero world offset; the local physics host also published a landblock-local origin to targeting.
    • Fix: Runtime owns the accepted local-player world center, converts remote Create placement before SetPosition, and publishes the local body's world position.
    • User gate: monsters and statics place correctly; monsters chase and hit the visible player instead of attacking another coordinate.

  3. 1fc529cd — distant Use/approach restored.

    • Root cause: Runtime object lookup is intentionally non-constructing, so a static door/corpse could enter MoveTo without a physics host and its target snapshot expired at the origin. Startup placement could also leave an impossible pre-PartArray motion suffix ahead of later actions.
    • Fix: ensure the canonical minimal static host before routing MoveTo and reconcile the startup suffix exactly at presentation attach.
    • User gate: near and distant object use works, including approach, turn, and use after arrival.

  4. f24532ad — spell, recall, projectile, and static VFX binding fixed.

    • Root cause: C3c could create effect/projectile/static-animation sidecars before first SetPosition had bound the entity's mesh, pose, cell, and visibility. One-shot F754/F755 packets were lost and projectiles could inherit a cell-less body.
    • Fix: exact-incarnation presentation barrier and FIFO replay; retry projectile/static binding on the committed visibility edge; synchronize effect cells on rebucket.
    • User gate: buffs/protections, recall effects, arrows, combat spell projectiles, portals, and static animation all work.

  5. 175ad6b0 — login materialization acknowledgement fixed.

    • Root cause: ACE creates the local player Hidden and releases that state on LoginComplete. Sending LoginComplete from raw F746 receipt raced first canonical placement and left the purple haze over the character.
    • Fix: one completion callback from Runtime's local first-entry terminal edge; content-less headless retains its only truthful accepted-Create edge.
    • User gate: ordinary login no longer leaves the purple haze; recall still has the intended materialization presentation.

Latest focused verification

After the final fix, these passed:

  • 90 focused App effect/projectile/static-animation scheduler tests.
  • Two focused Runtime login-completion tests.
  • The exact live-entity cell-tracking regression.
  • All 79 Headless tests.
  • dotnet build AcDream.slnx -c Release --no-restore with zero errors (existing warnings remain).

The long complete suite and connected nine-stop soak were not rerun after the final four stabilization commits. The P1 soak proves P1's binary, not the final campaign binary.

What remains — execute in this order

1. Reconcile the six selected-fixture failures

A broad selected run after cleanup exposed:

  • five failures in LiveEntityRuntimeTests, associated with the still-open placement/cell cutover;
  • one old RuntimeLiveEntitySessionControllerTests remote-first-entry fixture that provides an empty collision source while the production contract now requires truthful collision admission.

Re-run these two classes first and record the exact test names and assertions. Classify each as either a real product failure or a stale fixture. If stale, update the fixture to provide the same valid prepared collision neighborhood as production; never weaken the product contract or merely change expected values. If real, fix the owning production mechanism and add a smaller regression test.

Suggested first commands:

$env:ACDREAM_PAK_PATH='C:\Users\erikn\Documents\Asheron''s Call\acdream.pak'
dotnet test tests/AcDream.App.Tests/AcDream.App.Tests.csproj -c Release --no-restore --filter FullyQualifiedName~LiveEntityRuntimeTests -m:1
dotnet test tests/AcDream.Runtime.Tests/AcDream.Runtime.Tests.csproj -c Release --no-restore --filter FullyQualifiedName~RuntimeLiveEntitySessionControllerTests -m:1

2. Finish C4: remaining authoritative placement routes

The plan still marks routes 2–7 open:

  • route 2: ForcePosition;
  • route 3: portal placement through RuntimeWorldTransitState and RuntimePortalPlacementAuthority;
  • route 4: remote Create/Position, deleting the remaining RemoteTeleportController/inline MoveOrTeleport duplicate;
  • route 5: authoritative projectile correction;
  • route 6: drops and split-recovery marking;
  • route 7: pickup, parent-detach, and delete/recreate residue.

Inventory every current writer before editing. For each route, prove:

  • one Runtime SetPosition transaction owns accepted frame, exact cell, collision result, shadow/workset membership, and deferred-cell lifetime;
  • App only projects the committed result;
  • graphical and headless hosts use the same command and state path;
  • stale sequences, delete/GUID reuse, missing cells, portal generations, and replacement collision generations cannot commit old state;
  • no route reconstructs from a stale spawn or uses the legacy outdoor demote/ terrain-Z lift.

Resolve #276 when the spawn settler's resolved CellId becomes authoritative. Resolve #277 with a real service-window/celless lifecycle instead of relying on ACE's current broadcast radius.

3. Fix #280: destination prefetch before portal reveal

Current behavior waits only a hard-coded radius-one (3x3) outdoor neighborhood, while the visible configured world extends farther. The user can see distant terrain continue building after portal exit.

Port the retail mechanism, not a larger magic number:

  • CellManager::PreFetchCells @ 0x00455820;
  • LScape::PreFetchCells @ 0x00505660;
  • CLandBlock::PreFetchCells and CLandBlockInfo::PreFetchCells;
  • SmartBox::UseTime @ 0x00455410 while blocking_for_cells;
  • the TAS_TUNNEL_CONTINUE resume/reveal order.

Use the quality/view-distance configured destination window. Hold one generation-scoped reservation across terrain, buildings/statics, EnvCells, render publication, composite textures, and collision. Keep portal UI and wait cue responsive. Never reveal early because of a timeout, and do not wait for an impossible terminal marker for all dynamic ACE objects.

Acceptance: repeated login, /ls, spell recall, and portals at every quality setting reveal no constructing terrain, missing nearby statics/buildings, unready interiors, missing composites, or absent nearby collision. Dynamic monsters/items may still arrive later from ACE.

4. C5 closeout and live gates

After steps 1–3:

  1. Delete every superseded placement writer and compatibility projection.
  2. Run focused Runtime/Core/App tests for every route.
  3. Run the complete Release solution suite with the installed pak.
  4. Run the exact lifecycle/reconnect route.
  5. Run the canonical nine-stop soak on the final binary. Read report.json, not marker output. Required: Passed=true, zero failures, every canonical checkpoint, waitCueShown=false, zero pending publication/retirement/reveal debt, graceful exit, and no render-shadow mismatch. Diagnose any real failure; do not rerun past it.
  6. Perform two-client observation for remote creation, chase/attack, doors, drops/pickups, portal departure/arrival, arrows, and spells.
  7. Ask the user for the remaining #269/#278 slope-glide comparison at the known impassable slope.

Only then retire AP-1, AD-1, AP-131, and the legacy half of AD-60 and close the corresponding placement issues.

5. Finish the original physics-divergence campaign

After placement C5 is green:

  • AP-22: make ShadowShapeBuilder the sole authority for authored Setup collision shapes. Preserve cylinder order; use authored spheres when there are no cylinders; cylinder-first for mixed data; truly shapeless means no shadow. Remove invented Setup.Radius cylinders, Radius * 2 heights, and sphere-to-cylinder coercion across graphical, headless, static, and live paths.
  • AD-10: prove remote motion uses the full transition sweep, remove terrain-normal preprojection, and let CTransition::adjust_offset project against the actual retained contact plane. Preserve interpolation, correction replacement, Hidden state, and network cadence.
  • Run the final movement/collision matrix and update the divergence ledger, architecture, roadmap, milestones, memory, CLAUDE.md, and AGENTS.md. Resume vendor Slice 5 only after this campaign is genuinely closed.

Required deliverable

For every remaining item report:

  • observed failure and deterministic reproduction;
  • retail/reference evidence with named functions and addresses;
  • root cause in plain language plus file/line evidence;
  • exact fix and why it preserves Runtime ownership;
  • tests added or corrected;
  • commit SHA;
  • complete build/test/connected-gate numbers;
  • user visual result where required;
  • divergence/issue rows retired, narrowed, or left open.

Finish with an explicit list of anything still open. Do not describe the campaign as complete while any C4 route, #280, final-binary soak, AP-22, AD-10, or required user visual gate remains.