Reverse Engineering Mario Party to Randomize Its Boards

How I reverse-engineered Mario Party Superstars' proprietary BEA archive and AES-encrypted board format to build a deterministic board randomizer — shipped both as a Python CLI and as C++ Switch homebrew that runs on real hardware.

13 min read · reverse-engineering · nintendo-switch · homebrew · python · cpp

In short: Mario Party Superstars keeps its board layout in an undocumented archive, behind zstd compression and AES encryption with non-standard padding. I unpacked that format, found why the game white-screened on my first rebuilt archive, and shipped a seeded randomizer as a Python CLI and as C++ Switch homebrew. For what I built and the key decisions, see the case study; this article is the full investigation.

I built a randomizer for Mario Party Superstars that reshuffles a board's space layout into something fresh every session — and the part I'm proudest of is that it runs directly on a real Nintendo Switch. You pick a preset on the console, press A, exit the homebrew app, and launch the game to a board you've never played before. No PC in the loop.

It ships in two forms that share one algorithmic core:

  • A Python CLI that runs on a PC and produces a RomFS mod folder you drop into an emulator like Eden or Yuzu.
  • A C++ Switch homebrew .nro that runs from the Homebrew Menu and writes the mod straight to the SD card.

Both produce a byte-identical board for the same preset and seed. That means seeds are shareable: tell a friend your preset and an 8-character hex seed, and they generate the exact same custom board on their own hardware. You can play the same randomized layout remotely.

The tool ships no game data. You supply your own legally-dumped archive from your own console. Everything below is about the format work and the engineering, not the data.

The fun was never "shuffle an array." The fun was that the board layout lives inside a proprietary, undocumented archive, behind a compression layer, behind AES encryption with a non-standard padding scheme — and that getting the result to actually load on hardware took a debugging session with exactly one bit of feedback.

What a Mario Party board actually is

If you don't play Mario Party, here's the one thing you need to know: every board is a graph of spaces, and each space has a type that decides what happens when you land on it. The classic ones:

  • Blue — gain coins.
  • Red — lose coins.
  • Item — get an item.
  • Lucky — a bonus event.
  • Bowser — something bad, usually expensive.
  • Plus VS, Chance Time, and a handful of special markers (Start, the star location, shops, and so on).

The catch is that every board has a fixed layout. Yoshi's Tropical Island is the same every single time you play it. After a few games you've memorized where the risky spaces are and where the safe routes go, and the discovery is gone.

The randomizer reshuffles those space types so the board feels new again, and it does it with presets that tune the overall feel rather than just flipping spaces at random:

PresetFeel
BalancedClose to a normal board.
ChaoticFar more VS, Chance Time, and Bowser — high-variance swings.
EvilFloods the board with Red and Bowser. Coins drain fast; nobody is safe.
CompetitiveHeavily Blue, almost no luck spaces — rewards consistent play.

A preset is a set of target proportions that sum to 100. The tool doesn't just randomly nudge some spaces toward Blue; it allocates a specific count of each type and then shuffles their positions. More on that math later, because getting "weights that sum to 100" to become "exact integer counts that sum to the number of spaces on the board" is its own small problem.

The format, one layer at a time

The board layout doesn't live in a tidy JSON file. Getting to it means peeling back four layers.

The board data lives in Archive/hsbd04.nx.bea inside the game's RomFS. That .bea file is a SCNE/BEA archive — Nintendo's proprietary container format that packs many assets into a single binary, each asset zstd-compressed. Inside it, exactly one asset holds the board's space layout:

scene/hsbd04/data/hsbd04_map.nkn

That .nkn asset is the only thing the randomizer ever touches. The full path from file on disk to data I can edit looks like this:

hsbd04.nx.bea            (SCNE/BEA container)
  └─ hsbd04_map.nkn      (one asset inside it)
       ├─ zstd-compressed
       ├─ AES-128-CBC encrypted
       └─ CSV-like text   <- the actual board, finally

So: parse the archive, find the asset, zstd-decompress it, AES-decrypt the result, and only then do you get a plaintext table you can reason about. Each of those layers had a surprise in it.

Only column 5

Once decrypted, the map is a CSV-like table with CRLF line endings, one row per board space. The columns:

ColumnContents
0Space ID (integer)
1–4Next-space IDs — the board's graph edges
5Type (PLUS, MINUS, EVENT, ITEM, VS, CHANCE, KOOPA, HATENA_1, START, …)
6+Params and labels

The randomizer only ever touches column 5. IDs, topology, params, labels — all preserved exactly. The board you get is the same board, walked the same way; only what each space does changes.

