mahjong 2.0.0.dev2__py3-none-any.whl → 2.2.0.dev1__py3-none-any.whl

mahjong/__init__.py

@@ -1,5 +1,27 @@
 """
-_summary_.
+Japanese riichi mahjong hand calculator library.
+
+Compute hand cost (han, fu, yaku, and scores), validate winning hands, and calculate shanten (minimum tiles to tenpai).
+
+.. rubric:: Main entry points
+
+* :class:`~mahjong.hand_calculating.hand.HandCalculator` — estimate hand value (han, fu, cost,
+  and yaku list) given tiles, win tile, melds, and dora indicators.
+* :class:`~mahjong.agari.Agari` — check whether tiles form a complete (winning) hand structure.
+* :class:`~mahjong.shanten.Shanten` — calculate how many tiles away a hand is from winning.
+
+.. rubric:: Tile and meld utilities
+
+* :class:`~mahjong.tile.TilesConverter` — convert between mpsz-notation strings, 34-format count
+  arrays, and 136-format tile index lists.
+* :class:`~mahjong.meld.Meld` — represent declared melds (chi, pon, kan).
+
+.. rubric:: Configuration and results
+
+* :class:`~mahjong.hand_calculating.hand_config.HandConfig` — configure win conditions (tsumo/ron),
+  wind context, and optional rule variants (open tanyao, aka dora, double yakuman, etc.).
+* :class:`~mahjong.hand_calculating.hand_response.HandResponse` — structured result containing
+  han, fu, fu details, cost breakdown, and yaku list.
 
 Tile representation
 ###################
@@ -30,11 +52,8 @@ Honors (`z`) use ranks to distinguish individual tiles:
 * `6` - Green dragon (發, hatsu)
 * `7` - Red dragon (中, chun)
 
-Multiple tiles may be concatenated without separators to form a string that represents a collection. For example:
-
-``123m406p789s11555z``
-
-is equivalent to ``1m2m3m4p0p6p7s8s9s1z1z5z5z5z``.
+Multiple tiles may be concatenated without separators to form a string that represents a collection
+(e.g., ``123m406p789s11555z`` is equivalent to ``1m2m3m4p0p6p7s8s9s1z1z5z5z5z``).
 
 34-format
 ---------

mahjong/hand_calculating/__init__.py

@@ -0,0 +1,23 @@
+"""
+Hand value calculation pipeline.
+
+This subpackage evaluates a winning hand and produces its han, fu, yaku list,
+and payment amounts. The calculation flows through several stages:
+
+1. :class:`~mahjong.hand_calculating.divider.HandDivider` decomposes the hand into all
+   valid block combinations (4 melds + 1 pair, or 7 pairs for chiitoitsu).
+2. :class:`~mahjong.hand_calculating.yaku.Yaku` subclasses test each decomposition for
+   matching yaku patterns (e.g., tanyao, pinfu, honitsu).
+3. :class:`~mahjong.hand_calculating.fu.FuCalculator` computes minipoints from the meld
+   structure, wait type, pair, and winning method.
+4. :class:`~mahjong.hand_calculating.scores.ScoresCalculator` converts han and fu into
+   payment amounts, accounting for honba and kyoutaku bonuses.
+
+:class:`~mahjong.hand_calculating.hand.HandCalculator` orchestrates the full pipeline and
+returns a :class:`~mahjong.hand_calculating.hand_response.HandResponse` with the
+highest-scoring result.
+
+Behavior is controlled by :class:`~mahjong.hand_calculating.hand_config.HandConfig`, which
+specifies win conditions (tsumo/ron), wind context, and optional rule variants such as
+open tanyao, aka dora, and double yakuman.
+"""

mahjong/hand_calculating/divider.py

@@ -2,6 +2,7 @@ from collections.abc import Collection, Sequence
 from dataclasses import dataclass
 from enum import IntEnum
 from functools import lru_cache
+from itertools import product
 from typing import Literal
 
 from mahjong.meld import Meld
@@ -21,7 +22,7 @@ class _Block:
 
     @classmethod
     def from_meld(cls, meld: Meld) -> "_Block":
-        tile_34 = meld.tiles_34[0]
+        tile_34 = meld._sorted_tiles_34[0]  # noqa: SLF001
         match meld.type:
             case Meld.CHI:
                 return cls(tile_34, _BlockType.SEQUENCE)
@@ -160,29 +161,27 @@ class HandDivider:
         man_combinations = HandDivider._decompose_single_color_hand(hand[0:9], 0)
         pin_combinations = HandDivider._decompose_single_color_hand(hand[9:18], 9)
         sou_combinations = HandDivider._decompose_single_color_hand(hand[18:27], 18)
-        honors = HandDivider._decompose_honors_hand(hand[27:34])
+        honors_combinations = HandDivider._decompose_honors_hand(hand[27:34])
 
         combinations: list[list[_Block]] = []
 
         if not melds and (chiitoitsu := HandDivider._decompose_chiitoitsu(hand)):
             combinations.append(chiitoitsu)
 
-        for man in man_combinations:
-            for pin in pin_combinations:
-                for sou in sou_combinations:
-                    # For invalid suits, *_combinations will be [] and the loop will not be executed.
-                    all_blocks = [*man, *pin, *sou, *honors]
+        # For invalid suits or honors, *_combinations will be [] and the loop will not be executed.
+        for man, pin, sou, honors in product(man_combinations, pin_combinations, sou_combinations, honors_combinations):
+            all_blocks = [*man, *pin, *sou, *honors]
 
-                    num_pair = sum(block.ty == _BlockType.PAIR for block in all_blocks)
-                    if num_pair != 1:
-                        continue
+            num_pair = sum(block.ty == _BlockType.PAIR for block in all_blocks)
+            if num_pair != 1:
+                continue
 
-                    all_blocks.extend(melds)
-                    if len(all_blocks) != 5:
-                        continue
+            all_blocks.extend(melds)
+            if len(all_blocks) != 5:
+                continue
 
-                    all_blocks.sort()
-                    combinations.append(all_blocks)
+            all_blocks.sort()
+            combinations.append(all_blocks)
 
         combinations.sort()
         return tuple(tuple(blocks) for blocks in combinations)
@@ -282,7 +281,9 @@ class HandDivider:
         return combinations
 
     @staticmethod
-    def _decompose_honors_hand(honors_hand: list[int]) -> list[_Block]:
+    def _decompose_honors_hand(honors_hand: list[int]) -> list[list[_Block]]:
+        # If there is no honor tile, returns [[]].
+        # If the honors cannot be decomposed, returns [].
         has_pair = False
         blocks: list[_Block] = []
         for i, count in enumerate(honors_hand):
@@ -299,4 +300,4 @@ class HandDivider:
                 case _:
                     return []
 
-        return blocks
+        return [blocks]

mahjong/hand_calculating/fu.py

@@ -169,7 +169,7 @@ class FuCalculator:
             as tile indices in 34-format
         :param config: hand configuration with win method and optional rule settings
         :param valued_tiles: tile indices in 34-format for tiles that grant pair fu
-            (dragons, player wind, round wind); pass the same index twice for double-valued
+            (dragons, seat wind, round wind); pass the same index twice for double-valued
         :param melds: declared melds (chi, pon, kan)
         :return: tuple of (fu component list, total fu rounded up to nearest 10)
         """

