| name | smbw-save-data |
| description | Grant items and read/write SMBW save data via the GameDataMgr (gmd::) runtime API. Use when wiring a new AP item to an in-game grant, picking which probe:: primitive an item needs (counter / bool / badge bitfield / per-course / wonder seed), working with hash keys, the container A/B/C/D layout, the save-file byte format, or the save-survival/replay strategy. Bundles the save-file format reference and the save-OUT-vs-live-state warning. Triggers: "grant an item", "GameDataMgr", "hash key", "container A/B/C", "badge bitfield", "royal seed", "wonder seed count", "save file offset", "why doesn't the grant survive reload". |
SMBW save data & item grants (GameDataMgr)
The live-grant path is the GameDataMgr runtime API — the only mechanism
that changes actual gameplay state. To find/RE these functions, see the
smbw-reverse-engineering skill. The full decompile journal is at
../smbw-reverse-engineering/reference/static-analysis-findings.md.
To resolve a flag's hash + category (which decides the writer — see the footgun
below) offline from the RomFS, see smbw-romfs-datamining.
📋 For the consolidated current-state tables (hash keys, container API
offsets, struct layout, save offsets, badge map — all present-tense with status
flags), see
../smbw-reverse-engineering/reference/smbw-re-map.md.
The tables below are the grant-focused subset; the map is the superset.
⚠️ The single biggest trap: the save-OUT staging buffer is NOT a live-grant
path. Writers anchored on file offsets (the savedata_id UUID scan, badge
offset 0x0EA0, etc.) modify only the transient save-serialization buffer; the
game repopulates it FROM live state on every save and discards your writes.
That work produced a save-file editor + a verification target (predict
the bytes a real grant will write), not a grant. Background:
reference/runtime-address-backtrace-plan.md,
reference/save-diff-grants.md.
The singleton anchor
gmd::GameDataMgr::sInstance @ NSO +0x0363F0F0. Deref this qword at runtime
→ the live GameDataMgr*. The Switch side wraps this as probe::gmdSingleton().
This replaces every Cheat-Engine pointer-scan workflow.
Containers & their writers
| Container | Holds | Live writer (NSO) | Switch primitive (probe::, file) |
|---|
| A | hash-keyed u32/u16/u8 counters (coins, wonder-seed counts + mirrors) | +0x0049F648 (gmd, value, hash) | grantContainerACounter(hash,value), incrementContainerACounter(hash,delta) — ContainerA.cpp |
| B | hash-keyed bools (Royal Seeds, COMPLETE_GAME, INTRO) | +0x0049EA24 wrapper → +0x1F263FC delegate on gmd+8 substruct | grantContainerBBool(hash,value) — ContainerB.cpp |
| C | bitfields at gmd+0x70..0x8c (badges; wonder-seed bitfield) | walk bucket → typed sub-obj → uint32_t[] | setBadgeBitfieldAbsolute(bits), setContainerCBit(hash,bit,val), setWonderSeedBitfieldAbsolute(lo,hi) — ContainerC.cpp |
| D | per-course / per-seed arrays (wonder-seed persistence) | ⏳ active RE | setPerCourseBitfieldAbsolute(...), pushWonderSeedContainerDCounts() — PerCourse.cpp, SeedTrace.cpp |
Other GameDataMgr accessors: +0x0012AE94 container-A reader
(gmd, u32* out, hash); +0x03838AC sub-bool reader; +0x03D3FB0
stage-info hash → course-index translator (NOT a writer — old CLAUDE.md
guess was wrong); +0x03D4110 Murmur3-32 course-name lookup.
Grant primitives live in switch-mod/src/probe/*.cpp; hooks that drive them are
installed in switch-mod/src/main.cpp. (CLAUDE.md's old src/program/main.cpp
paths are the retired exlaunch tree.)
⚠️ Bool-vs-Int writer footgun — match the writer to the flag's category
The writer you pick must match the flag's GameDataList category, or the grant
silently fails or crashes:
| Flag category | Correct writer | Wrong writer → |
|---|
| Bool | grantContainerBBool(hash, 1) | grantContainerACounter → silent no-op (write goes nowhere) |
| Int / counter | grantContainerACounter(hash, n) | grantContainerBBool → null-deref crash |
This sank an entire 86-hash world-unlock table: it was dispatched single-list
through grantContainerACounter, but 84 of the 86 hashes are Bool-category, so
the channel never landed except for the 2 Int entries. (The historical "the Bool
writer crashed the drain worker on first boot" note was the inverse — the 1–2
Int-category hashes null-derefing the Bool setter, not a timing bug.) Fix: split the
table by category and route each side to its writer.
How to know a flag's category without guessing: read it from the RomFS
GameDataList.Product.100 schema — the smbw-romfs-datamining skill resolves any
flag name → hash → category → SaveFileIndex offline (scripts/romfs/hash_lookup.py).
Always check the category before wiring a new hash to a writer.
Verified hash keys
| Hash | Field | Container | Width |
|---|
0xf4ee6827 | flower_coin (purple coins) | A | u16 |
0x17f0bb21 | regular_coin | A | u8 |
0x55815859 | Royal Seed W1 (GRAND_SEED_WORLD1) | B | bool |
0x49abba86 | Royal Seed W2 | B | bool |
0xb550d8d6 | Royal Seed W3 | B | bool |
0x1dcf7f6e | Royal Seed W4 | B | bool |
0x0d5a3e00 | Royal Seed W5 | B | bool |
0xd4660d2b | Royal Seed W6 | B | bool |
0x5d3ec9b4 | COMPLETE_GAME | B | bool |
0x89f1cc52 | INTRO_CUTSCENE_COMPLETED | B | bool |
0x105df820 | badge owned bitfield (bit == internal_id) | C | u64 |
0xdf82e9ab | "current course" / is-clear lookup key | — | — |
0x390eb960 (+ 0x21f89ab1,0x8c20ccb7,0xeeff353b,0xa0e5f253) | per-current-world Wonder Seed count (gate predicate +0x1787b40 reads 0x390eb960) | A | u32 |
The bridge maps AP item names → hashes in
apworld/smbw_archipelago/client/{royal_seed_table,badge_table,wonder_seed_table,coin_table}.py.
Cross-verified against MemetendoYT's save editor + the HamletDuFromage cheat DB.
World-map / open-world Bowser-approach hashes (all Bool → grantContainerBBool):
six cloud-piranha WorldMapCloudPackunVanishInfo.IsVanish*
(0xc687fb5f 0xcff5f3d2 0x048bc39c 0x1677f038 0x95539ec5 0x7f6e8a47) + castle fly-in
WorldMapKoopaCastleEntranceDemoInfo.IsAppear 0xc06bd61e; plus the container-C
reveal node/road bits. Full table + derivation in the RE map §11 and the
smbw-romfs-datamining schema reference.
Badges (Container C)
Owned bitfield: hash 0x105df820, bit position == internal_id == badge ID
(bit 4 = Spring Feet). setBadgeBitfieldAbsolute(bits) overwrites the whole
bitfield (appears live, no save/reload). Gotchas: hash 0x6d1b5c25 is the
auxiliary UI-slot bitmap (file offset 0x1204), not ownership; the serializer
strips bit positions that aren't real badges — only use valid internal_ids.
Deferred-write & save-survival
Both container-A (+0x49F648) and container-B (+0x49EA24) queue to a dirty
buffer at gmd->[+0xf8] and apply at next save. A load-before-flush silently
drops the grant. The fix is AP-authoritative replay — the bridge re-pushes
the canonical set on triggers so any drop/in-game-pickup is reverted:
- Badges —
SetBadgesAbsoluteMsg absolute overwrite on every ReceivedItems,
every HelloMsg, and a ~2 s tick. Idempotent.
- Royal Seeds —
_collect_royal_seed_grants → re-emit one GrantHashKeyedMsg
per received seed on every HelloMsg.
- Wonder Seed counts —
SetWonderSeedCountsMsg{counts:[u32;8]} (AP buckets
W1..W6=0..5, Petal Isles=6, Special=7) overwritten on the same 3 triggers; the
Switch maps current-world index → bucket and writes the 5 mirror hashes via
pushWonderSeedOverride.
- Not replayed: container-A coins + the two completion bools (not AP items
today). Extend
_collect_royal_seed_grants into a generic
_collect_hash_keyed_grants when they become items.
⚠️ Gate-override only, not per-course persistence: pushWonderSeedOverride
makes the current world's gates pass from AP's count but does NOT write the
per-course Wonder Seed bitfield (Container D, file offset 0x3AF8 + 4*course_idx)
— that writer is the active RE in
docs/handoff-2026-05-29-ws-persistence.md
and docs/wonder-seed-re-reopen-2026-05-28.md.
The Royal-Seed check-loss / gate-entry follow-up is also active in
docs/royal-seed-gate-entry-design.md
and docs/gate-entry-session3-handoff.md.
Dual-write for instant UI refresh
A deferred write applies at next save; for the in-game counter to refresh
immediately, also write the live-state struct field directly (HamletDuFromage
cheat anchors give offsets: flower_coin live_base + 0xC8, lives +0x60).
Save-file format (verification + offline editing)
%APPDATA%\Ryujinx\bis\user\save\0000000000000002\<user>\game_data.sav —
~21,876 bytes, plaintext, magic 04 03 02 01, ~88% zero. First 0x400 after
the header is 128 × (u32 hash_key, u32 value) — the same container-A counter
table. Full byte map (header, tables, string blob, trailing per-course arrays:
CourseClear/GoalSeed/WonderSeed/PurpleCoin/ClapperGate stride 4, badges 0x0EA0,
lives 0x167C) is in reference/save-diff-findings.md.
Diff a save before/after an action with scripts/savediff.py:
python scripts/savediff.py game_data.sav.pre game_data.sav # classifies first-acquire / +1 / bit-flip / change
python scripts/savediff.py --summary game_data.sav # single-save inspection
This is how every grant primitive was validated (e.g. flower_coin 6 → 99 at
file offset 0x0894 after grantContainerACounter(0xf4ee6827, 99)).
