Author image Andrew A. Chen


  POE::Component::Client::Halo -- an implementation of the Halo query 


  use Data::Dumper; # for the sample below
  use POE qw(Component::Client::Halo);

  my $halo = new POE::Component::Client::Halo(
        Alias => 'halo',
        Timeout => 15,
        Retry => 2,

  $kernel->post('halo', 'info', '', 2302, 'pbhandler', 'ident');

  $kernel->post('halo', 'detail', '', 2302, 'pbhandler', 'ident');

  sub postback_handler {
      my ($ip, $port, $command, $identifier, $response) = @_;
      print "Halo query $command_executed on ";
      print " at $ip:$port";
      print " had a identifier of $identifier" if defined $identifier;
      print " returned from the server with:";
      print Dumper($response), "\n\n";


POE::Component::Client::Halo is an implementation of the Halo query protocol. It was reverse engineered with a sniffer and two cups of coffee. This is a preliminary release, based version of the dedicated server (the first public release). It is capable of handling multiple requests of different types in parallel.

PoCo::Client::Halo new can take a few parameters:

Alias => $alias_name

Alias sets the name of the Halo component with which you will post events to. By default, this is 'halo'.

Timeout => $timeout_in_seconds

Timeout specifies the number of seconds to wait for each step of the query procedure. The number of steps varies depending on the server being accessed.

Retry => $number_of_times_to_retry

Retry sets the number of times PoCo::Client::Halo should retry query requests. Since queries are UDP based, there is always the chance of your packets being dropped or lost. After the number of retries has been exceeded, an error is posted back to the session you specified to accept postbacks.


There are two methods that can be exported through the tag ':flags' -- halo_player_flag() and halo_game_flag(). They can be used to translate a specific game flag into its English equivalent.

  $english_value = halo_player_flag($flag_name, $flag_value);
  $english_value = halo_game_flag($flag_name, $flag_value);


You can send two types of events to PoCo::Client::Halo.


This will request the basic info block from the Halo server. In the postback, you will get 4 or 5 arguments, depending on whether or not you had a postback. ARG0 is the IP, ARG1 is the port, ARG3 is the command (for info queries, this will always be 'info'), ARG4 is a hashref with the returned data, and ARG5 is your unique identifier as set during your original post. Here are the fields you'll get back in ARG4:

  • Map

  • Teamplay

  • Classic

  • Mode

  • MaxPlayers

  • Hostname

  • Password

  • Version

  • Dedicated

  • Players


This request more detailed information about the server, as well as its rules, player information, and team score. Like 'info', you'll get 4-5 arguments passed to your postback function. ARG4 contains a HoHoH's: { 'Score' => { 'Red' => { 'team' => 'Red', 'score' => '17' }, 'Blue' => { 'team' => 'Blue', 'score' => '17' } }, 'Players' => { 'ZETA' => { 'score' => '0', 'team' => '0', 'ping' => '', 'player' => 'ZETA' }, 'badmofo' => { 'score' => '3', 'team' => '0', 'ping' => '', 'player' => 'badmofo' }, }, 'Rules' => { 'gametype' => 'Slayer', 'hostport' => '', 'fraglimit' => '50', 'mapname' => 'dangercanyon', 'gamever' => '', 'teamplay' => '1', 'password' => '0', 'game_flags' => '26', 'player_flags' => '1941966980,2', 'game_classic' => '0', 'gamevariant' => 'Team Slayer', 'gamemode' => 'openplaying', 'hostname' => 'DivoNetworks', 'maxplayers' => '16', 'dedicated' => '1', 'numplayers' => '2' } };

At the time of this module's release, ping information was not available within the info packets. They might be made public later on, so I left them in the response.

You can translate the player and game flags with the two methods mentioned above. Take a look at the sample program to see how it's done.


The errors listed below are ones that will be posted back to you in the 'response' field.

  • ERROR: Timed out waiting for response

    Even after retrying, there was no response to your request command.

  • There are other fatal errors that are handled with croak().


No tests are distributed with the module yet. There is a sample, though.


Rocco Caputo


Divo Networks

Thanks for loaning me servers to test against.

Brian Hurley

He decoded all the player and game flags after several long nights. Thanks.


POE::Component::Client::Halo is Copyright 2001-2003 by Andrew A. Chen <>. All rights are reserved. POE::Component::Client::Halo is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

6 POD Errors

The following errors were encountered while parsing the POD:

Around line 571:

You forgot a '=back' before '=head1'

Around line 582:

Expected '=item *'

Around line 588:

'=item' outside of any '=over'

Around line 592:

You forgot a '=back' before '=head1'

Around line 594:

'=item' outside of any '=over'

Around line 607:

You forgot a '=back' before '=head1'