Frivolity Developer's Guide

For your first trick, you will create a list of the requests that a player of the game can send to the referee. This list must be abstract enough that it remains independent from any user interface which might be applied to the game. In other words, it should not concern itself with things as low-level as player-side mouse movements or keystrokes, or even button-clicks, menu selections, or any other action that the human player might perform; instead, it defines only the final messages sent to the referee as a result of all that furious typing and clicking.

These requests should contain no actual game logic. They are merely the communication vehicle between player and referee; it's up to the ref to decide is the messages it receives actually make any sense. Take the following line from Volity's chess ruleset:

move_piece(start_square, destination_square)
	

Since it's defined in the player-to-referee API, a player can send this request to the referee at any time during the game, even if (by virtue of its arguments, or even of simple timing) the player is asking for the impossible. So, the referee will happily receive requests to move a pawn ahead by three spaces, or start a move from an empty square, or even move a piece when it's not that player's turn.

There are, informally, two types of player-to-referee requests. Beyond the conceptual difference, they also differ in the kinds of return values they expect from the referee.

Since the referee must tell the players — quite often all at once — about every player-knowable change in the game state, the referee-to-player API tends to run much longer than its complement, with functions for every sort of information that a game's referee might need to pass along to players. The attitude of these messages also differs from the player-to-referee methods, more resembling assertions and commands than requests. While running a game, the referee is the lone arbiter of that game's reality, and the players take its word as the unquestionable truth.

As with the player-to-referee API, one can informally divide methods defined by a ruleset's referee-to-player API into two categories. The division comes, however, by the number and nature of intended receivers. There is no real difference in the way the referee sends them, or in how client applications receive and react to them.

Let's see what our old friend RPS has as its referee-to-player API. Actually, this simple game contains only a single function in that direction:

And that's that, for this trivial game. Note that the ruleset assumes that the client-side UI file is smart enough to declare a winner for itself, based on the results of the two player_chose_hand calls that it will receive. It didn't have to do it this way; we wouldn't necessarily have slapped the Considered Harmful label onto a declare_winner(player) function, or the like. It just happens that this particular ruleset author^[4] prefers to make communication protocols as small as possible^[5].

Crazy Eights, being a more sophisticated game than RPS, has an API to match.

Here, the latter two functions are meant to the directed at individual players, as they deal with information that only those players should see (that being the rank and suit of the cards). Note that, when a player successfully draws a card (by sending the draw_card() request seen in the section called “The Player-to-Referee API”), the referee reacts by sending two messages to the players: the secret draw_card() to the player who actually made the action, and the public player_drew_card to the entire table, thus informing everyone about that player's increased hand size, without spilling the beans as to the card's specifics.

The referee-to-player function-call API really defines only half of the communication that the ref can send players over the course of a game. Error codes provide the rest, giving the referee a way to bark at players about what they're doing wrong, using predefined code numbers so that players' UI files can (if they choose) interpret these errors in creative ways.

The error-codes section of a ruleset definition document lists all the possible fault-responses that the ref might choose to blast back at players after receiving faulty requests from them. By convention, these codes exist in the 900-range, and each is paired with a suggested error message that should accompany the code.

Let's have a look at the RPS and Crazy eights error-code tables.

Note that codes have a particular meaning only for a single ruleset, as 901 is defined two different ways in the above two examples.

With all the APIs and error codes for your ruleset defined, you're nearly done! The final step involves choosing a URI to use as the ruleset's label, and then registering it with the Volity bookkeeper.

Volity places no restrictions on what you may use as a URI. While rulesets written or maintained by members of the core Volity development team often have URIs falling within the volity.org domain, ruleset authors are encouraged to use any URI under their own control. Optimally, a ruleset URI will also act as a URL, pointing at a Web page that, when visited with a browser, results in a page summarizing the ruleset (perhaps with additional, human-readable game rules and other notes), making it an excellent resource for developers and players alike.

When you have chosen a URI, take it over to http://volity.net and use the tools there to make it official. Congratulations! You can now move on to the really fun part — making your game module actually happen, by building a Perl module for it.

