/ 
Game-Cribbage-0.14
/ Game::Cribbage::Board

NAME

Game::Cribbage::Board - top-level game orchestration object

VERSION

Version 0.12

SYNOPSIS

use Game::Cribbage::Board;

my $board = Game::Cribbage::Board->new();
$board->add_player(name => 'Alice');
$board->add_player(name => 'Bob');
$board->start_game();

$board->set_crib_player('player1');
$board->draw_hands();           # deal 6 cards each

$board->cribbed_cards($player, 4, 5);  # discard indexes 4 and 5 to crib

$board->play_card($player, 0);
$board->cannot_play($player);
$board->next_play($board);

$board->end_hands();

DESCRIPTION

Provides the high-level API for a game of cribbage, delegating to Game::Cribbage::Rounds, Game::Cribbage::Round, Game::Cribbage::Hands, and Game::Cribbage::Deck. The board object is the primary interface used by the game UI layer (Game::Cribbage) and by external persistence layers via the id getter/setter methods.

PROPERTIES

players

Read/write arrayref of Game::Cribbage::Player objects.

$board->players;

deck

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

$board->deck;

rounds

Read/write object property holding the Game::Cribbage::Rounds manager.

$board->rounds;

FUNCTIONS

add_player

Creates a new Game::Cribbage::Player from %player args (must include name) and appends it to players. Returns $self.

$board->add_player(name => 'Alice');

add_player_if_not_exists

Finds an existing player by name; if not found, adds them. Returns ($player, $existed) where $existed is 1 if already present or 0 if newly created.

my ($player, $existed) = $board->add_player_if_not_exists(name => 'Bob');

get_player

Returns the first Game::Cribbage::Player whose name matches $name, or undef if not found.

my $player = $board->get_player(name => 'Alice');

build_deck

Constructs a new Game::Cribbage::Deck and assigns it to deck.

$board->build_deck();

build_rounds

Constructs a new Game::Cribbage::Rounds with the given round count.

$board->build_rounds(1);

start_game

Initialises the deck and rounds if not already done, then advances to the first (or next) round. Accepts optional rounds and id args.

$board->start_game();
$board->start_game(rounds => 2, id => 99);

next_hands

Advances the current round to the next hands cycle with the given args.

$board->next_hands(crib_player => 'player2');

force_to_crib

Forces a specific card (hashref { suit => ..., symbol => ... }) into the crib player's crib, drawing it from the deck if available or generating it.

$board->force_to_crib({ suit => 'H', symbol => '5' });

force_draw_card

Forces a specific card into $player's hand, drawing from the deck or inserting at $index if not in the deck.

$board->force_draw_card($player, 0, { suit => 'H', symbol => '7' });

draw_hands

Deals 6 cards to each player from the deck.

$board->draw_hands();

add_starter_card

Sets the starter card on the current hands cycle.

$board->add_starter_card($player, $card);

get_hands

Returns the current Game::Cribbage::Hands object.

my $hands = $board->get_hands();

identify_worst_cards

Returns the two worst cards to discard from $player's hand.

my ($cards, @indexes) = $board->identify_worst_cards($player);

validate_crib_cards

Validates (and if necessary replaces) the crib player's crib cards.

$board->validate_crib_cards(\@cards);

crib_player_id

Returns the id of the current crib player.

my $id = $board->crib_player_id();

crib_player_identifier

Returns the player key string (e.g. 'player1') of the crib holder.

my $key = $board->crib_player_identifier();

crib_player_name

Returns the display name of the crib player.

my $name = $board->crib_player_name();

crib_player_number

Returns the seat number of the crib player.

my $num = $board->crib_player_number();

crib_player_cards

Discards multiple cards from $player's hand into the crib.

$board->crib_player_cards($player, \@cards);

cribbed_card

Discards a single card at $index from $player's hand into the crib.

$board->cribbed_card($player, 2);

cribbed_cards

Discards multiple cards (by index) from $player's hand into the crib. Indexes are processed in descending order to avoid splice shifting.

$board->cribbed_cards($player, 4, 5);

force_play_card

Forces a card into play bypassing turn-order checks.

$board->force_play_card($card);

play_card

Plays $index for $player with full validation.

$board->play_card($player, 0);

get_card

Returns the card at $index in $player's hand.

my $card = $board->get_card($player, 0);

current_play

Returns the active Game::Cribbage::Play object.

my $play = $board->current_play();

current_play_cards

Returns an arrayref of the Game::Cribbage::Deck::Card objects played so far in the current play sequence.

my $cards = $board->current_play_cards();

current_play_score

Returns the running total of the current play sequence.

my $total = $board->current_play_score();

last_play_score

Returns the running total of the previous completed play sequence.

my $total = $board->last_play_score();

score

Returns the Game::Cribbage::Round::Score for the current round.

my $score = $board->score();

cannot_play

Declares that $player cannot play in the current sequence.

$board->cannot_play($player);

player_cannot_play

Returns true if $player has already declared cannot-play this sequence.

$board->player_cannot_play('player1');

no_player_can_play

Returns true when all players have declared cannot-play.

$board->no_player_can_play();

next_play

Advances to the next play sequence.

$board->next_play($board);

end_play

Ends the current play sequence, awarding the go point.

$board->end_play();

end_hands

Scores all hands, rotates the crib, and starts the next hands cycle.

$board->end_hands();

shuffle

Shuffles the deck.

$board->shuffle();

get_round_id / set_round_id

Get or set the current round's database identifier.

$board->set_round_id(42);
my $id = $board->get_round_id();

get_hands_id / set_hands_id

Get or set the current hands cycle's database identifier.

$board->set_hands_id(7);
my $id = $board->get_hands_id();

get_play_id / set_play_id

Get or set the current play sequence's database identifier.

$board->set_play_id(3);
my $id = $board->get_play_id();

get_crib_player_hand_id

Returns the database identifier of the crib player's hand.

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

set_player_hand_id / get_player_hand_id

Set or get the database identifier for a specific player's hand.

$board->set_player_hand_id('player1', 55);
my $id = $board->get_player_hand_id('player1');

set_crib_complete

Marks the crib as complete.

$board->set_crib_complete();

crib_complete

Returns the crib-complete flag.

$board->crib_complete();

best_run_play

Returns the best card for $player to play.

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

total_player_score

Returns the cumulative score for $player in the current round.

my $score = $board->total_player_score('player1');

set_crib_player

Sets the crib holder to $player and aligns the play's next-to-play.

$board->set_crib_player('player2');

next_to_play_id

Returns the id of the player whose turn it is to play.

my $id = $board->next_to_play_id();

next_to_play

Returns the Game::Cribbage::Player object whose turn it is.

my $player = $board->next_to_play();

set_next_to_play

Sets the next-to-play player key on the active play.

$board->set_next_to_play('player2');

hand_play_history

Returns a hashref with current_play and used_count keys summarising the play history.

my $hist = $board->hand_play_history();

reset_hands

Resets the current round's hands history and scores.

$board->reset_hands();

last_round_hands

Returns the penultimate Game::Cribbage::Hands object from the current round's history (i.e. the hands cycle that preceded the current one).

my $hands = $board->last_round_hands();

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)