NAME

Volity::WinnersList - class for Volity game record winners lists

SYNOPSIS

Here's code you might see in a Volity::Game subclass implementing a game where there is one winner and a bunch of losers, the latter of whom are all effectively tied for second place (we assume that the methods called in the first two lines are defined elsewhere):

if ($self->game_has_been_won) {
    my ($winner, @losers) = $self->get_winning_seat_order;
    $self->winners->add_seat_to_slot($winner, 1);
    $self->winners->add_seat_to_slot(\@losers, 2);
    $self->end;
}

And here's what you might see in a subclass defining a score-using games where each player has a discrete ordinal place, and ties and ties are not possible (again assuming the presence of some magic methods defined somewhere else in the subclass):

 if ($self->game_has_been_won) {
     my @ordered_seats = $self->get_winning_seat_order;
     for (my $index = 0; $index <= $#ordered_seats; $index++) {
	 my $place = $index + 1;
	 $self->winners->add_seat_to_slot($ordered_seats[$index], $place);
     }
     $self->end;
 }

DESCRIPTION

Attached to every Volity::Game-subclass object is a WinnersList object, accessible through the game object's winners method. When a game wraps up, it should use the methods listed in this document to place the table's seats in a winning order before calling the end method. The referee will then use this information when it builds the game record to send to the Volity bookkeeper.

METHODS

slots

Accessor to the raw list of winner slots. Returns an array of anonymous arrays, each representing a single slot, in winning order: the one at index [0] is the winningest slot, and the one at [-1] is the losingest. Each of these slot-arrays contains a number of Volity::Seat objects.

add_seat_to_slot ($seat, $position)

Adds the given seat to the winners list at the given position. Note that the position is expressed in game-rank, so the first-place position is 1, not 0.

If there are already seats at the current position, the given seat will share the slot with them. As a shortcut, you can add several seats at once to the same slot by passing an arrayref of seats as the first argument.

seats_at_slot ($position)

Returns the list of seats the given position in the winners list. Note that the position is expressed in game-rank, so the first-place position is 1, not 0.

AUTHOR

Jason McIntosh <jmac@jmac.org>

COPYRIGHT

Copyright (c) 2005-2006 by Jason McIntosh.