The first step, of course, involves creating a new Perl module that subclasses Volity::Game. See the section called “Completing the RPS example module” or the section called “A more complex example: Crazy Eights” if you need a nudge in this direction.

Frivolity uses Perl's fields pragma for defining inheritable object fields^[7]. Three of these fields are of particular interest to game module programmers.

To configure your module, you call some methods that set some class data fields.^[8]

With that in mind, let's start programming our RPS game. We'll write the necessary Perl-module handwaving, and then add in the configuration information.

package Volity::Game::RPS;
	
use warnings;
use strict;
	
# The following line makes this an actual Frivolity game module!
use base qw(Volity::Game);

__PACKAGE__->max_allowed_players(2);
__PACKAGE__->min_allowed_players(2);
__PACKAGE__->uri("http://volity.org/games/rps");

1;
    

Actually, an RPS player should probably have a field to store the hand-shape that they've chosen to throw. So, let's declare and then create an appropriate subclass of Volity::Player which defines a hand field. After adding in the appropriate lines, our module file now looks like this:

package Volity::Game::RPS;

use warnings;
use strict;

# The following line makes this an actual Frivolity game module!
use base qw(Volity::Game);

__PACKAGE__->max_allowed_players(2);
__PACKAGE__->min_allowed_players(2);
__PACKAGE__->uri("http://volity.org/games/rps");
__PACKAGE__->player_class("Volity::Player::RPS");

# The remainder of this file defines our player subclass. We'll insert
# edits to the game subclass above this line.
package Volity::Player::RPS;

use base qw(Volity::Player);
use fields qw(hand);

# That's it. We just wanted to add the 'hand' to the class's
# object-field list, which will automagically create a hand()
# accessor method for us.

1;      
    

We don't need to make any further changes to that player class, so all the example code for the remainder of this section will go above its package declaration. (We'll have a final look at the entire file, with both packages, after we're done putting the all the pieces together.)

Your module can optionally define any of the following object methods. They all exist as no-op stub methods in the base class, so you can choose to not override them. However, it's likely that you'll want to override at least start_game in order to define custom setup activity.

The referee calls each of these methods at certain points during the game object's lifetime.

In our RPS module, we override start_game to set all the players' hands to undef. Even though the player objects' hand fields are already undefined when they are first created, they will have a value (whichever hand type the player last threw) if the players played in the previous game at this table.

sub start_game {
  my $self = shift;
  for my $player ($self->players) {
    $player->hand(undef);
  }
}
    

Your module must define one method for every function defined by the ruleset's player-to-referee API. Furthermore, each method must be named after the API function it implements, prefixed with "rpc_" (which offers a bit of network security, since the referee prepends that string to all the RPC requests it receives for the game). This is true even if it breaks Perl subroutine-naming convention, as when a ruleset's API functions use StudlyCaps, for example. Since players invoke these methods directly upon your object via RPC, you've got no say in that matter (unless, of course, you also happen to be writing the ruleset API).

Each of these player-called methods should do something appropriate for the game, typically some combination of making internal state changes and calling UI functions on players (see the section called “Talking to Players”).

Mind the return values of these callback methods! They have a direct effect on the RPC response message that the referee will send back to the player, as follows:

According to its ruleset API, Rock Paper Scissors has but one player-to-referee call, choose_hand. Let's add that to our code now, but really just have it call another method, since that's going to contain the entirety of our game's logic! We'll see how that works in the section called “Completing the RPS example module”.

sub rpc_choose_hand {
  my $self = shift;
  return $self->set_hand(@_);
}
    

The referee-to-player section of the ruleset's API should define everything you'd ever need to tell your game's players. You don't need to implement these functions yourself; that's the job of the client-side UI file. Your game module simply needs a way to call these functions, and Frivolity gives you two ways to do this.

The Volity::Player base class defines a call_ui_function() object method, which takes as arguments the name of a player-side function, and any of its arguments you might like to pass along. The referee then uses RPC to call this function on the player represented by the invocant object.

