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

Games-Multiplayer-Manager documentation Contained in the Games-Multiplayer-Manager distribution.

Index

Code Index:

NAME

Top

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

SYNOPSIS

Top

  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

Top

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

METHODS

Top

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

Top

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

Top

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

Top

Nothing else to see at the moment.

CHANGES

Top

  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

Top

Cerone Kirsle, <cerone@aichaos.com>

COPYRIGHT AND LICENSE

Top

  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
Games-Multiplayer-Manager documentation Contained in the Games-Multiplayer-Manager distribution. 
package Games::Multiplayer::Manager;

use strict;
use warnings;

our $VERSION = '1.01';

sub new {
	my $proto = shift;
	my $class = ref($proto) || $proto;

	my $self = {
		debug       => 0,
		'_games'    => {},
		'_handlers' => {},
		@_,
	};

	bless ($self,$class);

	return $self;
}

sub debug {
	my ($self,$msg) = @_;

	return unless $self->{debug};
	print "Games::Multiplayer::Manager::debug // $msg\n\n";

	return 1;
}

sub version {
	return $VERSION;
}

##########################################
## General Methods                      ##
##########################################

sub create {
	my $self = shift;
	my %in = @_;

	# Required data.
	my $id   = $in{id};
	my $name = $in{name};

	if (not defined $id) {
		$self->debug ("Error creating game: ID was not provided!");
		return 0;
	}
	if (not defined $name) {
		$self->debug ("Error creating game $id: Name was not provided!");
		return 0;
	}

	# Return 0 if the ID already exists.
	return 0 if exists $self->{_games}->{$id};

	# Create the game.
	$self->{_games}->{$id} = {
		'_players' => {},
		'name' => $in{name},
		@_,
	};

	# Return true.
	return 1;
}

sub destroy {
	my $self = shift;
	my %in = @_;

	# Required data.
	my $id = $in{id};

	# Return if the ID doesn't exist.
	if (!exists $self->{_games}->{$id}) {
		$self->debug ("Could not destroy $id: Doesn't exist!");
		return 0;
	}

	# Check the force and alert flags.
	my $force = $in{force} || 0;
	my $alert = $in{alert} || 1 unless $in{alert} == 0;
	my $msg   = $in{message} || "This game ($self->{_games}->{$id}->{name}) has been terminated.";

	# Array of players.
	my @count = keys %{$self->{_games}->{$id}->{_players}};

	# If not being forced...
	if ($force != 1) {
		# Only close if there are no players.
		if (scalar(@count) > 0) {
			$self->debug ("Could not destroy $id: Game isn't empty yet!");
			return 0;
		}
	}

	# If there were players, try and alert them.
	if (scalar(@count) > 0) {
		if ($alert == 1) {
			foreach my $player (@count) {
				# Broadcast to this player.
				$self->sendMessage (
					to      => $player,
					message => $msg,
				);
			}
		}
	}

	# Destroy the game.
	delete $self->{_games}->{$id};
	return 1;
}

sub setHandler {
	my $self = shift;
	my %in = @_;

	# Set these handlers.
	foreach my $key (keys %in) {
		$self->{_handlers}->{$key} = $in{$key};
	}

	return 1;
}

sub sendMessage {
	my $self = shift;

	# Send these to the broadcast handler.
	if (exists $self->{_handlers}->{broadcast}) {
		&{$self->{_handlers}->{broadcast}} (@_) || return 0;
	}

	return 1;
}

sub broadcast {
	my $self = shift;
	my $id = shift;
	my $msg = shift;

	return 0 unless exists $self->{_games}->{$id};

	# Send this to all users.
	foreach my $user (keys %{$self->{_games}->{$id}->{_players}}) {
		$self->sendMessage (
			to      => $user,
			message => $msg,
		);
	}

	return 1;
}

##########################################
## Game Methods                         ##
##########################################

sub queryGame {
	my $self = shift;
	my $id = shift;

	# See if this game exists.
	if (exists $self->{_games}->{$id}) {
		return 1;
	}

	return 0;
}

sub listGames {
	my $self = shift;

	# Get a list of all the games.
	my @list = keys %{$self->{_games}};

	return @list;
}

##########################################
## Player Methods                       ##
##########################################

sub addPlayer {
	my $self = shift;
	my $id = shift;
	my %in = @_;

	# Get specific data.
	my $name = $in{name};

	# Must be a name.
	if (length $name == 0) {
		$self->debug ("Could not add player to $id: Player name not defined!");
		return 0;
	}

	# This ID must exist.
	if (!exists $self->{_games}->{$id}) {
		$self->debug ("Could not add player to $id: Game doesn't exist!");
		return 0;
	}

	# Add them.
	$self->{_games}->{$id}->{_players}->{$name} = {
		id => $id,
		@_,
	};
	return 1;
}

sub dropPlayer {
	my $self = shift;
	my ($id,$name) = @_;

	# ID must exist.
	if (!exists $self->{_games}->{$id}) {
		$self->debug ("Could not drop player from $id: Game doesn't exist!");
		return 0;
	}

	# Name must exist.
	if (!exists $self->{_games}->{$id}->{_players}->{$name}) {
		$self->debug ("Could not drop player from $id: Name not defined!");
		return 0;
	}

	# Drop them.
	delete $self->{_games}->{$id}->{_players}->{$name};
	return 1;
}

sub findPlayer {
	my $self = shift;
	my $name = shift;

	# Find them.
	my @games = ();
	foreach my $game (keys %{$self->{_games}}) {
		foreach my $member (keys %{$self->{_games}->{$game}->{_players}}) {
			if ($member eq $name) {
				push (@games, $game);
			}
		}
	}

	# Return the array of game ID's.
	return @games;
}

sub queryPlayer {
	my $self = shift;
	my ($id,$name) = @_;

	# Return true if they exist.
	return 1 if exists $self->{_games}->{$id}->{_players}->{$name};
	return 0;
}

sub listPlayers {
	my $self = shift;
	my $id = shift;

	# ID must be defined.
	if (length $id == 0) {
		$self->debug ("Could not list players: ID not passed in!");
		return undef;
	}

	# ID must exist.
	if (!exists $self->{_games}->{$id}) {
		$self->debug ("Could not list players: Game $id doesn't exist!");
		return undef;
	}

	# Get the players.
	my @list = keys %{$self->{_games}->{$id}->{_players}};
	return @list;
}

1;
__END__