Volity::Seat - A Volity seat, containing some players.

 # From within a Volity::Game subclass's code:
 my @seats = $self->seats;

 # Or, given a Volity::Player object:
 my $seat = $player->seat;

 # Now tell the seat they just picked up the Three of Clubs:
 $seat->call_ui_function("draw_card", "3C") 

An objects of this class represents a seat at a Volity table. Volity players who are actually playing a game sit in seats, and referees address game-specific RPC calls to seats, not to individual players. See the main Volity documentation for more information about the seat concept: http://www.volity.org/wiki/index.cgi?action=browse&id=Seats

As a game programmer, you need never create, modify, or destroy these objects yourself; that is all handled for you by the other objects that make up a Frivolity-run table, particularly the referee (see Volity::Referee). However, several methods of Volity::Game, the module you subclass to create your own Perl-based Volity game, will return objects of this class. Several crucial functions of communicating with a game's players involve calling methods on these objects, including the all-important call_ui_function method (described below).

Your Volity::Game subclass must define some variables that assist the referee in seat creation, particularly the seat_ids and required_seat_ids class variables. If you wish to extend this class for your game, you can speficy a Volity::Seat subclass to use through Volity::Game's seat_class method. All these are described in detail within Volity::Game.

You should treat these as read-only instance variables; the referee will adjust their values as necessary over the lifetime of the seat.

id

Returns the string that is this seat's ruleset-defined ID. Note that it is not prefixed with the "seat." namespace designation, so you'll have to add that yourself if using it in contexts where such is necessary.

players

Returns the list of Volity::Player objects sitting in this seat (or a reference to that list, in scalar context).

registered_player_jids

Returns the JIDs of all of the players who have ever sat in this seat while the current game has been active. In other words, it's the list of JIDs that will appear as this seat's players on the final game record, assuming that no other players sit in the seat before the game ends.

is_eliminated ($boolean)

If called with an argument, sets the seat's "eliminated" bit appropriately. In other words, if something happened in the game that caused this seat to be permanently removed from play, you should set this to 1.

Returns 1 if the seat is eliminated, 0 otherwise.

call_ui_function ($function, @args)

Sends the RPC request "game.$function(@args)" from the referee to the clients of all the players sitting in this seat.

(This method also exists on player objects, if you need to call it on individual players... but generally you won't have any reason to. From a game's perspective, all the players in a seat are a single game-playing entity.)

Jason McIntosh <jmac@jmac.org>

Copyright (c) 2005-2006 by Jason McIntosh.