For example, if we were implementing Crazy Eights, then we would need to reaction to a player drawing a card by putting some card's name into a variable named $card, and then sending it to the player via the API-defined draw_card(card) function. So, if that player happened to be in $drawing_player, then we'd say:

$drawing_player->call_ui_function('draw_card', $card);
    

Quite often (perhaps more often than not), you'll want to communicate something game-related to everyone at the table. You could individually invoke call_player_ui() on every player stored in the game's players field, but you'd probably be happier using the convenient call_ui_function_on_everyone() object method that's attached to your game object. It takes the same arguments as the other method, and does just what its name implies, invoking the named function (with included arguments) on every player.

This is actually the salient method as far as our Rock Paper Scissors implementation is concerned, since the referee of this game never has to send private messages to either player. And as it happens, the only time that it must send messages at all happens when the game ends, and it reveals both players' hand-throws to everyone at the table.

Finally, you can use ordinary Jabber messaging to communicate, sending chat messages to the table or to individual players (or even other people and entities on the Jabber network, if you really want to). The game classes don't offer any native way to do this, but you can instead pull strings on the encapsulated referee object to make it talk; for example, to send a friendly greeting to everyone in the table, where $self is a game object:

$self->referee->groupchat("Hello, everyone!");
    

Consult the Volity::Jabber manpage to learn about groupchat and the other chatty messages. And note that this chatting absolutely should not stand in for the API-defined referee-to-player calls; it should only be used for "color", or perhaps clever, off-spec hacks of your own devising, if used at all.

When the game has ended, you must tally up the results, and then let the referee know that it's time to wrap up.

First, create a new list comprising the players in winning order. That is, the person who won the game has their player object as the first member of the list, the second-place player is the second member, and so on down through whomever came in last. In the case of a tie for any position, use a list reference for that position, containing all the player objects who share that spot.

Once you've made this list, assign it to the game object's winners field, and then call the game's end_game() method, with no arguments. The referee takes care of the rest, destroying the game object in the process.

Now that we know how to receive and react to player activity, we can complete the RPS module, with a single, rather lengthy method that handles the ruleset's single player-to-referee function. Here's what the entire file looks like, then:

package Volity::Game::RPS;

use warnings;
use strict;

use base qw(Volity::Game);

__PACKAGE__->max_allowed_players(2);
__PACKAGE__->min_allowed_players(2);
__PACKAGE__->uri("http://volity.org/games/rps");
__PACKAGE__->player_class("Volity::Player::RPS");

sub start_game {
  my $self = shift;
  for my $player ($self->players) { 
    $player->hand(undef);
  }
}
			      
sub set_hand {
  my $self = shift;
  my ($player, $hand) = @_;
  if (substr("rock", 0, length($hand)) eq lc($hand)) {
    $player->hand_type('rock');
  } elsif (substr("paper", 0, length($hand)) eq lc($hand)) {
    $player->hand_type('paper');
  } elsif (substr("scissors", 0, length($hand)) eq lc($hand)) {
    $player->hand_type('scissors');
  } else {
    # I don't know what this hand type is.
    return (fault=>901);
  }

  # Has everyone registered a hand?
  if (grep(defined($_), map($_->hand_type, $self->players)) == $self->players) {
    # Yes! Time for BATTLE!
    # Sort the players into winning order.
    my @players = sort( {
			 my $handa = $a->hand_type; my $handb = $b->hand_type;
			 if ($handa eq $handb) {
			   return 0;
			 } elsif ($handa eq 'rock' and $handb eq 'scissors') {
			   return -1;
			 } elsif ($handa eq 'scissors' and $handb eq 'paper') {
			   return -1;
			 } elsif ($handa eq 'paper' and $handb eq 'rock') {
			   return -1;
			 } else {
			   return 1;
			 }
		       }
			$self->players);
    # Tell both players what their opponent chose
    for my $player (@players) {
      $self->call_ui_function_on_everyone('player_chose_hand',
					  $player->hand,
					 );
    }
    # Tell the players who won, using Jabber messaging (just because we can).
    my $victory_message;
    if ($players[0]->hand_type eq $players[-1]->hand_type) {
      $victory_message = sprintf("A tie! Both players chose %s.", $players[0]->hand_type);
      foreach (@players) { $_->call_ui_function(game_over=>'tie') }
      $self->winners([[@players]]);
    } else {
      if ($players[0]->hand_type eq 'rock') {
	$victory_message = sprintf("%s(rock) crushes %s(scissors)!", $players[0]->nick, $players[1]->nick);
	$self->winners($players[0], $players[1]);
      } elsif ($players[0]->hand_type eq 'scissors') {
	$victory_message = sprintf("%s(scissors) shreds %s(paper)!", $players[0]->nick, $players[1]->nick);
	$self->winners($players[0], $players[1]);
      } else {
	$victory_message = sprintf("%s(paper) smothers %s(rock)!", $players[0]->nick, $players[1]->nick);
	$self->winners($players[0], $players[1]);
      }
    }
    $self->referee->groupchat($victory_message);
    $self->end_game;
  }

  # At any rate, return undef, so the calling player gets a generic
  # success response message.
  return;
  
}

