/ 
Game-Cribbage-0.14
/ Game::Cribbage::Hands

NAME

Game::Cribbage::Hands - a single hands cycle within a round

VERSION

Version 0.12

SYNOPSIS

use Game::Cribbage::Hands;

my $hands = Game::Cribbage::Hands->new(
	crib_player => 'player1',
	number      => 1,
)->init($game);

# deal, then discard to crib
$hands->player1->add($card);
$hands->player1->discard(0, $hands->player1);

# play phase
my $score = $hands->play_card('player1', 0);
$hands->cannot_play_a_card('player2');
$hands->next_play($game);

# scoring phase
$hands->add_starter_card('player1', $starter);
my $scored = $hands->score_hands();

DESCRIPTION

Represents one complete hands cycle (deal, crib discard, play phase, hand scoring) within a Game::Cribbage::Round. Created via next_hands on the Round and initialised with init, which creates per-player Game::Cribbage::Player::Hand slots and the first Game::Cribbage::Play.

PROPERTIES

id

Read/write integer property for a database or external identifier.

$hands->id;
$hands->id($id);

number

Readonly integer property indicating which hands cycle this is within the round.

$hands->number;

crib_player

Read/write string property holding the player key for the current crib holder (e.g. 'player1').

$hands->crib_player;
$hands->crib_player('player2');

crib_complete

Read/write boolean property; set to 1 when both players have discarded their crib cards.

$hands->crib_complete;

starter

Read/write object property holding the starter Game::Cribbage::Deck::Card.

$hands->starter;

play

Read/write object property holding the current Game::Cribbage::Play sequence.

$hands->play;

player1 / player2 / player3 / player4

Read/write object properties each holding a Game::Cribbage::Player::Hand for the corresponding player slot.

$hands->player1;
$hands->player2;

cannot_play

Read/write hashref recording which players have declared they cannot play a card in the current play sequence. Keys are player strings ('player1' etc.), values are 1. Reset to {} at the start of each new play.

$hands->cannot_play;

play_history

Read/write arrayref of all Game::Cribbage::Play objects created during this hands cycle, in order. The last element is always the current play.

$hands->play_history;

FUNCTIONS

init

Initialises the hands cycle for $game: creates a Game::Cribbage::Player::Hand for each player and starts the first play. Returns $self.

my $hands = Game::Cribbage::Hands->new(...)->init($game);

add_starter_card

Sets the starter card, distributes it to all player hands, and awards 1 point for nobs if the starter is a Jack. Returns a Game::Cribbage::Play::Score if nobs scored, otherwise 0.

my $score = $hands->add_starter_card($player, $card);

find_player_card

Searches all player hands for a card matching $card and returns ($card, $player_string).

my ($card, $player) = $hands->find_player_card($lookup_card);

force_play_card

Marks the matching card as used and plays it via the current play, bypassing turn-order checks. Returns ($score, $player_string).

my ($score, $player) = $hands->force_play_card($card);

play_card

Plays $card_index (integer or card object) for $player, enforcing turn order and the 31-point limit. Returns a Game::Cribbage::Play::Score on success or a Game::Cribbage::Error.

my $score = $hands->play_card($player, $card_index);

cannot_play_a_card

Declares that $player cannot play without exceeding 31. If cards remain that could be played without exceeding 31, returns an arrayref of those cards instead. On success returns 1 and advances the turn.

my $result = $hands->cannot_play_a_card('player1');

set_next_to_play

Advances next_to_play on the current play to the next player, wrapping around.

$hands->set_next_to_play();

parse_next_to_play

Returns the player key that follows $player_string in turn order, wrapping from the last player back to 'player1'.

my $next = $hands->parse_next_to_play('player2');

set_player_hand_id

Sets the id on the named player's hand.

$hands->set_player_hand_id('player1', 42);

get_player_hand_id

Returns the id of the named player's hand.

my $id = $hands->get_player_hand_id('player1');

get_crib_player_hand_id

Returns the id of the crib player's hand.

my $id = $hands->get_crib_player_hand_id();

get_card

Returns the card at $card_index in the named player's hand.

my $card = $hands->get_card($player, $card_index);

play_score

Returns the current play's running total, or 0 if no play is active.

my $total = $hands->play_score();

last_play_score

Returns the running total of the previous completed play, or the string 'This is the first play' if only one play has occurred.

my $score = $hands->last_play_score();

new_play

Creates a new Game::Cribbage::Play and appends it to play_history. The next-to-play is inferred from the last card played in the previous play.

$hands->new_play();

next_play

Determines whether a new play can start or all hands are exhausted. If any player still has a playable card, returns a Game::Cribbage::Error listing those cards. If no cards remain at all, calls end_hands on $game and returns undef. Otherwise, ends the current play (awarding the go point) and starts a new one.

my $result = $hands->next_play($game);

end_play

Ends the current play (awarding the go point unless already awarded) and sets play to undef. Returns the Game::Cribbage::Play::Score for the go, or undef.

my $score = $hands->end_play();

score_hands

Calculates the score for every player hand (and crib) by calling calculate_score on each. Returns a hashref keyed by player string.

my $scored = $hands->score_hands();
# { player1 => 12, player2 => 8 }

card_exists

Returns 1 if $card exists in $player's hand (cards or crib).

$hands->card_exists($player, $card);

set_crib_complete

Marks the crib as complete by setting crib_complete to 1.

$hands->set_crib_complete();

best_run_play

Returns the best card for $player to play next, or a Game::Cribbage::Error with go set if no valid card exists.

my $card = $hands->best_run_play('player2');

next_to_play_id

Returns the player key string currently set as next_to_play on the active play.

my $player_key = $hands->next_to_play_id();

AUTHOR

LNATION, <email at lnation.org>

BUGS

Please report any bugs or feature requests to bug-game-cribbage at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Game-Cribbage. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Game::Cribbage

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2024 by LNATION.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)