Crate tenhou_shuffle 

Tenhou Deck/Wall-Shuffling Algorithm

Tenhou is an online Japanese Riichi Mahjong game. As of 2022-10-02, Tenhou has published their algorithm for shuffling the deck / wall of tiles, alongside with validation data for a particular game seed, including intermediate results.

This crate re-implements the published algorithm for reconstructing the full shuffled wall of any game from its RNG seed.

This crate is no_std.

MT19937 RNG

This crate bundles an implementation of MT19937, copy-pasted from https://crates.io/crates/mt19937. This is mostly for no_std compatibility.

• Seed: [u32; 624].
• Raw output type: u32.

The Algorithm

Assuming u32 is little-endian (LSByte first) in byte buffers.

Each game begins by seeding an MT19937 RNG for the game. This seed can be retrieved as a base-64 encoding of the seed array.

Each round in the game requires a shuffle. We first derive the randomness as follows:

• Generate 9 chunks of 1024 bits ([u32; 288]) from the game-wide RNG. This array is named src in the original algorithm description. This is implemented as src_from_mt.

• For every 1024-bit chunk ([u32; 32], little-endian), calculate its SHA512 hash. All 9 chunks of 512 bits are concatenated into [u32; 144]. This array is named rnd in the original algorithm description. This is implemented as rnd_from_src.

Then, we shuffle the wall with rnd:

• Start with wall = sorted array of all tiles; length = 136 (4 players) or 108 (3 players).
• Perform a low-to-high Fisher-Yates Shuffle, using rnd[i] as the random number table, scaled to i..n as i + rnd[i] % (n - i). This is implemented as shuffle_with_rnd.
• The shuffled wall array should be dealt from the highest index to the lowest.

Modules

mt19937_nostd

NOTE: copied from the source of https://crates.io/crates/mt19937 for no_std support.

Constants

MT19937_SEED_SIZE

NUM_CHUNKS

RND_LEN

SRC_LEN

Functions

derive_new_mt

Seeds a new MT19937 RNG from the given one.

mt_from_seed

Seeds a new MT19937 RNG.

rnd_from_mt

Generates the rnd array from the given MT19937 RNG. See mod-level docs for definition of the arrays.

rnd_from_src

Generates the rnd array from the src array by chunk-wise hashing. See mod-level docs for definition of the arrays.

seed_from_base64

Decodes MT19937 seed from little-endian base-64-encoded string.

seed_from_mt

Generates seed for another MT19937 RNG from the given one.

shuffle_with_mt

Shuffles the given wall array using randomness from the given MT19937 RNG. See mod-level docs for the algorithm.

shuffle_with_rnd

Shuffles the given wall array using randomness from the rnd array. See mod-level docs for definition of the arrays and the specific shuffling algorithm.

src_from_mt

Generates the src array from the given MT19937 RNG. See mod-level docs for definition of the arrays.