/node-gamequery

Gamequery is a Node.js library capable of querying for the status of nearly any game or voice server

Primary LanguageJavaScriptMIT LicenseMIT

Gamequery - Game Server Query Library TravisCI

Gamequery (formerly game-server-query) is a game server query library, capable of querying for the status of nearly any game or voice server. If a server makes its status publically available, Gamequery can fetch it for you.

Gamequery is available as a node.js module, as well as a command line executable.

Usage from Node.js

npm install gamequery

Promise:

var gamequery = require('gamequery');
gamequery.query({
	type: 'minecraft',
	host: 'mc.example.com'
}).then((state) => {
	console.log(state);
}).catch((error) => {
	console.log("Server is offline");
});

or Node.JS Callback:

var gamequery = require('gamequery');
gamequery.query({
	type: 'minecraft',
	host: 'mc.example.com'
},
function(e,state) {
	if(e) 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

Return Value

The returned state object will 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.

Games List

Supported

Not supported yet

  • rFactor Engine (rfactor):
  • rFactor
  • Arca Sim Racing
  • Cube Engine (cube):
  • Cube 1
  • Assault Cube
  • Cube 2: Sauerbraten
  • Blood Frontier
  • BFRIS
  • Call of Duty: Black Ops 1 and 2 (no documentation, may require rcon)
  • Counter-Strike 2D
  • Freelancer
  • Ghost Recon
  • GTR2
  • Haze
  • Hexen 2
  • Plain Sight
  • Red Faction
  • Savage: Battle for Newerth
  • Savage 2: A Tortured Soul
  • Sum of All Fears
  • Teeworlds
  • Tribes 1: Starsiege
  • Tribes 2
  • Vice City Multiplayer
  • World in Conflict

Other games

Want support for one of these games? Please open an issue to show your interest!

Don't see your game listed above?

First, let us know so we can fix it. Then, 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

Games with Additional Notes

Counter-Strike: Global Offensive

To receive a full player list response from CS:GO servers, the server must have set the cvar: host_players_show 2

DayZ

DayZ uses a query port that is separate from its main game port. The query port is usually the game port PLUS 24714 or 24715. You may need to pass this port in as the 'port_query' request option.

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.

Mumble

For full query results from Mumble, you must be running the GTmurmur plugin. If you do not wish to run the plugin, or do not require details such as channel and user lists, you can use the 'mumbleping' 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 gamequery, not the connection port. You must have a user account on the server with access level User or higher. Pass the login into to gamequery with the additional options: login, password

TeamSpeak 3

For teamspeak 3 queries to work correctly, the following permissions must be available for the guest server group:

  • Virtual Server
  • b_virtualserver_info_view
  • b_virtualserver_channel_list
  • b_virtualserver_client_list
  • Group
  • b_virtualserver_servergroup_list
  • b_virtualserver_channelgroup_list

Terraria

Requires tshock server mod, and a REST user token, which can be passed to gamequery 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. Usually, no action will be required from you. The 'port' option you pass gamequery should be the game's connection port. gamequery will attempt to calculate the query port automatically. If the query still fails, you may need to pass the 'port_query' option to gamequery as well, indicating the separate query 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 gamequery:

npm install gamequery -g

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

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

The output of the command will be in JSON format.