/ 
Game-Gin-0.01
/ Game::Gin::Search

NAME

Game::Gin::Search - the bot's reasoning, with signatures that cannot cheat

VERSION

Version 0.01

SYNOPSIS

use Game::Gin::Search qw(worth_taking best_discard knock_now);

worth_taking(hand => \@cards, upcard => $id, level => 2);
best_discard(hand => \@cards, level => 2);
knock_now(deadwood => 6, stock_left => 20, level => 3);

DESCRIPTION

Nothing here takes a game, a stock, or the other hand

Every function is given the cards the seat holds and the cards everybody has seen. The answer is never in scope, so no version of this module can consult it however it is later edited.

That is a signature rather than a rule, because a rule is a comment and a signature is checked. In gin it matters more than in most games: a bot that could read the stock would know every card it was about to draw, and a bot that could read the other hand would know exactly when to knock. Either would play legal, replayable, winning games indistinguishable from very good ones.

The same design is in P2PGames::Game::Hangman::Search and P2PGames::Game::Battleship::Search, which say the same thing about words and fleets.

FUNCTIONS

Nothing is exported by default. All take named arguments.

potential

potential(hand => \@cards, card => $id);

How much a card could still become, from what the hand already holds: another of its rank, or a neighbour in its suit. What stops a bot throwing the card that was one away from a meld.

worth_taking

worth_taking(hand => \@cards, upcard => $id, level => 2);

Whether the face-up card leaves the hand better off than it is now.

best_discard

best_discard(hand => \@cards, level => 2, just_taken => $id);

Which card to throw. Scored by what the hand is left with; the levels differ on how ties are broken, and ties are common.

knock_now

knock_now(deadwood => 6, stock_left => 20, level => 2);

Whether to knock. Gin is never wrong. Level 1 knocks whenever it may; level 2 holds until the count is low enough to survive an undercut.

A third level was built and removed after measurement: it lost to level 2 and sometimes failed to finish a match. The comment in the source carries the numbers.

LEVELS

2. How many levels there are, measured rather than chosen.

SEE ALSO

Game::Gin::Bot, Game::Gin::Deadwood.

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.