Not every row is fair game, either. A row is mutable only when all of these hold:

  • It has at least 6 fields.
  • Column 0 parses as an integer below 500.
  • Column 5 is one of the allowed types: PLUS, MINUS, EVENT, ITEM, VS, CHANCE, KOOPA, HATENA_1.

Everything else is protected and never touched: START, the star marker (MARK_STAR), the player marker (MARK_PC), BANK, the shop/Boo/Bowser spots (SPOT_*), any ID at or above 500, blank lines, and malformed rows. Get this classification wrong and you either corrupt the board or randomize a space that breaks the game's own logic — so the allow-list is deliberately conservative.

Turning weights into a board

Here's that small math problem from earlier. A preset gives me weights summing to 100. The board has some number N of mutable rows. I need exact integer counts, one per type, that sum to exactly N and match the target proportions as closely as possible.

Naive rounding doesn't work — round each weight * N / 100 independently and your counts can sum to N - 1 or N + 2. So the tool uses the largest-remainder method (the Hamilton method from electoral apportionment): compute each type's real quota, floor them all, then hand the leftover slots to the types with the largest fractional remainders, with stable tie-breaking so it's deterministic. The total always lands on N exactly.

Then the shuffle. The RNG is seeded from a SHA-256 hash of a board|preset|seed string — for example yoshi|balanced|MEESZ123. The first 8 bytes of the digest become a big-endian integer that seeds Python's random.Random (a Mersenne Twister). The assignment list — say 45 PLUS, 15 MINUS, and so on — is built from the apportioned counts and shuffled with Fisher-Yates using that seeded RNG. A final guard makes sure at least one PLUS and one MINUS always survive, which matters for the more extreme presets.

That's the whole determinism story: same board, same preset, same seed produces the same shuffle on any machine, every time. It's also exactly why the two implementations can claim byte-identical output — and why that claim was hard.

The white screen

This was the most significant engineering challenge of the project, and the best story in it.

Early builds white-screened the game whenever I loaded Yoshi's Tropical Island. A white screen is the worst kind of bug feedback: it tells you something is wrong and absolutely nothing about what. I had no source access to the game's board loader, so I couldn't step through it. I had exactly one bit of information per attempt — does the board load, yes or no.

Three things could plausibly cause it: a wrong game version, wrong board content, or wrong archive packing. With one bit of feedback, the only sane approach is to build minimal, controlled test files that each change a single variable, then run them on the actual hardware one at a time and bisect.

So I crafted five test .bea files and loaded each through Atmosphère's LayeredFS:

TestWhat it wasResultWhat it proves
AVanilla, completely unmodified archiveLoadsLayeredFS path, title ID, and setup are correct
BVanilla content, repacked with "append at EOF + repoint"White screenContent is innocent; packing is the variable that changed
CModified content, same bad packingWhite screenConsistent with the packing hypothesis
DVanilla content, new in-place overwrite packingLoadsThe in-place fix works
EReal balanced preset, in-place packingLoads, board visibly reshuffledFix confirmed end to end

Test B is the one that cracked it. The content was byte-for-byte vanilla, yet it white-screened — so the content couldn't be the problem. The only thing that had changed was how the tool repacked the archive.

Root cause: the game's board loader apparently validates that each asset still sits at its original file_offset in the archive. My first packing method appended the new payload at the end of the file and repointed the asset's record to the new location. Structurally that's a perfectly valid archive — the record correctly described where the data now lived — but the loader rejected it anyway, because the offset no longer matched what it expected.

The fix is to write the new payload at the asset's original file_offset, overwriting it in place, then zero the leftover bytes from the end of the new payload to the start of the next asset. Only the asset record's compressed and decompressed sizes get updated; the file_offset field is left untouched, and the total file size stays byte-identical to the original.

This only works because the type column is the only thing that changes, so the map's text length is essentially fixed per preset and the recompressed payload always fits the original 2,160-byte slot. That's not a happy accident I get to rely on blindly — replace_asset_inplace enforces it with an explicit overflow check, and the Switch build repeats the check after writing. The in-place constraint stopped being a workaround and became the invariant the whole tool is designed around.

Two languages, one shuffle

The Python CLI came first. The Switch homebrew is C++, because that's what runs on the console. But the headline feature — shareable seeds — only works if both implementations produce the exact same shuffle for the same preset and seed. Not "similar." Byte-identical.

That sounds easy until you realize it means the C++ side has to reproduce Python's random.Random precisely. Not "also a Mersenne Twister" — the actual CPython implementation, including the parts nobody thinks about.