mahjong/hand_calculating/hand.py

@@ -1,7 +1,7 @@
 from collections.abc import Collection
 from typing import TypedDict
 
-from mahjong.constants import AKA_DORAS, CHUN, HAKU, HATSU
+from mahjong.constants import AKA_DORAS, CHUN, HAKU, HATSU, NORTH
 from mahjong.hand_calculating.divider import HandDivider
 from mahjong.hand_calculating.fu import FuCalculator, FuDetail
 from mahjong.hand_calculating.hand_config import HandConfig
@@ -22,36 +22,108 @@ class _CalculatedHand(TypedDict):
     fu_details: list[FuDetail]
 
 
+def _hand_priority(hand: _CalculatedHand) -> tuple[int, bool, int, int]:
+    """
+    Rank a hand decomposition, the most expensive one is used.
+
+    The highest score wins, and on an equal score a real yakuman wins over counted (kazoe)
+    yakuman built from regular yaku, as on Tenhou.
+    """
+    total = hand["cost"]["total"] if hand["cost"] else -1
+    has_yakuman = any(yaku.is_yakuman for yaku in hand["hand_yaku"])
+    return total, has_yakuman, hand["han"], hand["fu"]
+
+
 # suit bitmask: sou=1, pin=2, man=4
 _ALL_SUITS_MASK = 7
 
