RCON

Send and receive remote console commands via RCON.

Overview

RCON allows you to send and receive console commands by interfacing with the server over a remote connection. RCON is secured using a password and a port (typically changed from the default 25575). RCON is dangerous because it allows you to execute commands with unrestricted privilege, such as if you were an operator on the server.

Workflow

1. const client = new util.RCON();

2. await client.connect(host, port);

3. await client.login('mypassword');

4. await client.run('time query daytime');

5. Wait for a response from the server

6. await client.close()

Examples

Multiple Responses

const util = require('minecraft-server-util');

const client = new util.RCON();

client.on('message', async (data) => {
    console.log(data);

    // Close the client whenever necessary. Make sure
    // that all responses have been read from the server
    // before closing to ensure they fire this event.
    await client.close();
});

const connectOpts = {
    timeout: 1000 * 5
    // ... any other connection options specified by
    // NetConnectOpts in the built-in `net` Node.js module
};

const loginOpts = {
    timeout: 1000 * 5
};

(async () => {
    await client.connect('localhost', 25575, connectOpts);
    await client.login('mypassword', loginOpts);
    await client.run('time query daytime');
})();

{ requestID: 1, message: 'The time is 4853' }

Single Response

const util = require('minecraft-server-util');

const client = new util.RCON();

const connectOpts = {
    timeout: 1000 * 5
    // ... any other connection options specified by
    // NetConnectOpts in the built-in `net` Node.js module
};

const loginOpts = {
    timeout: 1000 * 5
};

(async () => {
    await client.connect('localhost', 25575, connectOpts);
    await client.login('mypassword', loginOpts);
    
    const message = await client.execute('time query daytime');
    console.log(message);
    
    await client.close();
})();

'The time is 4853'

Methods

new util.RCON()

This method creates a new RCON client and returns its class. You will need to connect and login before you can start running commands.

const util = require('minecraft-server-util');

const client = new util.RCON();

// Connect
// Login
// Run command

client.connect()

Connects to the specified server using the host and port provided in the arguments.

const options = {
    timeout: 1000 * 5
    // ... any other connection options specified by
    // NetConnectOpts in the built-in `net` Node.js module
};

await client.connect('localhost', 25575, options);

client.login()

Logs into the server by using the password specified by the server. You will need to call client.connect() and wait for it to resolve before trying to log in.

await client.login('mypassword');

client.run()

This method will execute the command on the server and return without waiting for a response. This is typically used if the server sends more than one response for the specified command you are trying to run. You will need to connect then login before trying to run any commands. The return value is the request ID, an incremented counter for identifying what responses from the server are associated with the command request. You can use this request ID to identify what messages returning from the server are a response to this command.

const requestID = await client.run('time query daytime');

client.execute()

This method is the same as client.run(), except it will wait to return until it receives a message from the server about the output from the command. If the command you are running outputs more than one message, or you are missing some of the output, please use client.run() instead and use the client events to read all the messages.

const message = await client.execute('time query daytime');

console.log(message);

'The time is 4853'

client.close()

This will close the connection to the server. Make sure that you wait until you receive a response from the server for any queued executed commands before closing, as you will not receive them if closed before receiving the response.

await client.close();

Events

client.on('message')

This event is emitted whenever there is a message returned from the server after executing an RCON command. A single command may output multiple messages depending on the plugin or command used, so the first message received may not be the entire output.

client.on('message', (message) => {
    console.log(message);
});

{
    requestID: 1,
    message: 'Hello, world!' // the output of the command
}