Sanma support

[Nihisil]

Below is approximate plan of what we need to do, full research required for full requirements.

Add full sanma support to the library:

• Add support for shanten calculations
• Add support for is_agari calculations
• Add support for hand yaku calculations
• Add support for scores calculations

[Apricot-S]

1. Tsumo Loss (ツモ損) handling

Using the four-player scoring logic as-is will cause underpayment on tsumo wins because Sanma has one fewer child compared to four-player mahjong.

Many Sanma rulesets (including common offline rules) split the missing North seat payment between the remaining two players.

Meanwhile, in Tenhou and Mahjong Soul ranked matches, "tsumo loss ON" is the default behavior, but tournament modes in both platforms allow switching this option ON/OFF.

We should decide whether the library will:

• support both modes (tsumo-loss ON/OFF), or
• choose one as the default behavior.

This affects the score calculation API and configuration.

2. Treatment of Nuki-dora (抜きドラ)

Sanma rules often include nuki-dora, but implementations differ:

The library already defines Meld.NUKI, but it has not been used internally so far.
We need to decide whether nuki-dora is:

• counted as a separate yaku (Mahjong Soul style), or
• merged into normal dora count (Tenhou style).

This affects yaku evaluation, scoring, and meld representation.

3. Handling of 2m–8m tiles

Standard Sanma excludes 2m–8m entirely.
We need to define behavior when a hand or meld containing these tiles is passed to the API:

• Should Sanma mode enable strict validation and reject such hands?
• Or should the library silently ignore/normalize them?
• Or should the core remain permissive and validation be optional?

This affects shanten, agari, and yaku evaluation.

4. Handling of Meld.CHI

Chi is normally disabled in Sanma.
If a user passes melds containing Meld.CHI while Sanma mode is active, we need to define:

• Should this be treated as invalid input?
• Should the library ignore chi melds?
• Or should chi be allowed only if the ruleset explicitly enables it?

This affects meld validation and agari logic.

[Apricot-S]

I have implemented a shanten calculation for three player mahjong.
It is implemented in the feat/3p-shanten branch.

@Nihisil
Which do you think would be better: adding a method for three players, or adding an option flag like is_three_player: bool to the existing method (for four players)?
Also, I would like to hear your opinion on the naming of each (such as three_player, is_three_player, is_3p, etc.).

[Nihisil]

@Apricot-S thanks!

I think adding is_three_player flag to the current shanten class would be ok

[Apricot-S]

I would suggest keeping the Sanma support intentionally limited for now.

My proposal is:

1. Add explicit support for nuki-dora in scoring/yaku evaluation, treating it as additional dora (Tenhou-style).
2. Do not support tsumo-loss OFF.
3. Do not add special handling for Meld.CHI in Sanma mode.
4. Do not add special handling for 2m–8m validation outside shanten.

For tsumo-loss OFF, the rules are not fully uniform across rulesets. In particular, after splitting the missing North seat payment between the remaining players, rounding and adjustment rules can differ depending on the ruleset or region. This makes it difficult to represent cleanly with a simple formula, and supporting it properly may require ruleset-specific score tables. For this library, I think it is better to support the Tenhou-style (tsumo-loss ON) default behavior and keep tsumo-loss OFF out of scope.

For Meld.CHI and 2m–8m, I think these are primarily invalid inputs under standard Sanma rules, but they do not require changes to the agari or score calculation logic itself. Shanten calculation is different because the tile set changes, so validation there makes sense. For agari/yaku/score, I would prefer not to add Sanma-specific validation unless it is necessary for the calculation.

For nuki-dora, I would prefer adding an explicit argument such as nuki_count: int rather than relying on Meld.NUKI. Since nuki-dora is treated as additional dora, it does not need to be part of the meld structure used in hand decomposition.

Finally, I think the Sanma yaku/scoring behavior should follow Tenhou where applicable. The existing four-player validation already uses Tenhou logs, and aligning nuki-dora handling and other rule details with Tenhou would keep the overall behavior consistent.

[Nihisil]

Thanks for suggestions, and I agree with you that we can support only these mentioned cases for sanma games

[Apricot-S]

The score calculation needs to account for the reduction in the amount of tsumi sticks paid by the North player.

[Apricot-S]

@Nihisil
I would like to ask your opinion about the API design for num_nuki_dora.

I added num_nuki_dora as an argument of HandCalculator.estimate_hand_value(). However, after reconsidering the design, I think that decision may not have been the best one.

HandConfig already contains scoring-context values such as kyoutaku_number, tsumi_number, and paarenchan. Since num_nuki_dora is also a per-hand scoring context value, I now think it would be more natural to put it in HandConfig.

So I am considering reverting the estimate_hand_value() argument and adding num_nuki_dora to HandConfig instead.

What do you think?