-_DEFAULT_CONFIG = HandConfig()
-
 
 class HandCalculator:
+    """
+    Hand value estimator.
+
+    Evaluate a winning hand's han, fu, yaku, and payment amounts. Accepts tiles in
+    136-format, an optional :class:`~mahjong.hand_calculating.hand_config.HandConfig` for
+    win conditions and rule variants, and optional melds and dora/ura-dora indicators. When multiple
+    valid decompositions exist, the highest-scoring result is returned.
+    """
+
+    # basic hand validation
     ERR_NO_WINNING_TILE = "winning_tile_not_in_hand"
+    """``win_tile`` index is not present in the ``tiles`` array."""
+    ERR_HAND_NOT_WINNING = "hand_not_winning"
+    """No valid decomposition exists; the hand is not a winning hand."""
+    ERR_NO_YAKU = "no_yaku"
+    """Hand can be decomposed but has zero han (no yaku applies)."""
+
+    # count validation
+    ERR_NEGATIVE_TSUMI_NUMBER = "negative_tsumi_number_not_allowed"
+    """``HandConfig.tsumi_number`` (honba counters) is negative."""
+    ERR_NEGATIVE_KYOUTAKU_NUMBER = "negative_kyoutaku_number_not_allowed"
+    """``HandConfig.kyoutaku_number`` (riichi deposits) is negative."""
+    ERR_NEGATIVE_PAARENCHAN = "negative_paarenchan_not_allowed"
+    """``HandConfig.paarenchan`` (consecutive dealer wins) is negative."""
+    ERR_NEGATIVE_NUKI_DORA = "negative_nuki_dora_not_allowed"
+    """``HandConfig.num_nuki_dora`` (extracted north winds) is negative."""
+
+    # meld validation
+    ERR_MELD_INVALID = "meld_invalid"
+    """A meld fails :meth:`Meld.is_valid`: its tiles don't match its type, its type is unknown,
+    or a meld other than a kan or a nuki is closed."""
+    ERR_NUKI_MELD_NOT_SUPPORTED = "nuki_meld_not_supported"
+    """A nuki meld was passed; pass nuki through ``HandConfig.num_nuki_dora`` instead."""
+    ERR_MELD_TILE_NOT_IN_HAND = "meld_tile_not_in_hand"
+    """A meld tile index is not present in the ``tiles`` array."""
+
+    # riichi constraints
     ERR_OPEN_HAND_RIICHI = "open_hand_riichi_not_allowed"
+    """Riichi declared on an open hand (open melds present)."""
     ERR_OPEN_HAND_DABURI = "open_hand_daburi_not_allowed"
+    """Double riichi declared on an open hand."""
     ERR_IPPATSU_WITHOUT_RIICHI = "ippatsu_without_riichi_not_allowed"
-    ERR_HAND_NOT_WINNING = "hand_not_winning"
-    ERR_NO_YAKU = "no_yaku"
+    """Ippatsu claimed without riichi or double riichi."""
+
+    # win-condition conflicts
     ERR_CHANKAN_WITH_TSUMO = "chankan_with_tsumo_not_allowed"
+    """Chankan (robbing a kan) requires a ron win."""
     ERR_RINSHAN_WITHOUT_TSUMO = "rinshan_without_tsumo_not_allowed"
+    """Rinshan kaihou (win after kan) requires a tsumo win."""
     ERR_HAITEI_WITHOUT_TSUMO = "haitei_without_tsumo_not_allowed"
+    """Haitei raoyue (last-tile draw) requires a tsumo win."""
     ERR_HOUTEI_WITH_TSUMO = "houtei_with_tsumo_not_allowed"
+    """Houtei raoyui (last-tile discard) requires a ron win."""
     ERR_HAITEI_WITH_RINSHAN = "haitei_with_rinshan_not_allowed"
+    """Haitei and rinshan are mutually exclusive (different last-tile sources)."""
     ERR_HOUTEI_WITH_CHANKAN = "houtei_with_chankan_not_allowed"