####################
# Incoming RPC request handlers
###################

sub rpc_choose_hand {
  my $self = shift;
  $self->set_hand(@_);
}

package Volity::Player::RPS;

use base qw(Volity::Player);
use fields qw(hand_type);

1;
    

Now we'll cover a more complex game module, one that plays Crazy Eights, according to the ruleset APIs for that game which we defined earlier in this article. This task is rather more interesting than implementing RPS, since the player-to-referee API now contains several commands, and we will make use of a third-party Perl module — Games::Cards, by Amir Karger^[9].

package Volity::Game::CrazyEights;

use warnings;
use strict;

use base qw(Volity::Game);
# Fields:
#  deck: A Cards::Games::Deck object.
#  discard_pile: A Cards::Games::Pile object.
#  last_8_suit: The initial of the suit that the last 8-player called.
#  last_card_player: The player who has most recently played a card.
use fields qw(orig_deck deck discard_pile last_8_suit last_card_player);
use Games::Cards;

################
# Configuration
################

# Configure some class data, using field names inherited from Volity::Game.
__PACKAGE__->max_allowed_players(5);
__PACKAGE__->min_allowed_players(1);
__PACKAGE__->uri("http://volity.org/games/eights/index.html");
__PACKAGE__->player_class("Volity::Player::CrazyEights");

################
# Callbacks
################

# The server will call start_game on us. Crack open a new deck,
# shuffle it, and kick the players.
sub start_game {
  my $self = shift;
  my $game = Games::Cards::Game->new(
				     {cards_in_suit=>{
						      Ace=>1,
						      2=>2,
						      3=>3,
						      4=>4,
						      5=>5,
						      6=>6,
						      7=>7,
						      8=>50,
						      9=>9,
						      10=>10,
						      Jack=>10,
						      Queen=>10,
						      King=>10,
						     }
				     });
  # Set up all the different card-holding objects we'll need.
  $self->orig_deck(Games::Cards::Deck->new($game, 'deck'))->shuffle;
  $self->deck(Games::Cards::Stack->new($game, 'draw'));
  $self->orig_deck->give_cards($self->deck, 'all');
  $self->discard_pile(Games::Cards::Stack->new($game, 'discard'));

  # Tell the players that a new game has begun.
  foreach ($self->players) { $_->hand(Games::Cards::Hand->new($game, "$_")) }
  $self->call_ui_function_on_everyone('start_game');

  # Deal 'em out...
  $self->deal_cards;
  # Flip the starter.
  $self->flip_starter;
  # Announce the first player's turn.
  $self->call_ui_function_on_everyone(start_turn=>$self->current_player->nick);
  # Have the first player draw cards, maybe.
  $self->make_player_draw;
  # Now we sit back and let the first player make his or her move...
}

