volityd -- A daemon that runs a Volity parlor or bot factory
This is a program for running Volity servers, including parlors and bot fatcories. Run with valid configuration options, it acts a noninteractive daemon that either hosts a Volity game or makes available a bunch of bots for other Volity games to use.
You can run volityd with a configuration file, or by supplying a list of command-line options at runtime. You can also mix the two methods, in which case options you specify on the command line will override any of their counterparts in the config file. See "Config file format" for more about the config file.
Since there are many options, we recommend the use of a config file. The examples/ directory included with this distribution contains one config file for running a Tic Tac Toe parlor, and another that runs a Tic Tac Toe bot factory.
examples/
In the following documentation, each option has two names listed: its one-letter abbreviation followed by its long name. Either is usable on the command line, but the config file works with the only the long names.
For example, to set the Jabber ID that your server should use as foo@example.com, you can either supply -J foo@example.com or -jabber_id=foo@example.com on the command line, or the line jabber_id: foo@example.com in the config file.
foo@example.com
jabber_id: foo@example.com
An exception comes in how you define bots; see "Configuring bots".
The program will immediately die (with a specific complaint) if you don't specify enough information on the command line to allow the parlor or factory to authenticate with the Jabber server, or run a game module. Use an appropriate combination of the following flags to achieve this.
The hostname of the Jabber server that the parlor or factory will use.
If this is not defined but jid_host is, then this will be set to the value of jid_host.
jid_host
The hostname that the parlor or factory will use in its own Jabber ID.
By default, this will be the same as the value of host. You usually won't need to set this unless you are connecting to the jabber server via proxy, and the name of the host you are connecting to is different than the host part of your parlor or factory's intended JID.
host
The Jabber username that the parlor or factory will use when connecting.
The password that the parlor or factory will use when authenticating with the Jabber server.
If you supply this on the command line, volityd will automatically modify $0 so that it won't be exposed to process-listing commands like ps.
$0
The full Perl package name of the game module that the parlor or factory will run. It must be visible to @INC.
The parlor or factory's full Jabber ID. You can use this flag instead of using the username, jid_host and resource options. (But you can't use both this and them.)
username
resource
Bot factories only. If you are running a volityd process as a bot factory, then you must specify the URI of the Volity ruleset that you will provide bots for.
volityd
If you're running this program as a parlor, you don't need to specify this, since your Volity::Game subclass already should define its ruleset.
Volity::Game
Each of the following are optional. Not defining them at runtime will result in default behavior as described.
A comma-separated list of Jabber IDs that are allowed to send admin.* RPCs to this parlor or factory. All admin.* calls from Jabber IDs not on this list result in faults sent back to the caller.
Default: None.
The JabberID of the Volity network's bookkeeper.
Default: bookkeeper@volity.net/volity
The contact email address of the person responsible for this parlor or factory.
Polite servers set either this or the contact_jabber_id option (or both).
The filesystem pathname of the pidfile to be created when the server starts.
Default: None, and no pidfile is used.
A string containing Log::Log4perl configuration information, defining the behavior of the volityd logger. See Log::Log4perl. (A reference to this string is passed directly to that module's init() method.)
Log::Log4perl
init()
The logger works through various Log4perl invocations already spread throughout the Volity modules, set at appropriate priority levels, ranging from 'DEBUG' to 'INFO' to 'FATAL'.
The program will die with an error if you define both this option and log_config_file.
Default: None, and no logging occurs unless you specify a value for the log_config_file option.
The contact Jabber ID of the person responsible for this server.
Polite servers set either this or the contact_email option (or both).
contact_email
The hostname of the Jabber MUC server to use when creating new game tables.
Default: conference.volity.net
The Jabber server's TCP port.
Default: 5222 (the standard Jabber connection port)
The Jabber resource string that the server will use after authenticating. The string 'volity' (the default string) is a good choice for 'live' servers; use something like 'testing' otherwise.
Default: 'volity'
The version number of the Volity platform protocol that this server supports.
Unless you're doing something highly unusual with the Volity Perl libraries, you're probably best sticking with the default value on this one.
Default: 1.0
The path to a volityd config file. See "Config file format".
If you specify any command-line options beyond this one, they will override any config options specified in the file.
Default: None, and volityd will look for all options to come from the command line.
The filesystem pathname of a Log::Log4perl configuration file, which defines the behavior of the volityd logger. See Log::Log4perl. (The filename is passed directly to that module's init() method.)
The program will die with an error if you define both this option and log_config_info.
Default: None, and no logging occurs, unless you specify a value for the log_config_info option.
The role that this server will play on the Volity network. There are only two legal values for this option: parlor and factory.
parlor
factory
Default: parlor
Whether or not this server is visble to Volity's game finder. Set to 1 if it is, or 0 if it should go unlisted.
Default: 1
If you specify a config file via the -C or --config command-line options, then you must prepare a YAML file at that location. Its contents are simply a list of the options you want to set, with one option per line (but see "Configuring bots" for an exception). Each option is keyed by its long name. Here's a possible snippet:
username: foo host: volity.net password: secretpassword42 game: Volity::Game::MyFunGame
To specify a multiline value, set the value after the colon to | (a pipe character), followed by a newline, and then the value with every line indented, like so:
log_config_info: | [ line 1 of config info ] [ line 2 of config info ] [ ... ]
For more information about the YAML markup format, see YAML or http://yaml.org .
You can configure your server to know about Perl-based Volity bot classes (subclasses of Volity::Bot) that are installed on your machine. This is a requirement for bot factories (whose existence isn't very meaningful without them), and it's not required but recommended for parlors. A parlor that knows about local bot classes will make those bots available to its players without having to go through external bot factories.
Volity::Bot
You must specify several parameters for each bot class to use. These include the name of the bot's Perl class, a Jabber ID, and a password. (This latter is not necessary for bots whose basic Jabber ID matches that of your parlor.)
Because of the plurality of options involved, bot configuration from the command line works differently than from a config file.
The relevant command line options include:
bot_jid_host
bot_host
To define multiple bots, just invoke the flags multiple times. For example:
$ volityd -C some_config.yml -bot_class=Volity::Bot::MyFirstBot\ -bot_jabber_id=firstbot@volity.net\ -password=secretPASSword\ -bot_class=Volity::Bot::MyOtherBot\ -bot_jabber_id=secondbot@volity.net\ -password=SECRETpassWORD
From the config file, define instead a YAML sequence under the key "bots". Each member of the sequence is a YAML mapping with the following keys:
Here is an example config file snippet that performs the same bot configuration as above:
bots: - bot_class: Volity::Bot::MyFirstBot bot_jabber_id: firstbot@volity.net password: secretPASSword - bot_class: Volity::Bot::MyOtherBot bot_jabber_id: secondbot@volity.net password: SECRETpassWORD
The Volity developer site: http://volity.org
Volity
YAML
Jason McIntosh <jmac@jmac.org>
Copyright (c) 2006 by Jason McIntosh.
To install Volity, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Volity
CPAN shell
perl -MCPAN -e shell install Volity
For more information on module installation, please visit the detailed CPAN module installation guide.