mahjong.shanten

class mahjong.shanten.Shanten[source]

Shanten (minimum tiles to tenpai/agari) calculation.

The shanten number represents how many tiles away a hand is from being complete (agari). A shanten number of 0 means the hand is tenpai (one tile away from winning), and -1 means the hand is already complete.

Accepts tile counts that correspond to valid game states: 1, 2, 4, 5, 7, 8, 10, 11, 13, or 14. Tile counts divisible by 3 (0, 3, 6, 9, 12) are rejected because they never occur in real riichi mahjong gameplay (a hand is always 3n+1 or 3n+2 tiles).

Supports three hand types: regular (4 melds + 1 pair), chiitoitsu (seven pairs), and kokushi musou (thirteen orphans).

TENPAI_STATE = 0: Hand is tenpai — one tile away from winning.

AGARI_STATE = -1: Hand is complete (agari).

static calculate_shanten(tiles_34, use_chiitoitsu=True, use_kokushi=True)[source]

Return the minimum shanten number across regular, chiitoitsu, and kokushi hand types.

A pair alone is a complete hand (remaining melds are implied open):

>>> tiles_34 = [0] * 34
>>> tiles_34[0] = 2
>>> Shanten.calculate_shanten(tiles_34)
-1

A triplet with an isolated tile is tenpai (one tile needed for the pair):

>>> tiles_34 = [0] * 34
>>> tiles_34[0] = 3
>>> tiles_34[9] = 1
>>> Shanten.calculate_shanten(tiles_34)
0

Parameters:

tiles_34 (Sequence[int]) – hand in 34-format count array (length 34)
use_chiitoitsu (bool) – include seven pairs pattern in calculation
use_kokushi (bool) – include thirteen orphans pattern in calculation

Returns:

minimum shanten number (-1 for agari, 0 for tenpai, positive for tiles needed)

Raises:

ValueError – if tile count exceeds 14 or is divisible by 3

Return type:

int

static calculate_shanten_for_chiitoitsu_hand(tiles_34)[source]

Calculate the shanten number for a chiitoitsu (seven pairs) hand.

Count the number of pairs and unique tile kinds to determine how far the hand is from completing seven distinct pairs.

Seven distinct pairs form a complete hand:

>>> tiles_34 = [2, 2, 2, 2, 2, 2, 2] + [0] * 27
>>> Shanten.calculate_shanten_for_chiitoitsu_hand(tiles_34)
-1

Six pairs with two singles — tenpai:

>>> tiles_34 = [2, 2, 2, 2, 2, 2, 1, 1] + [0] * 26
>>> Shanten.calculate_shanten_for_chiitoitsu_hand(tiles_34)
0

Parameters:: tiles_34 (Sequence[int]) – hand in 34-format count array (length 34)
Returns:: shanten number for chiitoitsu (-1 for complete, 0-6 otherwise)
Return type:: int

static calculate_shanten_for_kokushi_hand(tiles_34)[source]

Calculate the shanten number for a kokushi musou (thirteen orphans) hand.

Kokushi requires one of each terminal (1, 9 of each suit) and each honor tile, plus one duplicate. Count how many of the 13 required tiles are present and whether any appears twice.

All 13 terminal/honor tiles with one duplicate form a complete hand:

>>> tiles_34 = [0] * 34
>>> for i in [0, 8, 9, 17, 18, 26, 27, 28, 29, 30, 31, 32, 33]:
...    tiles_34[i] = 1
>>> tiles_34[33] = 2
>>> Shanten.calculate_shanten_for_kokushi_hand(tiles_34)
-1

Parameters:: tiles_34 (Sequence[int]) – hand in 34-format count array (length 34)
Returns:: shanten number for kokushi (-1 for complete, 0-13 otherwise)
Return type:: int

static calculate_shanten_for_regular_hand(tiles_34)[source]

Calculate the shanten number for a regular hand (4 melds + 1 pair).

The number of melds to be calculated is determined based on the number of tiles in the hand. The number of melds is determined as number_of_tiles // 3 (e.g., 0 for 1-2 tiles, 1 for 4-5 tiles, …, 4 for 13-14 tiles). If there are fewer than 4 melds, the remaining melds are treated as open melds.

Use a depth-first search over all possible meld/pair/tatsu decompositions of the suited tiles (indices 0-26), after pre-processing honor tiles (indices 27-33).

A pair alone is a complete hand (remaining melds are implied open):

>>> tiles_34 = [0] * 34
>>> tiles_34[0] = 2
>>> Shanten.calculate_shanten_for_regular_hand(tiles_34)
-1

A triplet with an isolated tile is tenpai:

>>> tiles_34 = [0] * 34
>>> tiles_34[0] = 3
>>> tiles_34[9] = 1
>>> Shanten.calculate_shanten_for_regular_hand(tiles_34)
0

Parameters:: tiles_34 (Sequence[int]) – hand in 34-format count array (length 34)
Returns:: shanten number for regular hand (-1 for complete, 0+ otherwise)
Raises:: ValueError – if tile count exceeds 14 or is divisible by 3
Return type:: int