minecraft-server-admin

API for managing a minecraft server instance

node-minecraft-server-admin

This module aims to encapsulate the management of a minecraft server, including spinning up game instances, running backup/restore operations, getting/setting server.properties, white-list.txt, banned-*.txt, etc data, and more as time goes on.

npm install minecraft-server-admin

The export is a single constructor function:

var Server = require("minecraft-server-admin");

This module is very opinionated, and creates it's directory structure in a very particular way to encapsulate all server information into a single directory. (which is the dir supplied as the only argument to the Constructor function)

  • backups/ - All server backups will reside here
  • server/ - The minecraft server base dir will reside here (largely controlled by the minecraft server itself)
    • world/ - Usually, this is the server's world data (can be configured via server.properties)
    • minecraft_server.jar - This is a symbolic link pointing to a minecraft_server.jar somewhere else on disk.
    • banned-ips.txt - Banned IP addresses
    • banned-players.txt - Banned player usernames
    • white-list.txt - Server whitelist (must be enabled in server.properties)
    • opts.txt - Server operator list
    • server.properties - See the Minecraft Wiki
    • server.log - Server console/log output
  • config.json - This contains configuration details for the server that exist outside the server.properties and friends. (such as the java command, allowed RAM, etc)

The constructor requires a base directory as it's only parameter, this will be the root directory for all the server's data/configuration/etc.

Arguments

  • dir - The path to the server's location on disk

The absolute path location for this server, set by the Constructor (see above)

An instance of file-class.File (see file-class) pointing to server/server.log.

An instance of file-class.JSONFile (see file-class) pointing to config.json.

An instance of file-class.File (see file-class) (using parse/stringify methods from node-minecraft-server-properties) pointing to server/server.properties

An instance of file-class.ListFile (see file-class) pointing to server/white-list.txt.

An instance of file-class.ListFile (see file-class) pointing to server/ops.txt.

An instance of file-class.ListFile (see file-class) pointing to server/banned-ips.txt.

An instance of file-class.ListFile (see file-class) pointing to server/banned-players.txt.

An instance of dir-backup (see node-dir-backup) that sets up a backup system with the server/ dir as the source, and backups/ as the target.

This property is only set after a game has been started and begins to run successfully, it is an instance of the node-minecraft-runner object, and exposes that entire API via this property. (this includes execute server commands on the console, allows for listening to events that the server emits, etc)

This is a String property that returns the current status of the running game, or "Stopped" if no game is running.

This is the filesystem location of the server's jar file, not following the symbolic link. (ie: server/minecraft_server.jar)

This function returns the absolute path to a file within the server's directory.

Arguments

  • location - The relative location of the file

Returns String

This creates the entire directory structure for a server, additional data passed via arguments will be passed off to various other methods to creating configuration files (such as server.properties)

Arguments

  • options - Hash of data for server defaults
    • config - config.json data (ie: java, ram)
    • properties - server/server.properties data
    • whitelist - server/white-list.txt data
    • ops - server/ops.txt data
    • bannedPlayers - server/banned-players.txt data
    • bannedIps - server/banned-ips.txt data
    • jar - server/minecraft_server.jar source location
  • callback - Arguments provided:
    • err - Error object (if relevent)
var options = {
    properties: {
        // ... any excluded properties will likely be given defaults by the server 
        "white-list": true
    },
    ops: [ "the-op" ]
};
 
server.create(options, function (err) {
    // err => null or Error() 
});

This will destroy the entire directory structure for the server, if a game is currently running, it will stop that instance first.

Arguments

  • callback - Arguments provided:
    • err Error object (if relevent)

This will check for the existence of the server specified by this object.

Arguments

  • callback - Arguments provided:
    • exists - Boolean indicating the existence of the server's root dir

This method is short-hand for reading both banned-ips.txt and banned-players.txt.

Arguments

  • callback - Arguments provided:
    • err - Error object (if relevent)
    • banned - Object of banned players/ips

This method destroys the world data. (ie: the dir specified by the level-name property in server.properties) This is a nice way to give your world a clean slate without needing to reconfigure the entire server.

Arguments

  • callback - Arguments provided:
    • err - Error object (if relevent)

This method creates a symbolic link at server/minecraft_server.jar pointing to the location specified.

Arguments

  • location - The absolute path to a valid minecraft_server.jar file
  • callback - Arguments provided:
    • err - Error object (if relevent)

This method downloads the file located at the specified url via HTTP to server/minecraft_server.jar.

Arguments

  • url - The url pointing to a valid minecraft_server.jar
  • callback - Arguments provided:
    • err - Error object (if relevent)

This method will start the server instance, when the server has started properly, it will set the Server#game property with the node-minecraft-runner instance object.

Arguments

  • callback - Arguments provided:
    • err - Error object (if relevent)

This method will stop the server instance, once the server stops/exits, the Server#game property will be deleted.

Arguments

  • callback - Arguments provided:
    • err - Error object (if relevent)

This is short-hand for stopping and starting the server, any errors encountered by either will be passed to the callback.

Arguments

  • callback - Arguments provided:
    • err - Error object (if relevent)

This method handles running a backup for the server's server/ directory. (to exclude the backups themselves from being part of the backup) This method also handles the necessary steps to take if the server is actively running, such as broadcasting a message to the current users, forcing the server to flush data to disk, etc.

Arguments

  • callback - Arguments provided:
    • err - Error object (if relevent)
    • timestamp - Date reflecting the time of the backup itself

This method restores a server from a previously-run backup. Unlike Server#backup(), it cannot be run while the server is still actively running.

Arguments

  • callback - Arguments provided:
    • err - Error object (if relevent)