/ 
Game-Gin-0.01
/ Game::Gin::Scoring

NAME

Game::Gin::Scoring - lay-offs, and what a hand was worth

VERSION

Version 0.01

SYNOPSIS

use Game::Gin::Scoring qw(best_layoff settle);

my $lay = best_layoff($unmatched, $knocker_melds);
$lay->{laid};       # the cards laid off
$lay->{deadwood};   # what the defender is left with

my $r = settle(
    knocker          => 'p1',
    defender         => 'p2',
    knocker_deadwood => 4,
    knocker_melds    => $melds,
    defender_cards   => $cards,
);
$r->{winner};  $r->{points};  $r->{kind};   # knock, gin, big_gin, undercut

DESCRIPTION

The numbers, and which ruleset they are from

Gin 25, undercut 25, big gin 31: the modern set, as Wikipedia states it. The older published set, which Pagat gives and Wikipedia calls the early official rules, is gin 20 and undercut 10. Mixing the two would give scoring that no publication describes and no vector to test against.

Lay-offs are computed, not offered

Laying off only ever reduces the defender's deadwood, so declining is never right and it is not a decision worth a turn. It is searched rather than taken greedily, because a card can extend two melds and the choice matters.

An undercut includes equal counts

A knock that merely ties the defender scores the defender, not the knocker.

FUNCTIONS

Nothing is exported by default.

best_layoff

my $lay = best_layoff(\@unmatched, \@melds);

The lay-off that leaves the defender with the least deadwood. Returns laid, the grown melds, and the resulting deadwood.

settle

Who won a hand and by how much, given the knocker, the defender's cards and whether it was gin. Lay-offs are applied unless it was gin.

match_result

my $m = match_result(hands => \@hand_results, target => 100);

What a whole match came to, given the results of its hands in order. Returns winner, loser, hand_points, hands_won, shutout, totals and the target.

The winner is the player who reached the target, and the bonuses decide the margin rather than the winner. The totals can invert: a player who wins eight small hands collects eight box bonuses and may finish with the higher number without having won the game.

A shutout doubles each player's hand points before the box bonuses are added, which is the order the source gives. Doubling afterwards would pay the boxes twice.

A cancelled hand was won by nobody, so it pays no box bonus and does not break a shutout.

GIN_BONUS, UNDERCUT_BONUS, BIG_GIN_BONUS

25, 25 and 31.

TARGET, BOX_BONUS, GAME_BONUS

100, 25 and 100: the score a match runs to, what each hand won is worth at the end, and what winning the match is worth.

SEE ALSO

Game::Gin::Deadwood, Game::Gin::Meld.

AUTHOR

LNATION, <email@lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION.

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