NAME

Volity::Referee - Class for in-MUC game overseers.

DESCRIPTION

An object of this class represents a Volity referee, the automated process that sits in a MUC along with the players, and arbitrates the game for them. See the general Volity documentation for a more detailed description of how this works.

In the Frivolity system, a Volity::Server object automatically makes a referee object and sends it to the appropriate MUC when a game starts. The class of referee it makes depends upon the value of the server object's referee_class instance variable, but most games can get away with using this default class, and putting all their game logic in a Volity::Game subclass.

USAGE

After being instanced, your Volity::Game subclass object will have a referee object as its referee instance variable, accessible through the referee() accessor.

In many cases, you can program your game module without ever directly referring to the referee. While this class does make many important methods available (such as seats()), they are transparently available from your game object as well. The referee simply sits in the background and takes care of all the Volity protocol-level stuff for you, letting you concentrate on making your game work.

METHODS

It's worth noting that this module subclasses from Volity::Jabber, and therefore enjoys all the methods that it defines, as well as the ones listed here.

Furthermore, all of these methods are also available with instances of Volity::Game and its subclasses; they transparently pass them up to their associated Volity::Referee objects, and pass back the return values. For your convenience, the method documentation below also appears in Volity::Game.

Object accessors

All these are simple accessors which return the named object attribute. If an argument is passed in, then the attribute's value is first set to that argument.

It is through these accessors that you perform most game configuration definition, such as the maximum number of players allowed per game.

This module inherits from Class::Accessor, so all the tips and tricks detailed in Class::Accessor apply here as well.

bookkeeper_jid

The JID of the network's bookkeeper. Initially set by the server, depending upon its own configuration.

muc_jid

The JID of the table's MUC. Set by various magic internal methods, so you should treat this as read-only; things will probably not work well if you reset this value yourself.

game_class

Important! The Perl class of the actual game (usually a subclass of Volity::Game).

You must set this on object construction though the new method's argument hash, as detailed in "Object construction" in Volity. Not doing so will result in an error.

game

The referee superclass already knows how and when to create a game object from the class specified by the game_class instance variable, and when it does so, it stores that object under game.

You should treat-this as a read-only variable. Generally, it will always be defined, as a referee creates a new game object as soon as it can. When a game ends, the object is destroyed a new one automatically takes its place.

Other Methods

startup_time

Returns the time (in seconds since the epoch) when this palor started.

last_activity_time

Returns the time (in seconds since the epoch) when this referee last handled a game.* RPC.

games_completed

Returns the number of games that have been begun and ended with this referee.

groupchat ( $message )

Sends the given message string as a groupchat to the referee's table.

JABBER EVENT HANDLING

Volity::Referee inherits from Volity::Jabber, and therefore uses all the same callback methods defined in "CALLBACK METHODS" in Volity::Jabber.

Don't be shy about overriding any handlers you wish, so long as you call the parent class's handler at some point so that any special Volity::Referee magic will be taken care of. This includes passing chat messages along to the contained game object or class (see "The Game Object").

AUTHOR

Jason McIntosh <jmac@jmac.org>

COPYRIGHT

Copyright (c) 2003-2006 by Jason McIntosh.