################
# Player Actions
################

sub rpc_play_card {
  my $self = shift;
  warn "In rpc_play_card.\n";
  my ($player, $card_name) = @_;
  unless ($player eq $self->current_player) {
    return(fault=>901, "It's not your turn!");
  }
  my $hand = $player->hand;
  my $card_index;
  eval { $card_index = $hand->index($card_name); };
  unless (defined($card_index)) {
    return(fault=>902, "You don't have that card ($card_name).");
  }
  my $card = $hand->cards->[$card_index];
  # We have a card... is it a legal play?
  if (
      ($card->name eq '8') or
      ($card->name eq $self->last_card->name) or
      (
       ($self->last_card->name ne '8') and
       ($card->suit eq $self->last_card->suit)
      )
      or
      (
       ($self->last_card->name eq '8') and
       ($card->suit eq $self->last_8_suit)
      )
     ) {
    # Yep. Move the card to to discard pile.
    $hand->give_a_card($self->discard_pile, $card_index);
    # Reset the declared suit.
    $self->last_8_suit(undef);
    # Announce the play to  the players.
    foreach ($self->players) { 
	$_->call_ui_function(player_played_card =>
			       $player->nick,
			       $card->name . $card->suit);
    }
  } else {
    return(fault=>907, "That's not a legal play!");
  }
  # Set the current player as the last card-player. This will help in case
  # the player later makes a 'change_suit()' call.
  $self->last_card_player($player);

  # See if the game is over.
  return if $self->check_for_game_over;

  # Move the turn along, unless an 8 was played. In that case,
  # we must wait for the player to choose a suit first.
  unless ($card->name eq '8') {
    $self->end_turn;
  }

  return;

}

sub rpc_choose_suit {
  my $self = shift;
  my ($player, $suit) = @_;
  unless ($player eq $self->current_player) {
    return(fault=>901, "It isn't your turn.");
  }
  unless (
	  (defined($self->last_card_player)) and
	  ($self->last_card->name eq '8') and
	  ($self->last_card_player eq $player)
	 ) {
    return(fault=>905, "You can't change the suit now!");
  }
  my $suit_letter = uc(substr($suit, 0, 1));
  if (grep($suit_letter eq $_, qw(D S H C))) {
    $self->call_ui_function_on_everyone(player_chose_suit=>$player->nick, $suit);
    $self->last_8_suit($suit_letter);
    $self->end_turn;
  } else {
    return(fault=>906, "I can't turn '$suit' into a recognizable suit name.");
  }
}

sub rpc_draw_card {
  my $self = shift;
  my ($player) = @_;
  unless ($player eq $self->current_player) {
    return(fault=>901, "It isn't your turn.");
  }
  unless (@{$self->deck->cards}) {
    return(fault=>904, "You can't draw a card; the draw pile has no cards left!");
  }
  my $drawn_card_name = $self->deck->top_card->name . $self->deck->top_card->suit;
  $self->deck->give_cards($player->hand, 1);
  # Tell the player about this new card.
  $player->call_ui_function(draw_card=>$drawn_card_name);
  # Tell the other players that the player drew a card.
  map($_->call_ui_function(player_drew_card=>$player->nick), grep($_ ne $player, $self->players));
}

################
# Internal Methods
################

sub deal_cards {
  my $self = shift;
  # Two-player games have seven-card hands; others get five-card hands.
  my $hand_size = scalar($self->players) == 2? 7: 5;
  for my $player ($self->players) {
    $self->deck->give_cards($player->hand, $hand_size);
    my @cardz = map($_->name . $_->suit, @{$player->hand->cards});
    $player->call_ui_function(receive_hand=>\@cardz);
  }
}

sub flip_starter {
  my $self = shift;
  $self->deck->give_cards($self->discard_pile, 1);
  my $starter_name = $self->discard_pile->top_card->name . $self->discard_pile->top_card->suit;
  $self->call_ui_function_on_everyone(starter_card=>$starter_name);
  # Semi-hack... if the starter is an 8, silently set our notion of
  # the last 8 suit. This keeps the logic in the match-checking part of
  # rpc_play_card simpler.
  $self->last_8_suit = $self->last_card->suit if $self->last_card->name eq '8';
}