+    """Houtei and chankan are mutually exclusive."""
+    ERR_RINSHAN_WITHOUT_KAN = "rinshan_without_kan_not_allowed"
+    """Rinshan kaihou requires a kan meld, or an extracted north wind (nuki dora)."""
+    ERR_IPPATSU_WITH_RINSHAN = "ippatsu_with_rinshan_not_allowed"
+    """Ippatsu and rinshan are mutually exclusive (declaring a kan cancels ippatsu)."""
+
+    # tenhou (blessing of heaven) constraints
     ERR_TENHOU_NOT_AS_DEALER = "tenhou_not_as_dealer_not_allowed"
+    """Tenhou is exclusive to the dealer: ``player_wind`` must be East."""
     ERR_TENHOU_WITHOUT_TSUMO = "tenhou_without_tsumo_not_allowed"
+    """Tenhou requires a tsumo win on the dealer's first draw."""
     ERR_TENHOU_WITH_MELD = "tenhou_with_meld_not_allowed"
+    """Tenhou requires a closed hand with no declared melds."""
+
+    # chiihou (blessing of earth) constraints
     ERR_CHIIHOU_AS_DEALER = "chiihou_as_dealer_not_allowed"
+    """Chiihou is exclusive to non-dealer players."""
     ERR_CHIIHOU_WITHOUT_TSUMO = "chiihou_without_tsumo_not_allowed"
+    """Chiihou requires a tsumo win on the player's first draw."""
     ERR_CHIIHOU_WITH_MELD = "chiihou_with_meld_not_allowed"
+    """Chiihou requires a closed hand with no declared melds."""
+
+    # renhou (blessing of man) constraints
     ERR_RENHOU_AS_DEALER = "renhou_as_dealer_not_allowed"
+    """Renhou is exclusive to non-dealer players."""
     ERR_RENHOU_WITH_TSUMO = "renhou_with_tsumo_not_allowed"
+    """Renhou requires a ron win before the player's first draw."""
     ERR_RENHOU_WITH_MELD = "renhou_with_meld_not_allowed"
