Noncommital Premarital Mischief

    exaroton

    1.7.0 • Public • Published

    Node.js exaroton API client

    About

    The exaroton API allows automated access to some basic functionalities of your game servers, such as starting or stopping the server. You can read the API documentation here: https://developers.exaroton.com

    This is the official Node.js implementation of this API.

    Installation

    npm install exaroton
    

    Usage

    To use the API and this client you have to get your API key, which you can generate in your exaroton account settings: https://exaroton.com/account

    Create a client object

    const {Client} = require('exaroton');
    
    const client = new Client(token);

    Remember to keep your token secret and don't add it to any private or public code repositories.

    REST API

    Get account info

    let account = await client.getAccount();
    console.log("My account is " + account.name + " and I have " + account.credits + " credits.");

    The account object contains the fields and information as listed in the documentation.

    List servers

    let servers = await client.getServers();
    
    for(let server of servers) {
        console.log(server.name + ": " + server.id);
    }

    Each server object contains the fields and information as listed in the documentation.

    Create a server object by ID

    let server = client.server(id);

    Get server information

    await server.get();
    console.log(server.name + ": " + server.id);

    Get/check the server status

    console.log(server.status);
    
    if (server.hasStatus(server.STATUS.ONLINE)) {
        console.log("Server is online.");
    } else if (server.hasStatus([server.STATUS.PREPARING, server.STATUS.LOADING, server.STATUS.STARTING])) {
        console.log("Server is online soon.");
    } else {
        console.log("Server is offline.");
    }

    The server status is an integer as described in the documentation. You can use the ServerStatus object, which you can require on its own const {ServerStatus} = require('exaroton') or via the shorthand server.STATUS property.

    Start/stop/restart the server

    try {
        await server.start();
        await server.stop();
        await server.restart();
    } catch (e) {
        console.error(e.message);
    }

    It's important to catch errors, because incorrect calls, e.g. a server.stop() when the server is offline will result in an error.

    Execute a server command

    try {
        await server.executeCommand("say Hello world!");
    } catch (e) {
        console.error(e.message);
    }

    Get the server logs

    try {
        let logs = await server.getLogs();
        console.log(logs);
    } catch (e) {
        console.error(e.message);
    }

    This is cached and will not return the latest updates immediately. It's also not possible to get the server logs while the server is loading, stopping or saving.

    Share the server logs via mclo.gs

    try {
        let url = await server.shareLogs();
        console.log(url);
    } catch (e) {
        console.error(e.message);
    }

    This is cached and will not return the latest updates immediately. It's also not possible to share the server logs while the server is loading, stopping or saving.

    Get the server RAM

    try {
        let ram = await server.getRAM();
        console.log("This server has " + ram + " GB RAM.");
    } catch (e) {
        console.error(e.message);
    }

    The amount of RAM is returned in full GiB.

    Set the server RAM

    try {
        await server.setRAM(8);
    } catch (e) {
        console.error(e.message);
    }

    The RAM is set in full GiB and has to be between 2 and 16.

    Get the server MOTD

    try {
        let motd = await server.getMOTD();
        console.log(motd);
    } catch (e) {
        console.error(e.message);
    }

    Set the server MOTD

    try {
        await server.setMOTD("Hello world!");
    } catch (e) {
        console.error(e.message);
    }

    Player lists

    A player list is a list of players such as the whitelist, ops or bans. Player list entries are usually usernames, but might be something else, e.g. IPs in the banned-ips list. All player list operations are storage operations that might take a while, so try to reduce the amount of requests and combine actions when possible (e.g. adding/deleting multiple entries at once). Player lists are also cached any might not immediately return new results when changed through other methods e.g. in-game.

    Get a player list object

    You can list all available player lists...

    try {
        let lists = await server.getPlayerLists();
        console.log(lists);
    } catch (e) {
        console.error(e.message);
    }

    ... or if you already know the name (e.g. "whitelist") you can directly create a player list object:

    try {
        let list = server.getPlayerList("whitelist");
        console.log(list);
    } catch (e) {
        console.error(e.message);
    }
    Get all player list entries
    try {
        let list = server.getPlayerList("whitelist");
        let entries = await list.getEntries();
        console.log(entries);
    } catch (e) {
        console.error(e.message);
    }
    Add player list entries

    We handle all the heavy work of adding player list entries for you, e.g. automatically adding UUIDs depending on the online mode or executing the necessary commands while the server is running.

    try {
        let list = server.getPlayerList("whitelist");
        await list.addEntry("Steve"); // add just one entry
        await list.addEntries(["Steve", "Alex"]); // add multiple entries at once
        console.log(await list.getEntries());
    } catch (e) {
        console.error(e.message);
    }
    Delete player list entries
    try {
        let list = server.getPlayerList("whitelist");
        await list.deleteEntry("Steve"); // delete just one entry
        await list.deleteEntries(["Steve", "Alex"]); // delete multiple entries at once
        console.log(await list.getEntries());
    } catch (e) {
        console.error(e.message);
    }

    Websocket API

    The websocket API allows a constant connection to our websocket service to receive events in real time without polling (e.g. trying to get the server status every few seconds).

    Server status events

    You can simply connect to the websocket API for a server by running the subscribe() function.

    server.subscribe();

    By default, you are always subscribed to server status update events, you can react to server status changes by adding a listener:

    server.subscribe();
    server.on("status", function(server) {
        console.log(server.status);
    });

    This event is not only triggered when the status itself changes but also when other events happen, e.g. a player joins the server.

    Console

    There are several optional streams that you can subscribe to, e.g. the console.

    server.subscribe("console");

    The console stream emits an event for every new console line.

    server.subscribe("console");
    server.on("console:line", function(data) {
        console.log(data.line);
    });

    The data.line property is already cleaned up for easier use in this client library, you can use data.rawLine if you want the raw data with all formatting codes etc.

    The console stream also allows you to send commands directly over the websocket. This is faster because the connection is already established and no further authorization etc. is necessary. This library already checks if you are subscribed to the console stream and sends the command through that stream instead, so you can just use it the same way as before:

    try {
        await server.executeCommand("say Hello world!");
    } catch (e) {
        console.error(e.message);
    }

    Tick times

    On Minecraft Java edition servers with version 1.16 and higher it is possible to get the tick times, and the TPS (ticks per second) of your server. This information is also available as an optional stream.

    server.subscribe("tick");
    server.on("tick:tick", function(data) {
        console.log("Tick time: " + data.averageTickTime + "ms");
        console.log("TPS: " + data.tps);
    });

    RAM usage

    There are two different optional streams to get RAM usage, the general stats stream and the Java specific heap stream. It is recommended to use the heap stream if you are running a server software that is based on Java. It is not recommended using both.

    You can subscribe to multiple streams at once by passing an array to the subscribe function.

    server.subscribe(["stats", "heap"]);
    server.on("stats:stats", function(data) {
        console.log(data.memory.usage);
    });
    server.on("heap:heap", function(data) {
        console.log(data.usage);
    });

    Unsubscribe

    You can unsubscribe from one, multiple or all streams using the server.unsubscribe() function.

    server.unsubscribe("console");
    server.unsubscribe(["tick", "heap"]);
    server.unsubscribe(); // this disconnects the websocket connection

    Keywords

    none

    Install

    npm i exaroton

    Homepage

    exaroton.com

    DownloadsWeekly Downloads

    6

    Version

    1.7.0

    License

    MIT

    Unpacked Size

    52.1 kB

    Total Files

    41

    Last publish

    Collaborators

    • exaroton