mahjong.shanten

class mahjong.shanten.Shanten

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.

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)

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 without a pair is tenpai (one tile needed for the pair):

>>> tiles_34 = [0] * 34
>>> tiles_34[0] = 3
>>> 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 the hand contains more than 14 tiles

Return type:

int

static calculate_shanten_for_chiitoitsu_hand(tiles_34)

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)

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)

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

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 without a pair is tenpai:

>>> tiles_34 = [0] * 34
>>> tiles_34[0] = 3
>>> 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 the hand contains more than 14 tiles

Return type:

int