NAME
Game::Mahjong::Hand - one seat's tiles: the counts, the melds, the flowers
VERSION
Version 0.01
SYNOPSIS
my $hand = Game::Mahjong::Hand->from_notation('123m 55p EEE 78s');
$hand->add(27); # a drawn nine of bamboo
$hand->size; # 14
$hand->chow_shapes(24); # the pairs in hand that run with a six of bamboo
my $meld = $hand->claim_pung(28, 2); # the pair of east winds and seat 2's discard
$hand->expects; # 10: thirteen less three a meldDESCRIPTION
The concealed tiles are a count vector over the thirty-four kinds, because tiles of a kind are identical and every question the rules and the decomposer ask is about counts. The melds are Game::Mahjong::Meld objects in the order they were made; the flowers are the exposed bonus tiles.
Thirteen between turns
A seat holds thirteen tiles between turns counting three for every meld (3.4.29); expects is that number for the melds so far, and total is the concealed count plus three a meld, fourteen for a complete hand whatever its kongs.
The claims are mechanics, not rules
claim_chow, claim_pung, claim_kong, concealed_kong and promote_kong move the tiles and build the meld, and die if the tiles are not there: that is a programmer error. Whether the seat MAY claim (its turn, the window, the seat to the left, the kong after a chow) is Game::Mahjong::Rules' question, answered with a code before any of these is called.
The waits are a cache
waits is the list of kinds that complete the hand, filled by Game::Mahjong::Shanten only when the hand is one from ready, and cleared by every change to the tiles or the melds. It is what makes "can this seat win on the tile" a lookup when a window opens.
ATTRIBUTES
counts
An arrayref of thirty-five: index 1 to 34 the count of that kind, index 0 unused.
melds
The melds made, in order.
flowers
The exposed bonus tiles, sorted.
waits
The cached waits, or undef when not computed.
METHODS
from_tiles
A hand from a list of kinds.
from_notation
A hand from a notation string with melds and flowers.
add, remove
One tile in or out. Both die on a bonus tile and remove dies below zero.
add_flower
One bonus tile exposed. Dies on a second of the same.
count
How many of a kind are concealed.
size
How many tiles are concealed.
tiles
The concealed tiles as a sorted list with repeats.
kinds
The distinct kinds held, sorted.
meld_count, total, expects
As above.
is_concealed
No exposed meld; a concealed kong does not count against it.
concealed_kongs
The concealed kongs, to be shown at the end of the hand.
holds_pair, holds_pung_of, holds_kong_of
Two or more, three or more, exactly four of a kind concealed.
exposed_pung_of
The exposed pung of a kind, for promotion, or undef.
chow_shapes
my @pairs = $hand->chow_shapes($kind);Every pair of concealed tiles that makes a chow with the kind, each a sorted two-element arrayref, lowest chow first; empty for an honour.
claim_chow, claim_pung, claim_kong, concealed_kong, promote_kong
The mechanics above. Each returns the meld.
clone
A copy the caller may change.
to_notation
The hand as a notation string.
FULL
Thirteen.
SEE ALSO
Game::Mahjong::Meld, Game::Mahjong::Wall, Game::Mahjong::Notation
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.