sub last_card {
  my $self = shift;
  return $self->discard_pile->top_card;
}

sub end_turn {
  my $self = shift;
  $self->rotate_current_player;
  $self->call_ui_function_on_everyone(start_turn=>$self->current_player->nick);
  $self->make_player_draw;
}

# make_player_draw: Called at the start of a turn. Has the player draw
# cards from the deck until a play becomes possible. (This will draw
# no cards if the player starts the turn with legal plays already
# available.)
sub make_player_draw {
  my $self = shift;
  my $player = $self->current_player;
  my @hand_cards = @{$player->hand->cards};
  my $last_card = $self->last_card;
  my $last_value = $last_card->name;
  my $last_suit = defined($self->last_8_suit)?
      $self->last_8_suit : $last_card->suit;
  my $last_8_suit = $self->last_8_suit;
  until (
	 grep(
	      (
	       ($_->name eq 8) or
	       ($_->suit eq $last_suit) or
	       ($_->name eq $last_value)
	      ),
	      @hand_cards,
	     ) or
	 @{$self->deck->cards} == 0
	) {
      if (@{$self->deck->cards} == 0) {
	# Ye gods, the draw pile has run out. This player's turn is over.
	$self->call_ui_function_on_everyone(player_passes=>$player->nick);
	$self->end_turn;
      }
    my $drawn_card_name = $self->deck->top_card->name . $self->deck->top_card->suit;
    $self->deck->give_cards($player->hand, 1);
    @hand_cards = @{$player->hand->cards};
    $player->call_ui_function(draw_card=>$drawn_card_name);
    # Tell the other players that the player drew a card.
    map($_->call_ui_function(player_drew_card=>$player->nick), grep($_ ne $player, $self->players));
  }
}

sub check_for_game_over {
  my $self = shift;
  my $hand = $self->current_player->hand;
  unless ($hand->cards->[0]) {
    # The current player has no cards. Game over!
    # Sort the players into a Frivolity winner list.
    # Each member of this list is a listref, containing all the players
    # tied for that place. (This will often be just a single player, if
    # there are no actual ties for that place.)
    my %players_by_hand_value;
    my %scores_by_nickname;
    for my $player ($self->players) {
      my $hand_value = $player->evaluate_hand;
      $scores_by_nickname{$player->nick} = $hand_value;
      if ($players_by_hand_value{$hand_value}) {
	push (@{$players_by_hand_value{$hand_value}}, $player);
      } else {
	$players_by_hand_value{$hand_value} = [$player];
      }
    }
    my @winners;		# Sorted winner list!
    # We will add players to the winner list according to their hand values.
    # A simple sort by these values will give us the right order, since 
    # the fewer points, the better you did. (The first-place winner has zero
    # points!)
    foreach (sort(keys(%players_by_hand_value))) {
      push (@winners, $players_by_hand_value{$_});
    }

    # The the players about this.
    $self->call_ui_function_on_everyone(scores=>\%scores_by_nickname);
    
    # Set this array as my winner list, and signal that we're all done,
    # by calling the end_game() method.
    # The ref will take care of the rest!
    $self->winners(@winners);
    
    $self->end_game;
    return 1;
  } else {
    # Else, the player still holds cards, so the game ain't over yet...
    return 0;
  }
}
    
################
# Player Class
################

package Volity::Player::CrazyEights;

use warnings;
use strict;

use base qw(Volity::Player);
use fields qw(hand score);

# evaluate_hand: Return the game-over score of this player's hand.
sub evaluate_hand {
  my $self = shift;
  my $score = 0;
  my @cards = @{$self->hand->cards};
  for my $card (@cards) {
    $score += $card->value;
  }
  return $score;
}

1;
    

Presumably you'd want to add some POD documentation too, but this code listing is already long enough.