-
-    # more possible errors, like tenhou and haitei can't be together (so complicated :<)
+    """Renhou requires a closed hand with no declared melds."""
 
     @staticmethod
     def estimate_hand_value(
@@ -64,16 +136,84 @@ class HandCalculator:
         ura_dora_indicators: Collection[int] | None = None,
     ) -> HandResponse:
         """
-        :param tiles: array with 14 tiles in 136-tile format
-        :param win_tile: 136-tile format tile that caused win (ron or tsumo)
-        :param melds: array with Meld objects
-        :param dora_indicators: array of tiles in 136-tile format
-        :param config: HandConfig object
-        :param scores_calculator_factory: ScoresCalculator class or subclass
-        :param ura_dora_indicators: array of tiles in 136-tile format (only counted with riichi)
-        :return: HandResponse object
+        Estimate the point value of a winning hand.
+
+        Validate the hand and win conditions, decompose the hand into all possible
+        block combinations, evaluate yaku and fu for each decomposition, and return
+        the highest-scoring result as a :class:`~mahjong.hand_calculating.hand_response.HandResponse`.
+
+        Basic closed ron with tanyao:
+
+        >>> from mahjong.hand_calculating.hand import HandCalculator
+        >>> from mahjong.tile import TilesConverter
+        >>> tiles = TilesConverter.string_to_136_array(man="22444", pin="333567", sou="444")
+        >>> win_tile = TilesConverter.string_to_136_array(sou="4")[0]
+        >>> result = HandCalculator.estimate_hand_value(tiles, win_tile)
+        >>> result.han
+        1
+        >>> result.fu
+        40
+        >>> result.cost["main"]
+        1300
+
+        Tsumo win with riichi and pinfu:
+
+        >>> from mahjong.hand_calculating.hand_config import HandConfig
+        >>> tiles = TilesConverter.string_to_136_array(man="234789", pin="12345666")
+        >>> win_tile = TilesConverter.string_to_136_array(pin="6")[0]
+        >>> config = HandConfig(is_tsumo=True, is_riichi=True)
+        >>> result = HandCalculator.estimate_hand_value(tiles, win_tile, config=config)
+        >>> result.han
+        3
+        >>> result.fu
+        20
+        >>> result.cost["main"]
+        1300
+        >>> result.cost["additional"]
+        700
+
+        Dealer tsumo with riichi and ippatsu:
+
+        >>> from mahjong.constants import EAST
+        >>> config = HandConfig(is_tsumo=True, is_riichi=True, is_ippatsu=True, player_wind=EAST)
+        >>> result = HandCalculator.estimate_hand_value(tiles, win_tile, config=config)
+        >>> result.error is None
+        True
+
+        Open hand with melds and dora:
+
+        >>> from mahjong.meld import Meld
+        >>> tiles = TilesConverter.string_to_136_array(man="234567", pin="22", sou="234", honors="555")
+        >>> win_tile = TilesConverter.string_to_136_array(man="7")[0]
+        >>> melds = [Meld(meld_type=Meld.PON, tiles=TilesConverter.string_to_136_array(honors="555"))]
+        >>> dora_indicators = [TilesConverter.string_to_136_array(man="6")[0]]
+        >>> result = HandCalculator.estimate_hand_value(tiles, win_tile, melds=melds, dora_indicators=dora_indicators)
+        >>> result.han
+        2
+
+        Invalid hand returns an error:
+
+        >>> tiles = TilesConverter.string_to_136_array(man="12345")
+        >>> win_tile = TilesConverter.string_to_136_array(man="1")[0]
+        >>> result = HandCalculator.estimate_hand_value(tiles, win_tile)
+        >>> result.error == HandCalculator.ERR_HAND_NOT_WINNING
+        True
+
+        :param tiles: hand tiles in 136-format (14 tiles including the winning tile;
+            15 with one kan, 16 with two, etc.)
+        :param win_tile: the winning tile index in 136-format (must be present in ``tiles``)
+        :param melds: declared melds (:class:`~mahjong.meld.Meld` objects for chi, pon, kan)
+        :param dora_indicators: dora indicator tile indices in 136-format
+        :param config: hand configuration with win conditions, wind context, and optional rules;
+            defaults to a closed ron with no special conditions
+        :param scores_calculator_factory: scoring calculator class; pass
+            :class:`~mahjong.hand_calculating.scores.Aotenjou` for aotenjou (limitless) scoring
+        :param ura_dora_indicators: ura dora indicator tile indices in 136-format
+            (counted only when riichi or double riichi is declared)
+        :return: :class:`~mahjong.hand_calculating.hand_response.HandResponse` with scoring
+            details on success, or with :attr:`~mahjong.hand_calculating.hand_response.HandResponse.error`
+            set on failure
         """
-
         if not melds:
             melds = []
 
@@ -83,16 +223,27 @@ class HandCalculator:
         if not ura_dora_indicators:
             ura_dora_indicators = []
 
-        config = config or _DEFAULT_CONFIG
+        config = config or HandConfig()
 
-        hand_yaku = []
+        hand_yaku: list[Yaku] = []
         scores_calculator = scores_calculator_factory()
         tiles_34 = TilesConverter.to_34_array(tiles)
 
         is_aotenjou = isinstance(scores_calculator, Aotenjou)
 
-        opened_melds = [x.tiles_34 for x in melds if x.opened]
-        is_open_hand = len(opened_melds) > 0
+        is_open_hand = any(meld.opened for meld in melds)
+
+        if config.tsumi_number < 0:
+            return HandResponse(error=HandCalculator.ERR_NEGATIVE_TSUMI_NUMBER)
+
+        if config.kyoutaku_number < 0:
+            return HandResponse(error=HandCalculator.ERR_NEGATIVE_KYOUTAKU_NUMBER)
+
+        if config.paarenchan < 0:
+            return HandResponse(error=HandCalculator.ERR_NEGATIVE_PAARENCHAN)
+
+        if config.num_nuki_dora < 0:
+            return HandResponse(error=HandCalculator.ERR_NEGATIVE_NUKI_DORA)
 
         # special situation
         if config.is_nagashi_mangan:
@@ -105,6 +256,10 @@ class HandCalculator:
         if win_tile not in tiles:
             return HandResponse(error=HandCalculator.ERR_NO_WINNING_TILE)
 
