NAME

Game::Mahjong::Score - the points of a winning hand under the five principles

VERSION

Version 0.01

SYNOPSIS

my $tally = Game::Mahjong::Score::score($hand, $winning_kind, {
    by => 'discard', prevailing => 0, seat => 1, flowers => 2,
});
$tally->points;         # 93
$tally->minimum_met;    # 1: basic 91 >= 8

Game::Mahjong::Score::MINIMUM;   # 8
Game::Mahjong::Score::floor($hand, \%ctx);   # a lower bound from the melds

DESCRIPTION

For every split of the hand (Game::Mahjong::Decompose) and every placement of the winning tile in it, the fans the checkers find (Game::Mahjong::Fans) are combined under the rulebook's principles (3.9.1.5) and the highest total is the score. Flowers are added after the minimum is read, because a hand of seven points and a flower cannot win (3.11.6.6: "at least 8 points ... not counting the points for Flowers"). A hand with no fan at all scores Chicken Hand's eight.

The principles as applied

The primary fan is the highest. A fan that a kept fan excludes or implies is dropped, whichever of the two the rulebook wrote the exclusion on. Within a fan the instances kept use disjoint sets. Across fans, an instance that combines two or more sets is kept only while at least one of its sets is not yet in any kept combination, which is the account-once rule read literally: "you can only combine any remaining sets once with a set that has already been used". So a pure straight with a fourth chow that doubles one of its three scores one of Pure Double Chow, Short Straight or Two Terminal Chows and not two, which is what Appendix 1's Full Flush example says. A fan that names one set (a dragon pung) or none (a flush, a wait) is not a combination and is never blocked by usage.

The waits are read from the thirteen

If the context carries no waits, the scorer removes the winning tile and asks the decomposer what the thirteen waited on, so the edge, closed and single waits are scored only when that tile was the hand's only wait.

FUNCTIONS

score

my $tally = score($hand, $winning_kind, \%ctx);

A Game::Mahjong::Tally, or undef for a hand that is not complete. Dies unless the hand is fourteen tiles' worth. The context is Game::Mahjong::Fans' plus flowers.

minimum_met

Whether a tally's basic points reach MINIMUM.

floor

A lower bound on a hand's eventual score from its exposed melds alone: the set-based fans found within the melds, combined. Zero with no melds. For the bot's "can I still reach eight" test.

MINIMUM

Eight.

SEE ALSO

Game::Mahjong::Fans, Game::Mahjong::Tally, Game::Mahjong::Result

AUTHOR

LNATION <email@lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION <email@lnation.org>.

This is free software, licensed under the Artistic License 2.0.