NAME

Frivolity - A Perl implementation of the Volity game platform

DESCRIPTION

All the modules under the Volity namespace implement Frivolity, an implementation of the Volity Internet game system. The Volity module per se holds only a few utility methods (see "METHODS"). More interesting are its subclasses, which implement other key system components.

Modules of interest to game developers

If you are primarily interested in writing your own Volity games in Perl, then you really only need a deep understanding of the following modules.

Volity::Game

A framework library for creating Volity game modules. You can make your own Volity-ready game modules by subclassing Volity::Game.

Volity::Game is a great starting point for learning how to create your own Volity games with these libraries.

Volity::Seat

The base class for the entities that are actually playing a volity game. Each discrete, role-bearing entity at the game table -- "black" and "white" at Chess, or "North", "East", "West" and "South" at Bridge, for example --is represented by an object of this class.

Creation and destruction of seat objects is handled for you, but several methods of Volity::Game (and the subclasses you might make from it) return seat objects, so you should know how to work with them.

While the Volity::Seat base class is full-featured enough to use as-is, you have the option of subclassing Volity::Seat and configuring your game subclass to use it instead of the base class.

Volity::Player

A class that defines individual Volity users from a server-side perspective. Active seats contain players, and game observers -- that is, users at a table but not sitting down -- are also defined by this class.

As with seats, creation and destruction of player objects is handled for you, but several methods of both Volity::Game and Volity::Seat deal with objects of this class.

Volity::WinnersList

This small but important class defines an object that will help you create a bookkeeper-ready game record once each of your games is finished being played.

Volity::Bot

A framework library for creating bots, game-playing automatons that users can summon to a Volity table as artificial competition.

Writing bots is a recommended but not completely necessary part of creating a Volity game. Therefore, Volity::Bot should be your next step in the process of game creation with Frivolity once you've gotten your head around Volity::Game and the other modules listed above.

Modules of interest to deep-voodoo wizards

Should you wish to hack deeper into the system, there's plenty more to see. All of these modules are subclasses of Volity::Jabber.

Volity::Server

A "black-box" game server engine; tell it what game class to use (probably a subclass of Volity::Game), call start, and off you go.

The volityd program, which is distributed with these libraries, takes care of setting up and creating this object for you. See volityd.

Volity::Referee

A Volity referee is the entity that sits in a MUC (multi-user conference) with some players, and arbitrates the game being played therein.

In this implementation, the Volity::Referee object takes care of all referee activities common to all Volity games, and delegates game-specific logic to a Volity::Game subclass object that it contains. Developers using these modules can therefore put all their programming work into this subclass and generally leave the referee class alone.

Volity::Bookkeeper

Another black-box module, this time for running a Volity bookkeeper, which manages game records and the like by acting as a front-end to a database.

Unless you wish to run your own Volity network (as opposed to running your games as part of the worldwide Volity network centered around volity.net), you probably don't need to bother with this one.

Due to its separate dependencies, such as the need for a MySQL database, this module is distributed separately from the rest of Frivolity.

USAGE

Creating new Volity games

Perl hackers who wish to write Volity game modules can easily do so by creating an object class that inherits from Volity::Game, and optionally an automated opponent through a Volity::Bot subclass. See those modules' documentation for more information.

Running a Volity parlor

As with any Volity implementation, you don't need to host any Internet services of your own to host a game module; you simply need a valid login to a Jabber server somewhere. Frivolity includes a Perl program, volityd, that creates a Volity server for you, using a Volity::Game subclass that you provide it. See volityd for more information.

Fully hooking a parlor into a greater Volity network (such as volity.net) involves registering it with that network's bookkeeper. Refer to http://www.volity.org/wiki/index.cgi?Game_Developer's_Overview for information on registering with volity.net.

METHODS

The following object methods are available to instances of all the classes listed in "DESCRIPTION".

logger

Returns the object's attached Log::Log4perl object, which is automatically created and initialized as needed. This lets Volity subclasses easily add prioritized log and debug output to their code. See Log::Log4perl for documentation on this object's use.

You tell the volityd program about a Log4perl-style config file to use through its log_config config option. See volityd for details.

expire ($message)

A convenience method which calls the logger object's fatal method using the given $message, and then calls Carp:croak() with the same message.

SEE ALSO

The Volity developers' website at http://www.volity.org contains all sorts of resources for developers, including a documentation wiki, links to mailing lists, and client software downloads.

AUTHOR

Jason McIntosh <jmac@jmac.org>

Jabber ID: jmac@volity.net

COPYRIGHT

Copyright (c) 2003-2006 by Jason McIntosh.