feat(lod114d): PlugY multi-page stash through the StashTab contract by ResurrectedTrader · Pull Request #19 · ResurrectedTrader/d2bsng

ResurrectedTrader · 2026-09-13T11:12:57Z

Builds on #18: the 1.14d backend now implements the StashTab contract over PlugY's multi-page stash when PlugY is present, and keeps the vanilla single-tab path otherwise. No contract, JS or character-state changes; scripts get more tabs from the same API.

What PlugY does

Only the shown page's items live in the player's inventory. The others are parked on PlugY's page lists (a PYPlayerData tail appended to D2PlayerDataStrc, two doubly linked Stash lists), removed from the inventory with the game's own routine, so they read as stored-mode items with no parent inventory and a zeroed node byte. Page switches are server round trips over PlugY's overloaded C->S 0x3A packet; the server pushes the result with its custom S->C 0x9D. docs/plugy_stash.md has the full write-up.

Backend (`src/backends/lod114d`)

game/PlugY.h / game/PlugY.cpp (new) and imports/extras/PlugY.h (new, static_asserted struct mirrors): everything PlugY-specific, in its own files so it can be removed wholesale (recipe in the doc).
Detection: GetModuleHandle("PlugY.dll") -> VERSIONINFO allowlist (12.00, 14.00, 14.01, 14.02, 14.03; the 1.14d-capable releases, verified identical for every struct / patch site / command this code reads) -> the InitPlayerData alloc call must target PlugY.dll's image (ActiveMultiPageStash=1) -> the alloc size immediate must equal sizeof(D2PlayerDataStrc). A missing module or a not-yet-applied patch is retried until a player unit exists, then cached as a final negative, so a vanilla install pays one atomic load per stash query. Adds the plugy feature tag for analytics.
Init without PlugY.exe: plugy::InstallInitHook() from Bridge::Init redirects Game.exe's startup call [LoadLibraryA] (RVA 0x621C) to run PlugY's exported Init once Fog's pool exists, the same point PlugY.exe patches. No-op without the module or when PlugY.exe already patched the site.
game/Stash.cpp: delegates to plugy:: while plugy::IsActive() && plugy::HasStashTabs() holds. Tabs enumerate both page lists; Name is the page name; GetItems walks the parked list or the inventory for the shown page; shared tab 0 reports PlugY's shared gold pool and its DepositGold / WithdrawGold send the put/take commands (all-or-nothing, amount ignored, fire and forget).
Clicking a page that is not shown: plugy::WithActivePage runs on the script thread: release read locks, take the operation mutex, plan and send the relative page moves, poll the mirror until the target is shown, click, wait for the server's item-action ack keyed on the cursor item id change (a page revert sent before the ack desyncs client and server), send the reverse plan, wait again. ClickItem hands parked items to plugy::ClickParkedItem.
Unit::ItemLocation() reports a parked item as Stash.
hooks/Intercepts: a single-slot atomic IncomingPacketObserver called at the top of the incoming-packet intercept, used for the ack wait.
PlugY's 1.14d patch sites were compared against d2bs's hook sites once (101 vs 28 sites, zero overlaps against 14.03); the result and the nearest miss are recorded in the doc.

Docs

docs/plugy_stash.md (new) covers the PlugY mechanics, detection, init path, overlap check, click sequence, gold and the removal recipe; docs/stash_tabs.md and CLAUDE.md point at it.

Verification

This code was built, linted, tested and exercised in-game against PlugY 14.03 (single player) before being split from #18: page enumeration, names, parked-item reads, unit.stashTab, clicking items into and out of inactive pages with the ack wait, shared gold moves. On this branch: clang-format clean, clang-tidy 112/112 passed. Not re-run in-game after the rebase onto the merged contract.

🤖 Generated with Claude Code

…ontract When a supported PlugY build (12.00, 14.00-14.03) has its multi-page stash installed, game/Stash.cpp delegates every StashTab member to game/PlugY.cpp: tabs enumerate PlugY's personal and shared page lists, GetItems reads items parked on pages that are not shown, Name is the user-given page name, shared tab 0 carries PlugY's shared gold pool, and Click / ClickItem swap the target page in over PlugY's 0x3A command channel, click, wait for the server's item action acknowledgement, and swap back before returning. Without PlugY the vanilla single-tab path is unchanged. Detection is module handle -> version allowlist -> the InitPlayerData alloc call redirected into PlugY.dll -> alloc size == sizeof(D2PlayerDataStrc), so the PYPlayerData tail is only ever read when PlugY actually appended it. Bridge::Init installs a hook on Game.exe's startup LoadLibraryA call that runs PlugY's exported Init when PlugY.dll was injected without PlugY.exe. Unit::ItemLocation reports a parked item (stored mode, no parent inventory) as Stash. Intercepts gains a single-slot incoming-packet observer for the ack wait. scripts/plugy_overlap_audit.py checks PlugY's 1.14d patch sites against d2bs's hook sites (zero overlaps against 14.03). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

The comparison it ran is recorded in docs/plugy_stash.md; the script was a one-off. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…asStashTabs, page walks as struct members IsActive() now caches a missing PlugY.dll as a final negative once a player unit exists (PlugY loads and runs Init at Game.exe startup, long before that), so a vanilla install pays one atomic load per stash query instead of a mutex and a loader lookup on every call. HasPages() becomes HasStashTabs() and no longer hides the IsActive() check; Stash.cpp spells out plugy::IsActive() && plugy::HasStashTabs() at each delegation, and IsParkedItem, the one entry reached from the generic item paths, checks both itself. The page-list walks (Head / ForEachPage / FindPage / PageCount / ActivePage / IsActivePage) and the page name conversion move onto the PYPlayerData / Stash mirrors in imports/extras/PlugY.h; they add no data, and the size static_asserts still hold. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

ResurrectedTrader · 2026-09-13T11:24:12Z

+}
+
+// Page names are typed into PlugY's in-game text box and stored in the ANSI code page.
+std::string PageName(const Stash& page) {


Could these just be member methods on the struct, or does that change the struct size?