The subtle bit is seeding. CPython's random.Random doesn't just take an integer and feed it to the generator. It converts the integer into an array of 32-bit words (little-endian, as many words as the value needs) and runs it through init_by_array. My 8-byte SHA-256-derived seed becomes either a one- or two-word array depending on its magnitude, and the generator's entire state depends on getting that conversion bit-for-bit right.

So the C++ port (pyrandom.cpp) reimplements CPython's path exactly:

init_genrand        single-seed initialization
init_by_array       multi-word seed, matching CPython's loop structure
seed_u64            uint64 -> key array, matching CPython's bit-length logic
genrand_uint32      the Mersenne Twister state transition
getrandbits(k)      top k bits of a 32-bit draw
randbelow(n)        rejection sampling
shuffle             Fisher-Yates on top of randbelow

To keep myself honest, there's a parity test suite. It compiles a standalone C++ tool that runs the full randomizer pipeline and emits a CSV, then diffs that against Python's output for all four presets across multiple seeds. They match byte-for-byte. That diff is the contract; if a future change to either side breaks parity, the test catches it before a single seed stops being shareable.

The archive had no spec, and the padding lied

Two layers below the shuffle were the ones with no documentation at all.

The SCNE/BEA format has no public specification. I pieced it together by staring at the raw binary in a hex editor, cross-referencing Switch Toolbox's open-source parser, and writing small extraction tools to validate my understanding. The tricky part is the asset record (ASST): it mixes 32- and 64-bit fields, has reserved alignment bytes, and stores filenames at offsets pointed to from inside the record. The header has a similar mix of widths plus a table of 8-byte pointers to those records. Get any field width wrong and you don't get an error — you silently parse garbage, and the only signal is that extraction produces the wrong bytes. The validation loop was: extract an asset, re-serialize it, and check the output is byte-identical to the original.

Then there was the encryption. After zstd-decompressing the .nkn asset you don't get the CSV — you get an AES-128-CBC encrypted blob. Finding the key and IV (by examining known-good decryptions) was step one. The real trap was the padding. Most AES-CBC code uses PKCS#7. This file doesn't. Its scheme is:

<UTF-8 CSV text> + 0x00 (NUL terminator) + 0x0A bytes to pad to a 16-byte block

If you re-encrypt with the wrong padding, the ciphertext differs and the game rejects the file. I confirmed the real scheme with a round-trip test: decrypt, then re-encrypt, then compare against the original ciphertext byte-for-byte. Once those matched bit-for-bit, I knew I had the right key, IV, and padding — all three at once, which is the only way to be sure with a black-box format.

Writing safely to a console

Writing to the SD card on a live game console deserves care. A crash or power loss mid-write could leave a half-written archive that won't load. So the Switch build never writes the active file directly. The flow is:

  1. Generate the new archive bytes in memory.
  2. Write them to hsbd04.nx.bea.tmp.
  3. Re-open the temp file and verify it: parse the asset records, decrypt the map, parse the CSV, and confirm at least one PLUS and one MINUS survived.
  4. Only if verification passes: back up the current mod, then rename the temp file into place.
  5. Write the seed, report, and CSV to an output folder.
  6. On any failure: show a clear on-screen error and leave no partial active file.

The tool also stays strictly inside its own directory — it never touches cheat files, other title IDs, or anything outside its own footprint.

On the PC side the output is friendlier to inspect: a folder with the modded romfs/Archive/hsbd04.nx.bea, a randomizer-report.txt (seed, preset, before/ after type counts, and every changed space ID), and the decrypted randomized-map.csv so you can see exactly what changed.

What it doesn't do

Being honest about scope is part of the engineering, so:

  • One board, for now. The Python CLI handles Yoshi's Tropical Island. Other boards use different archive names and would need their maps profiled first.
  • Only the space type changes. The board graph, star locations, item/shop/ Boo/Bowser placements, and all game logic are untouched.
  • The dump must match the installed game version. A dump from a different version can fail to load (white screen — the same loader strictness from earlier). Re-dump after a game update.
  • The slot size is fixed per version. Any new mutable type or preset weight change has to re-verify that the output still fits the 2,160-byte slot.

None of these are bugs; they're the edges of what's currently safe to touch.

This was an enormously fun project — a fixed game board became a format puzzle, a hardware-debugging mystery, and a cross-language determinism contract, and at the end of it a real Switch boots a board I shuffled. I hope you enjoyed the write-up.

The case study sums up the decisions and trade-offs behind the tool.