# Phase B.5 — BuildPickUp + ground-item interaction — Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Close M1 demo target 4/4 — make F-key pick up the currently-selected ground item by sending ACE's `PutItemInContainer (0x0019)` GameAction. **Architecture:** Mirror B.4b's outbound `BuildUse` chain. Add one new wire-builder (`InteractRequests.BuildPickUp`) and one new GameWindow helper (`SendPickUp`); wire the F-key action into the existing `OnInputAction` switch using the existing `_selectedGuid` field. The ACE inbound handlers (`InventoryPutObjInContainer 0x019B`, `RemoveObject`) are already wired in `GameEventWiring.cs` and will despawn the ground item once ACE acknowledges the pickup — no inbound work needed. **Tech Stack:** C# / .NET 10 / xUnit (existing). Wire format: `BinaryPrimitives.WriteUInt32LittleEndian` little-endian envelope same as every other `0xF7B1` GameAction in the file. --- ## Predecessor & branch state - **Branch:** `claude/phase-b5-pickup` in worktree `.claude/worktrees/investigate-npc-click`. - **Main HEAD at start:** `e7842e0` — Merge B.4c. - **Existing commits on branch:** `86440ff` — the B.5 handoff doc (`docs/research/2026-05-13-b5-pickup-handoff.md`). --- ## Wire format (verified against ACE source) `references/ACE/Source/ACE.Server/Network/GameAction/Actions/GameActionPutItemInContainer.cs`: ```csharp var itemGuid = message.Payload.ReadUInt32(); var containerGuid = message.Payload.ReadUInt32(); var placement = message.Payload.ReadInt32(); ``` `references/ACE/Source/ACE.Server/Network/GameAction/GameActionType.cs:13`: ``` PutItemInContainer = 0x0019, ``` Therefore the full **24-byte** GameAction body is: | Offset | Field | Bytes | |---|---|---| | 0 | `0xF7B1` (GameAction envelope) | 4 | | 4 | `gameActionSequence` | 4 | | 8 | `0x0019` (PutItemInContainer subopcode) | 4 | | 12 | `itemGuid` (u32, the server guid of the ground item) | 4 | | 16 | `containerGuid` (u32, the player's server guid) | 4 | | 20 | `placement` (i32, 0 = let server choose slot) | 4 | **NB:** The handoff doc (`2026-05-13-b5-pickup-handoff.md`) said "20-byte total body." That was an arithmetic error in the handoff — corrected here. --- ## File structure (which files touched) - **Modify:** `src/AcDream.Core.Net/Messages/InteractRequests.cs` — add `PutItemInContainerOpcode` constant + `BuildPickUp(seq, itemGuid, containerGuid, placement)` builder. - **Modify:** `tests/AcDream.Core.Net.Tests/Messages/InteractRequestsTests.cs` — add a unit test for `BuildPickUp` covering byte layout + opcode. - **Modify:** `src/AcDream.App/Rendering/GameWindow.cs` — add private `SendPickUp(uint itemGuid)` helper next to `SendUse`; add `case InputAction.SelectionPickUp` in the `OnInputAction` switch. No new files. No tests for the GameWindow helper (it's a thin pass-through wrapper around `_liveSession.SendGameAction` mirroring `SendUse`, which itself has no unit test for the same reason). --- ## Task 1: TDD — InteractRequests.BuildPickUp **Files:** - Modify: `tests/AcDream.Core.Net.Tests/Messages/InteractRequestsTests.cs` - Modify: `src/AcDream.Core.Net/Messages/InteractRequests.cs` - [ ] **Step 1: Write the failing test.** Append this new `[Fact]` immediately after `BuildUseWithTarget_WritesBothGuids` in `tests/AcDream.Core.Net.Tests/Messages/InteractRequestsTests.cs`: ```csharp [Fact] public void BuildPickUp_WritesOpcode0x0019AndPayload() { byte[] body = InteractRequests.BuildPickUp( gameActionSequence: 5, itemGuid: 0xABCDu, containerGuid: 0x5000000Au, placement: 0); Assert.Equal(24, body.Length); Assert.Equal(InteractRequests.GameActionEnvelope, BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(0))); Assert.Equal(5u, BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(4))); Assert.Equal(InteractRequests.PutItemInContainerOpcode, BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(8))); Assert.Equal(0xABCDu, BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(12))); Assert.Equal(0x5000000Au, BinaryPrimitives.ReadUInt32LittleEndian(body.AsSpan(16))); Assert.Equal(0, BinaryPrimitives.ReadInt32LittleEndian(body.AsSpan(20))); } ``` - [ ] **Step 2: Run test to verify it fails.** ```powershell dotnet test tests/AcDream.Core.Net.Tests/AcDream.Core.Net.Tests.csproj ` --filter "FullyQualifiedName~InteractRequestsTests.BuildPickUp" ``` Expected: build fails with `CS0117: 'InteractRequests' does not contain a definition for 'BuildPickUp'` (and a second error for `PutItemInContainerOpcode`). - [ ] **Step 3: Add the constant + builder.** Edit `src/AcDream.Core.Net/Messages/InteractRequests.cs`. Add this opcode constant immediately after the existing `TeleToLifestoneOpcode` declaration (~line 31): ```csharp public const uint PutItemInContainerOpcode = 0x0019u; ``` Then append the new builder method immediately after `BuildTeleToLifestone` (~line 75, just before the closing `}` of the class). Use the same `XmlDoc + BinaryPrimitives` style as the existing builders: ```csharp /// /// Pick up a ground item or move an item between containers. The /// server places the item in at /// the given slot (pass 0 to let the /// server choose). For F-key ground-pickup, pass the player's own /// server guid as . /// /// /// Wire layout (ACE GameActionPutItemInContainer.Handle): /// /// u32 0xF7B1 /// u32 gameActionSequence /// u32 0x0019 // PutItemInContainer /// u32 itemGuid // server guid of the item /// u32 containerGuid // destination container (player or bag) /// i32 placement // 0 = server picks slot /// /// /// public static byte[] BuildPickUp( uint gameActionSequence, uint itemGuid, uint containerGuid, int placement) { byte[] body = new byte[24]; BinaryPrimitives.WriteUInt32LittleEndian(body, GameActionEnvelope); BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(4), gameActionSequence); BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(8), PutItemInContainerOpcode); BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(12), itemGuid); BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(16), containerGuid); BinaryPrimitives.WriteInt32LittleEndian (body.AsSpan(20), placement); return body; } ``` - [ ] **Step 4: Run test to verify it passes.** ```powershell dotnet test tests/AcDream.Core.Net.Tests/AcDream.Core.Net.Tests.csproj ` --filter "FullyQualifiedName~InteractRequestsTests.BuildPickUp" ``` Expected: 1 passing, 0 failing. - [ ] **Step 5: Commit.** ```powershell git add src/AcDream.Core.Net/Messages/InteractRequests.cs ` tests/AcDream.Core.Net.Tests/Messages/InteractRequestsTests.cs git commit -m "feat(B.5): InteractRequests.BuildPickUp — PutItemInContainer 0x0019" ``` --- ## Task 2: GameWindow integration — SendPickUp + OnInputAction case **Files:** - Modify: `src/AcDream.App/Rendering/GameWindow.cs` This task does NOT include new tests. `SendPickUp` is a 6-line passthrough that gates on `InWorld` state and routes to `_liveSession.SendGameAction`. It mirrors `SendUse` (also untested by unit tests) and is verified end-to-end via the in-world visual check in Task 3. - [ ] **Step 1: Add the `SendPickUp` helper.** Locate `SendUse` (currently around line 8870 in `src/AcDream.App/Rendering/GameWindow.cs`). Insert this new helper immediately after `SendUse`'s closing brace: ```csharp private void SendPickUp(uint itemGuid) { if (_liveSession is null || _liveSession.CurrentState != AcDream.Core.Net.WorldSession.State.InWorld) { _debugVm?.AddToast("Not in world"); return; } var seq = _liveSession.NextGameActionSequence(); var body = AcDream.Core.Net.Messages.InteractRequests.BuildPickUp( seq, itemGuid, _playerServerGuid, placement: 0); _liveSession.SendGameAction(body); Console.WriteLine($"[B.5] pickup item=0x{itemGuid:X8} container=0x{_playerServerGuid:X8} seq={seq}"); } ``` - [ ] **Step 2: Wire the F-key action.** Locate the `OnInputAction` switch's `case InputAction.UseSelected` (currently around line 8745). Insert a new case immediately after it: ```csharp case AcDream.UI.Abstractions.Input.InputAction.SelectionPickUp: if (_selectedGuid is uint pickupTarget) SendPickUp(pickupTarget); else _debugVm?.AddToast("Nothing selected"); break; ``` - [ ] **Step 3: Build the whole solution.** ```powershell dotnet build -c Debug ``` Expected: build succeeds with zero errors. (Existing warnings unchanged.) - [ ] **Step 4: Run the full test suite.** ```powershell dotnet test -c Debug --nologo ``` Expected: 1047 passing, 8 failing (8 pre-existing baseline failures from main HEAD; same count as before B.5). The new `BuildPickUp_WritesOpcode0x0019AndPayload` test contributes +1 passing. - [ ] **Step 5: Commit.** ```powershell git add src/AcDream.App/Rendering/GameWindow.cs git commit -m "feat(B.5): SendPickUp helper + F-key SelectionPickUp wiring" ``` --- ## Task 3: Visual verification in live client **Not a code task — user-driven acceptance test.** Run the launch recipe, drop a test item, click-then-F. - [ ] **Step 1: Kill stale client + wait for ACE session cleanup.** ```powershell Get-Process -Name AcDream.App -ErrorAction SilentlyContinue | Stop-Process -Force Start-Sleep -Seconds 20 ``` - [ ] **Step 2: Launch the client (background).** ```powershell $env:ACDREAM_DAT_DIR = "$env:USERPROFILE\Documents\Asheron's Call" $env:ACDREAM_LIVE = "1" $env:ACDREAM_TEST_HOST = "127.0.0.1" $env:ACDREAM_TEST_PORT = "9000" $env:ACDREAM_TEST_USER = "testaccount" $env:ACDREAM_TEST_PASS = "testpassword" $env:ACDREAM_DEVTOOLS = "1" dotnet run --project src\AcDream.App\AcDream.App.csproj -c Debug 2>&1 | Tee-Object -FilePath "launch-b5.log" ``` - [ ] **Step 3: User-driven test scenario.** Hand off to user for visual verification: 1. ACE drops a test item near `+Acdream` (server `/drop` slash command, or whatever ACE supports for the testaccount). Specify what item type was dropped in the verification report. 2. **Single-click the item** — `[B.4b] pick guid=0x` should appear in the log. The selection toast should show the item name. 3. **Press F** — `[B.5] pickup item=0x container=0x5000000A seq=` should appear in the log. 4. **Item should disappear from the ground** (ACE acks → `RemoveObject` → existing despawn path removes it from view). 5. **No regressions on door interaction:** double-click the inn door, observe it swings open as in B.4c. 6. **Bonus: NPC chat check.** Click an NPC, observe the chat panel. If NPC dialogue appears → M1 demo target 3 confirmed met. If silent → file an issue. - [ ] **Step 4: Grep the log for evidence.** ```powershell Select-String -Path launch-b5.log -Pattern "\[B\.5\] pickup|\[B\.4b\] pick|UseDone|InventoryPutObjInContainer|RemoveObject" ``` Expected: at least one `[B.5] pickup` line and a subsequent `RemoveObject` for the same guid. --- ## Task 4: Ship handoff + docs + merge - [ ] **Step 1: Write the ship handoff doc** at `docs/research/2026-05-14-b5-shipped-handoff.md`. Follow the B.4c handoff structure: TL;DR, three-commit table (TDD builder + GameWindow integration + handoff itself), wire-format evidence, visual-verification evidence (with launch log excerpt), open issues carried forward (#61 #62 from B.4c), what shipped, what was left for later. - [ ] **Step 2: Update `docs/plans/2026-04-11-roadmap.md`** — move Phase B.5 from "Next phase candidates" into the shipped-table with the merge SHA placeholder + link to the handoff doc. - [ ] **Step 3: Update `CLAUDE.md`** — update the "Currently in Phase L.2" paragraph's M1 demo status from "3 of 4 met" to "4 of 4 met", reference the B.5 handoff, and add a fresh "Next phase candidates" list (chronic-issue triage, Phase C visual fidelity, N.6 slice 2, etc.). - [ ] **Step 4: Update `docs/ISSUES.md`** — if any new issues surfaced during visual verification, file them. If the click-NPC bonus check succeeded, note it in the recent-progress section. - [ ] **Step 5: Commit docs.** ```powershell git add docs/research/2026-05-14-b5-shipped-handoff.md ` docs/plans/2026-04-11-roadmap.md ` CLAUDE.md ` docs/ISSUES.md git commit -m "docs(B.5): ship handoff + roadmap/CLAUDE update + M1 4/4 met" ``` - [ ] **Step 6: Merge to main.** ```powershell git checkout main git merge --no-ff claude/phase-b5-pickup -m "Merge branch 'claude/phase-b5-pickup' — Phase B.5 pickup" ``` - [ ] **Step 7: Optional worktree cleanup.** (Per B.4c precedent, submodules block `git worktree remove`; do `git worktree prune` after manually deleting the directory if disk pressure warrants. Otherwise skip — the directory is small.) --- ## Acceptance criteria summary - [ ] `dotnet build -c Debug` green. - [ ] `dotnet test -c Debug` shows +1 new passing (the `BuildPickUp_WritesOpcode0x0019AndPayload` test). - [ ] Total pass count = baseline + 1; failure count unchanged (8 pre-existing). - [ ] Visual: click ground item → F → log shows `[B.5] pickup ...` → item disappears. - [ ] No regression on B.4c door interaction (double-click inn door still swings). - [ ] Bonus: click NPC → chat appears in chat panel (or filed as a follow-up issue). - [ ] Branch merged into main with non-fast-forward merge commit. --- ## Carry-overs from B.4c (do not lose track) - **#61** — AnimationSequencer link→cycle frame-0 flash. Low severity. Not blocking M1 demo. - **#62** — PARTSDIAG null-guard. Latent (not reachable for doors currently). One-line fix. Neither blocks B.5. Address before recording the M1 demo video if the door-swing flap is distracting on tape.