Robot
/
node-gamedig
mirror of https://github.com/gamedig/node-gamedig.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
68 Commits 21 Branches 0 Tags 8.7 MiB
JavaScript 100%
Go to file
Michael Morrison e857eb1b47 Improve error handling on TCP 2014-02-02 05:32:02 -06:00
bin Misc tidying 2014-02-01 09:47:39 -06:00
games Improve error handling on TCP 2014-02-02 05:32:02 -06:00
lib Improve error handling on TCP 2014-02-02 05:32:02 -06:00
.gitignore Super mega-commit 2014-01-31 16:27:52 -06:00
LICENSE initial commit 2013-07-10 05:02:48 -05:00
README.md Explain what gamedig is in the readme 2014-02-01 20:10:52 -06:00
package.json bump version to 0.2.1 2014-02-01 20:05:23 -06:00

README.md

node-GameDig - Game Server Query Library

node-GameDig is a game server library, capable of querying for the status of nearly any game server. If has a node.js api, as well as a command line interface.

Usage from Node.js

npm install gamedig

var Gamedig = require('gamedig');
Gamedig.query(
	{
		type: 'minecraft',
		host: 'mc.example.com'
	},
	function(state) {
		if(state.error) console.log("Server is offline");
		else console.log(state);
	}
);

Input Parameters

  • type: One of the game IDs listed in the game list below
  • host
  • port: (optional) Uses the protocol default if not set
  • notes: (optional) Passed through to output

###Callback Function

The callback function is "guaranteed" to be called exactly once.

If an error occurs, the returned object will contain an "error" key, indicating the issue. If the error key exists, it should be assumed that the game server is offline or unreachable.

Otherwise, the returned object is guaranteed to contain the following keys:

Stable, always present:

  • name
  • map
  • password: Boolean
  • maxplayers
  • players: (array of objects) Each object may contain name, ping, score, team, address
  • bots: Same schema as players
  • notes: Passed through from the input

Unstable, not guaranteed:

  • raw: Contains all information received from the server
  • query: Details about the query performed

It can usually be assumed that the number of players online is equal to the length of the players array. Some servers may return an additional player count number, which may be present in the unstable raw object.

Supported Games

Don't see your game listed here?

  1. Let us know so we can fix it
  2. You can try using some common query protocols directly by using one of these server types:
  • protocol-ase
  • protocol-battlefield
  • protocol-doom3
  • protocol-gamespy1
  • protocol-gamespy2
  • protocol-gamespy3
  • protocol-nadeo
  • protocol-quake2
  • protocol-quake3
  • protocol-unreal2
  • protocol-valve
  • protocol-valvegold

Games with Additional Notes

Minecraft

Some minecraft servers may not respond to a typical status query. If this is the case, try using the 'minecraftping' server type instead, which uses a less accurate but more reliable solution.

Nadeo (ShootMania / TrackMania / etc)

The server must have xmlrpc enabled, and you must pass the xmlrpc port to GameDig, not the connection port. You must have a user account on the server with access level User or higher. Pass the login into to GameDig with the additional options: login, password

Terraria

Requires tshock server mod, and a REST user token, which can be passed to GameDig with the additional option: token

Separate Query Port

Games with this note use a query port which is usually not the same as the game's connection port. You must pass the query port to GameDig, not the connection port.

Usage from Command Line

Want to integrate server queries from a batch script or other programming language? You'll still need npm to install gamedig:

npm install gamedig -g

After installing gamedig globally, you can call gamedig via the command line using the same parameters mentioned in the API above:

gamedig --type minecraft --host mc.example.com --port 11234

The output of the command will be in JSON format.