view release on metacpan or  search on metacpan

lib/Net/RCON/Minecraft.pod  view on Meta::CPAN

The TCP port number to connect to.

=item password

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

=item timeout

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

=back

=head1 SENDING COMMANDS

=head2 command( $command )

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

Sends the C<$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 C<$response> can be treated like a plaintext
string. However, what you are really getting is L<overload> stringification of
a L<Net::RCON::Minecraft::Response> object, as some modded servers will return
Minecraft C<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 L<Net::RCON::Minecraft::Response> for I<slightly> more detail, but there
really isn't much to it. C<$response-E<gt>plain> will always return a scalar,
so may be slightly safer when dealing with other code that doesn't handle
overloaded objects well.

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

=head1 OTHER METHODS

=head2 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 C<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.

=head2 connect

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

However, you may explicitly call C<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 C<croak()> if the connection fails for any reason, and C<$@>
will be set. Otherwise, C<connect()> will return a true value.

=head2 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 C<connect()>) to
succeed, but C<command()> calls to fail.

=head2 disconnect

    $rcon->disconnect;

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

=head1 DIAGNOSTICS

=head2 Errors

This module C<croak()>s on error. You are advised to wrap all method calls,
especially C<connect()> and C<command()> in block C<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 C<croak()> on invalid inputs.

=head2 Warnings

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

=head1 SEE ALSO