NAME

Games::Multiplayer::Manager - Perl extension for easy management of multiplayer games in interactive environments.

SYNOPSIS

  use Games::Multiplayer::Manager;

  # Create a new game manager.
  my $game = new Games::Multiplayer::Manager ();

  # Set up broadcast handler.
  $game->setHandler (broadcast => sub {
    my $self = shift;
    print "Got message for $self->{to}: $self->{message}\n\n";
  });

  # Create a new game.
  $game->create (
    id   => "tag",
    name => "The Game of Tag",
  );

  # Add a player.
  $game->addPlayer ("tag",
    host => "Perl",
    name => "foo",
  );

  # Drop that player.
  $game->dropPlayer ("tag", "foo");

  # Destroy the game.
  $game->destroy ("tag");

DESCRIPTION

Games::Multiplayer::Manager is a simple interface for creating and managing multiplayer games in interactive environments (for example, with IRC bots).

METHODS

new

Create a new game manager. This method should be called only once (a single manager object can manage as many games as you need). You can also pass in default variables (try to avoid any that begin with an underscore).

  my $manager = new Games::Multiplayer::Manager (debug => 1);

version

Returns the module's version.

  my $version = $manager->version;

create

Create a new game instance. Passed in are details on the game, which must include a unique identifier and a name (you can pass in any extra data if you want to, but not much else is used by the module itself).

This creates a new, empty game. To add players to it later, call the addPlayer method with the same ID that you created the game with.

This method will return 0 if there was an error (most likely the ID was already in use by another game).

  $manager->create (
    id   => "tag",
    name => "The Game of Tag",
  );

destroy

Destroy a game instance. Pass in arguments in hash form. The required element is the ID of the game to destroy. Optional arguments are "force" (boolean) to force any existing players out of the game. If that is true, another argument "alert" should be provided to define whether or not the players should be told about the game being terminated. You can also pass a "message" to be broadcasted to those players.

  $manager->destroy (
    id      => "tag",
    force   => 1,
    message => "Game terminated by an administrator.",
    alert   => 1,
  );

setHandler

Set a handler. Currently the only handler is for "broadcast" - your handler sub would receive a hash containing "to" and "message"

  $manager->setHandler (broadcast => \&broadcast);

sendMessage

Send a message to a single person. This method is usually called from within the module.

  $manager->sendMessage (to => "foo", message => "Hello!");

broadcast

Send a message to all players in a given Game ID.

  $manager->broadcast ("tag", "Soandso has been tagged!");

GAME METHODS

queryGame

Check a game's existence. Pass in the Game ID. This method will return 1 if the game exists, or 0 if it does not.

  my $exists = $manager->queryGame ("tag");

listGames

Returns an array of every Game ID that is currently in existence under this manager.

  my @games = $manager->listGames;

PLAYER METHODS

addPlayer

Add a player to an already created game. The first parameter is the Game ID, followed by a hash that must contain (at least) a unique name for the player.

  $manager->addPlayer ("tag",
    name => "foo",
  );

dropPlayer

Remove a player from a game. The game ID must exist, and a name must be defined.

  $manager->dropPlayer ("tag", "foo");

findPlayer

Searches every existing game for a certain player. This method returns an array of each Game ID that the player exists in.

  my @ids = $manager->findPlayer ("foo");

queryPlayer

Check a player's existence within a game. Returns true if they exist there.

  my $exists = $manager->queryPlayer ("tag", "foo");

listPlayers

Returns an array of players that exist in the passed in Game ID.

  my @players = $manager->listPlayers ("tag");

SEE ALSO

Nothing else to see at the moment.

CHANGES

  Version 1.01
  - Fixed a few bugs with arrays being returned by the module. It used to return "0"
    when the array would've been empty, causing $array[0] = 0. This has been fixed.
    empty arrays return empty now.
  - Revised the module page. The broadcast handler receives "to" and "message" as
    the hash keys, not "msg".
  - Fixed the test script; Makefile should install more smoothly now.

  Version 1.00
  - Initial release.

AUTHOR

Cerone Kirsle, <cerone@aichaos.com>

COPYRIGHT AND LICENSE

  Games::Multiplayer::Manager - Multiplayer game management for interactive environments.
  Copyright (C) 2005  Cerone Kirsle

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

cpanm Games::Multiplayer::Manager

perl -MCPAN -e shell
install Games::Multiplayer::Manager