/ 
Net-RCON-Minecraft-0.04
River stage zero No dependents
/ Net::RCON::Minecraft

NAME

Net::RCON::Minecraft - Minecraft RCON remote console

VERSION

Version 0.04

SYNOPSIS

use Net::RCON::Minecraft;

my $rcon = Net::RCON::Minecraft->new(password => 'secret',
                                         host => 'mc.example.com');

eval { $rcon->connect } or die "Connection failed: $@"; # Optional

my $response = eval { $rcon->command('kill @a') };
if ($@) {
    warn "Command failed: $@";
} else {
    say "Command response: " . $response;
}

DESCRIPTION

This module is a Minecraft-specific implementation of the RCON protocol, used to automate sending commands and receiving responses from a Minecraft server.

With a properly configured server, you can use this module to automate many tasks, and extend the functionality of your server without the need to mod the server itself.

MINECRAFT RCON BUG MC-72390

Bug MC-72390

Vanilla servers running versions older than Minecraft 1.14.3 have a bug in the RCON implementation that can cause server crashes. See the link above for details. RCON is not recommended on these older servers. If you are running modded Minecraft, your base (e.g., spigot, bukkit, etc.) may or may not have patched this issue. Check with them first.

If you are running vanilla 1.14.3 or greater, however, RCON should work just fine.

ENABLING RCON

Your Minecraft server must be configured to use RCON via the following options in the server.properties file in your Minecraft server's top level directory:

rcon.port=25575
rcon.password=secret
enable-rcon=true

Your Minecraft server will need to be restarted for these options to take effect.

A Note About Security

While the full security implications of enabling RCON are beyond the scope of this documentation, the most important consideration is that anyone who can connect to rcon.port and provide the rcon.password will have full, operator-level access to run arbitrary commands on your server.

If you do nothing else, please at least choose a secure, random password. Configuring access to rcon.port (TCP) in your firewall will ensure only permitted hosts can use RCON. Contact your network administrator.

CONSTRUCTOR

new( %options )

Creates a new RCON object with the given properties, but does not contact the server. The properties and their defaults are shown below:

my $rcon = Net::RCON::Minecraft->new(
    host            => 'localhost',
    port            => 25575,
    password        => '',
    timeout         => 30,
);
host

The hostname or IPv4/IPv6 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.

timeout

Specifies the timeout for all socket reads, in seconds. connect() and command() will wait this long before giving up.

SENDING COMMANDS

command( $command )

my $response = eval { $rcon->command("data get block $x $y $z") };

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.

For all intents and purposes $response can be treated like a plaintext string. However, what you are really getting is overload stringification of a Net::RCON::Minecraft::Response object, as some modded servers will return Minecraft U+00a7 color codes, and you will want to handle those:

$response->raw;   # Original. Minecraft color codes are left as-is
$response->plain; # Color codes stripped. The result is plain text
$response->ansi;  # Color codes converted to ANSI escape sequences

See Net::RCON::Minecraft::Response for slightly more detail, but there really isn't much to it. $response->plain will always return a scalar, so may be slightly safer when dealing with other code that doesn't handle overloaded objects well.

command() will croak() in the event of connection failure, no command given, or any unexpected protocol response from the server. command() does not know anything about Minecraft commands (or their responses) themselves, and this is by design.

OTHER METHODS

timeout( $seconds )

$s->timeout(3.5); # Timeout is now 3.5 seconds
printf "Our timeout is %.2f seconds\n", $s->timeout;

Set a new socket read timeout value. Takes effect immediately.

The new timeout will affect all network reads. If the server takes more than this many seconds to send all the bytes we are expecting, we will croak() with a timeout error message.

The default of 30 seconds is normally enough, but may need to be set higher if you are running a command that takes a long time, or the Minecraft server is very busy.

connect

This method is optional. By default, this module will connect to the Minecraft server automatically as soon as the first command() is run. It will stay connected unless there is an error, and will attempt to reconnect the next time command() is run.

However, you may explicitly call connect() if you need more granular control, and earlier error handling in the event of a failed connection:

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

The above attempts to connect to the configured host and port, and issues the configured password for authentication.

If already connected, does nothing but returns a true value.

This method will croak() if the connection fails for any reason, and $@ will be set. Otherwise, connect() will return a true value.

connected

In normal operation, you probably won't need to call this method.

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.

DIAGNOSTICS

Errors

This module croak()s on error. You are advised to wrap all method calls, especially connect() and command() in block eval, like so:

my $r = eval { $rcon->command($cmd_str) };
if ($@) {
    # Error occurred. Description of error is in $@
} else {
    # No errors. $r contains your command response.
}

Other methods will only croak() on invalid inputs.

Warnings

There are currently no warnings generated by this module. That may change in the future, and those warnings will be signaled via carp().

SEE ALSO

SUPPORT

AUTHOR

Ryan Thompson <rjt@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2020 Ryan Thompson

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