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
.nrothat 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:
| Preset | Feel |
|---|---|
| Balanced | Close to a normal board. |
| Chaotic | Far more VS, Chance Time, and Bowser — high-variance swings. |
| Evil | Floods the board with Red and Bowser. Coins drain fast; nobody is safe. |
| Competitive | Heavily 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:
| Column | Contents |
|---|---|
| 0 | Space ID (integer) |
| 1–4 | Next-space IDs — the board's graph edges |
| 5 | Type (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:
| Test | What it was | Result | What it proves |
|---|---|---|---|
| A | Vanilla, completely unmodified archive | Loads | LayeredFS path, title ID, and setup are correct |
| B | Vanilla content, repacked with "append at EOF + repoint" | White screen | Content is innocent; packing is the variable that changed |
| C | Modified content, same bad packing | White screen | Consistent with the packing hypothesis |
| D | Vanilla content, new in-place overwrite packing | Loads | The in-place fix works |
| E | Real balanced preset, in-place packing | Loads, board visibly reshuffled | Fix 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:
- Generate the new archive bytes in memory.
- Write them to
hsbd04.nx.bea.tmp. - Re-open the temp file and verify it: parse the asset records, decrypt the
map, parse the CSV, and confirm at least one
PLUSand oneMINUSsurvived. - Only if verification passes: back up the current mod, then rename the temp file into place.
- Write the seed, report, and CSV to an output folder.
- 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.