The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Minecraft-RCON-1.010_04
River stage zero No dependents
1 ++
/ Minecraft::RCON

NAME

Minecraft::RCON - RCON remote console communication with Minecraft servers

VERSION

Version 1.010_01

SYNOPSIS

    use Minecraft::RCON;

    my $rcon = Minecraft::RCON->new( { password => 'secret' } );

    eval { $rcon->connect };
    die "Connection failed: $@" if $@;

    my $response;
    eval { $response = $rcon->command('help') };
    say $@ ? "Error: $@" : "Response: $response";

    $rcon->disconnect;

DESCRIPTION

Minecraft::RCON provides a nice object interface for talking to Mojang AB's game Minecraft. Intended for use with their multiplayer servers, specifically your multiplayer server, as you will need the correct RCON password, and RCON must be enabled on said server.

CONSTRUCTOR

new( %options )

Create a new RCON object. Note we do not connect automatically; see connect() for that. The properties and their defaults are shown below:

    my $rcon = Minecraft::RCON->new({
        address         => '127.0.0.1',
        port            => 25575,
        password        => '',
        color_mode      => 'strip',
        error_mode      => 'error',
    });

We will carp() but not die in the event that any unknown options are provided.

address

The hostname or IP address to connect to.

port

The TCP port number to connect to.

password

The plaintext password used to authenticate. This password must match the rcon.password= line in the server.properties file for your server.

color_mode

The color mode controls how Minecraft::RCON handles color codes sent back by the Minecraft server. It must be one of strip, convert, or ignore. constants. See color_mode() for more information.

METHODS

connect

    eval { $rcon->connect }; # $@ will be set on error

Attempt to connect to the configured address and port, and issue the configured password for authentication.

If already connected, returns undef (nothing to be done).

This method will croak if the connection fails for any reason. Otherwise, returns a true value.

connected

    say "We are connected!" if $rcon->connected;

Returns true if we have a connected socket, false otherwise. Note that we have no way to tell if there is a misbehaving Minecraft server on the other side of that socket, so it is entirely possible for this command (or connect()) to succeed, but command() calls to fail.

disconnect

    $rcon->disconnect;

Disconnects from the server by closing the socket. Always succeeds.

command( $command, [ $color_mode ] )

    my $response = $rcon->command("data get block $x $y $z");
    my $ansi = $rcon->command('list', 'convert');

Sends the $command to the Minecraft server, and synchronously waits for the response. This method is capable of handling fragmented responses (spread over several response packets), and will concatenate them all before returning the result.

The resulting server response will have its color codes stripped, converted, or ignored, according to the current color_mode() setting, unless a $color_mode is given, which will override the current setting for this command only.

color_mode( $color_mode, [ $code ] )

    $rcon->color_mode('strip');

When a command response is received, the color codes it contains can be stripped, converted to ANSI, or left alone, depending on this setting.

$color_mode is optional, unless $code is also specified. The valid modes are as follows:

strip

Strip any color codes, returning the plaintext.

convert

Convert any color codes to the equivalent ANSI escape sequences, suitable for display in a terminal.

ignore

Ignore color codes, returning the full command response verbatim.

The current mode will be returned.

If $code is specified and is a CODE ref, color_mode() will apply the new color mode, run $code->(), and then restore the original color mode. This is useful when you use one color mode most of the time, but have sections of code requiring a different mode:

Example usage:

    # Color mode is 'convert'
    $rcon->color_mode(strip => sub {
        my $plaintext = $rcon->command('...');
    });

But see also command($cmd, $mode) for running single commands with another color mode.

color_convert( $string, [ $color_mode ] )

    my $response = $rcon->command('list');
    my ($strip, $ansi) = map { $rcon->color_convert($response, $_) }
        qw<strip convert>;

This method is used internally by command() to convert command responses as configured in the object. However, color_convert() itself may be useful in some applications where a stripped version of the response may be needed for parsing, while an ANSI version may be desired for display to a terminal, for example, without having to run the command itself (with possible side-effects) a second time. For color_convert() to do anything meaningful, your object's color_mode should be set to ignore.

ERROR HANDLING

This module croaks (see Carp) for almost all errors. When an error does not affect control flow, we will carp instead.

Thus, command() and connect(), at minimum, should be wrapped in block eval:

    eval { $result = $rcon->command('list'); };
    warn "I don't know who is online because: $@" if $@;

If a little extra syntactic sugar is desired, you can use an exception handler like Try::Tiny instead:

    use Try::Tiny;

    try {
        $result = $rcon->command('list');
    } catch {
        warn "I don't know who is online because: $_";
    }

DEPRECATED METHODS

The following methods have been deprecated. They will issue a warning to STDOUT when called, and will be removed in a future release.

convert_color ( $enable )

If $enable is a true value, change the color mode to convert. Returns 1 if the current color mode is convert, undef otherwise.

Deprecated. Use color_mode('convert') instead.

strip_color

If $enable is a true value, change the color mode to strip. Returns 1 if the current color mode is strip, undef otherwise.

Deprecated. Use color_mode('strip') instead.

SEE ALSO

Terminal::ANSIColor, IO::Socket::INET
https://developer.valvesoftware.com/wiki/Source_RCON_Protocol
https://wiki.vg/RCON

AFFILIATION WITH MOJANG

Note from original author, Fredrik Vold:

I am in no way affiliated with Mojang or the development of Minecraft. I'm simply a fan of their work, and a server admin myself. I needed some RCON magic for my servers website, and there was no perl module.

It is important that everyone using this module understands that if Mojang changes the way RCON works, I won't be notified any sooner than anyone else, and I have no special avenue of connection with them.

AUTHORS

Ryan Thompson <rjt@cpan.org>

Addition of unit test suite, fragmentation support, and other improvements.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

http://dev.perl.org/licenses/artistic.html

Fredrik Vold <fredrik@webkonsept.com>

Original (0.1.x) author.

No copyright claimed, no rights reserved.

You are absolutely free to do as you wish with this code, but mentioning me in your comments or whatever would be nice.

Minecraft is a trademark of Mojang AB. Name used in accordance with my interpretation of http://www.minecraft.net/terms, to the best of my knowledge.