+        for meld in melds:
+            if meld_error := HandCalculator._validate_meld(meld, tiles):
+                return HandResponse(error=meld_error)
+
         if config.is_riichi and not config.is_daburu_riichi and is_open_hand:
             return HandResponse(error=HandCalculator.ERR_OPEN_HAND_RIICHI)
 
@@ -132,8 +287,17 @@ class HandCalculator:
         if config.is_houtei and config.is_chankan:
             return HandResponse(error=HandCalculator.ERR_HOUTEI_WITH_CHANKAN)
 
-        # raise error only when player wind is defined (and is *not* EAST)
-        if config.is_tenhou and config.player_wind and not config.is_dealer:
+        if (
+            config.is_rinshan
+            and config.num_nuki_dora == 0
+            and not any(x.type in (Meld.KAN, Meld.SHOUMINKAN) for x in melds)
+        ):
+            return HandResponse(error=HandCalculator.ERR_RINSHAN_WITHOUT_KAN)
+
+        if config.is_rinshan and config.is_ippatsu:
+            return HandResponse(error=HandCalculator.ERR_IPPATSU_WITH_RINSHAN)
+
+        if config.is_tenhou and not config.is_dealer:
             return HandResponse(error=HandCalculator.ERR_TENHOU_NOT_AS_DEALER)
 
         if config.is_tenhou and not config.is_tsumo:
@@ -172,8 +336,10 @@ class HandCalculator:
         hand_options = HandDivider.divide_hand(tiles_34, melds)
 
         # precompute dora counts, invariant across all hand decompositions
-        dora_count_map = build_dora_count_map(dora_indicators)
+        dora_count_map = build_dora_count_map(dora_indicators, config.options.is_three_player)
         precomputed_dora = count_dora_for_hand(tiles_34, dora_count_map)
+        if config.num_nuki_dora > 0:
+            precomputed_dora += dora_count_map.get(NORTH, 0) * config.num_nuki_dora + config.num_nuki_dora
 
         precomputed_aka_dora = 0
         if config.options.has_aka_dora:
@@ -181,8 +347,10 @@ class HandCalculator:
 
         precomputed_ura_dora = 0
         if config.is_riichi or config.is_daburu_riichi:
-            ura_count_map = build_dora_count_map(ura_dora_indicators)
+            ura_count_map = build_dora_count_map(ura_dora_indicators, config.options.is_three_player)
             precomputed_ura_dora = count_dora_for_hand(tiles_34, ura_count_map)
+            if config.num_nuki_dora > 0:
+                precomputed_ura_dora += ura_count_map.get(NORTH, 0) * config.num_nuki_dora
 
         yakuhai_seat_wind_yaku = (
             config.yaku.seat_wind_east,
@@ -198,6 +366,7 @@ class HandCalculator:
         )
 
         calculated_hands: list[_CalculatedHand] = []
+        meld_blocks = [meld._sorted_tiles_34 for meld in melds]  # noqa: SLF001
         for hand in hand_options:
             is_chiitoitsu = config.yaku.chiitoitsu.is_condition_met(hand)
             valued_tiles = [HAKU, HATSU, CHUN, config.player_wind, config.round_wind]
@@ -221,7 +390,7 @@ class HandCalculator:
             suit_mask, honor_count = classify_hand_suits(hand)
             has_honors = honor_count > 0
 
-            win_groups = HandCalculator._find_win_groups(win_tile, hand, opened_melds)
+            win_groups = HandCalculator._find_win_groups(win_tile, hand, meld_blocks)
             for win_group in win_groups:
                 cost = None
                 error = None
@@ -424,7 +593,7 @@ class HandCalculator:
                     if not is_aotenjou:
                         hand_yaku = yakuman_list
                     else:
-                        scores_calculator.aotenjou_filter_yaku(hand_yaku, config)  # ty: ignore[unresolved-attribute]
+                        scores_calculator.aotenjou_filter_yaku(hand_yaku, config)
                         yakuman_list = []
 
                 # calculate han
@@ -475,7 +644,7 @@ class HandCalculator:
                 calculated_hands.append(calculated_hand)
 
         # exception hand
-        if not is_open_hand and config.yaku.kokushi.is_condition_met(None, tiles_34):
+        if not melds and config.yaku.kokushi.is_condition_met(None, tiles_34):
             if tiles_34[win_tile // 4] == 2:
                 hand_yaku.append(config.yaku.daburu_kokushi)
             else:
@@ -515,7 +684,7 @@ class HandCalculator:
 
                 count_of_dora = 0
                 for tile in tiles_for_dora:
-                    count_of_dora += plus_dora(tile, dora_indicators)
+                    count_of_dora += plus_dora(tile, dora_indicators, is_three_player=config.options.is_three_player)
 
                 if count_of_dora:
                     config.yaku.dora.han_open = count_of_dora
@@ -526,7 +695,9 @@ class HandCalculator:
                 if config.is_riichi or config.is_daburu_riichi:
                     count_of_ura_dora = 0
                     for tile in tiles_for_dora:
-                        count_of_ura_dora += plus_dora(tile, ura_dora_indicators)
+                        count_of_ura_dora += plus_dora(
+                            tile, ura_dora_indicators, is_three_player=config.options.is_three_player
+                        )
 
                     if count_of_ura_dora:
                         config.yaku.ura_dora.han_closed = count_of_ura_dora
@@ -542,14 +713,11 @@ class HandCalculator:
             return HandResponse(error=HandCalculator.ERR_HAND_NOT_WINNING)
 
         # find most expensive hand
-        calculated_hands = sorted(calculated_hands, key=lambda x: (x["han"], x["fu"]), reverse=True)
+        calculated_hands.sort(key=_hand_priority, reverse=True)
         # correctly sort expensive hands by fu details
-        calculated_hands = [
-            x
-            for x in calculated_hands
-            if x["han"] == calculated_hands[0]["han"] and x["fu"] == calculated_hands[0]["fu"]
-        ]
-        calculated_hands = sorted(calculated_hands, key=lambda x: sum([y["fu"] for y in x["fu_details"]]), reverse=True)
+        top_priority = _hand_priority(calculated_hands[0])
+        calculated_hands = [x for x in calculated_hands if _hand_priority(x) == top_priority]
+        calculated_hands.sort(key=lambda x: sum([y["fu"] for y in x["fu_details"]]), reverse=True)
         calculated_hand = calculated_hands[0]
 
         error = calculated_hand["error"]
@@ -567,25 +735,38 @@ class HandCalculator:
         )
 
     @staticmethod
-    def _find_win_groups(win_tile: int, hand: list[list[int]], opened_melds: list[list[int]]) -> list[list[int]]:
+    def _validate_meld(meld: Meld, tiles: Collection[int]) -> str | None:
+        if not meld.is_valid():
+            return HandCalculator.ERR_MELD_INVALID
+
+        if meld.type == Meld.NUKI:
+            return HandCalculator.ERR_NUKI_MELD_NOT_SUPPORTED
+
+        if any(tile not in tiles for tile in meld.tiles):
+            return HandCalculator.ERR_MELD_TILE_NOT_IN_HAND
+
+        return None
+
+    @staticmethod
+    def _find_win_groups(win_tile: int, hand: list[list[int]], meld_blocks: list[list[int]]) -> list[list[int]]:
         win_tile_34 = (win_tile or 0) // 4
 
-        # track which opened melds have been matched using a consumed flags array
-        consumed = [False] * len(opened_melds)
+        # track which declared melds have been matched using a consumed flags array
+        consumed = [False] * len(meld_blocks)
 
-        # collect closed sets and find unique win groups in a single pass
+        # collect undeclared sets and find unique win groups in a single pass
         seen: set[tuple[int, ...]] = set()
         win_groups: list[list[int]] = []
         for x in hand:
-            # check if this set matches an unconsumed opened meld
-            is_opened_meld = False
-            for i, meld in enumerate(opened_melds):
+            # check if this set matches an unconsumed declared meld
+            is_declared_meld = False
+            for i, meld in enumerate(meld_blocks):
                 if not consumed[i] and x == meld:
                     consumed[i] = True
-                    is_opened_meld = True
+                    is_declared_meld = True
                     break
 
-            if is_opened_meld:
+            if is_declared_meld:
                 continue
 
             # for forms like 45666 and ron on 6