Robot/node-gamedig
1
0
Fork 0
mirror of https://github.com/gamedig/node-gamedig.git synced 2024-11-17 17:25:19 +01:00
Code Issues Projects Releases Packages Wiki Activity
node-gamedig/README.md

22 KiB
Raw Blame History

node-GameDig - Game Server Query Library

node-GameDig 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, GameDig can fetch it for you.

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

Usage from Node.js

npm install gamedig

Promise:

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

or Node.JS Callback:

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

Is NPM out of date? If you're feeling lucky, you can install the latest code with

npm install sonicsnes/node-gamedig

Query Options

Typical

  • type: One of the game IDs listed in the game list below
  • host: Hostname or IP of the game server
  • port: (optional) Uses the protocol default if not set

Advanced

  • notes: (optional) An object passed through in the return value.
  • maxAttempts: (optional) Number of attempts to query server in case of failure. (default 1)
  • socketTimeout: (optional) Milliseconds to wait for a single packet. Beware that increasing this will cause many queries to take longer even if the server is online. (default 2000)
  • attemptTimeout: (optional) Milliseconds allowed for an entire query attempt. This timeout is not commonly hit, as the socketTimeout typically fires first. (default 10000)

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 2
  • Vice City Multiplayer
  • World in Conflict

Want support for one of these games? Please open an issue to show your interest! Know how to code? Protocols for most of the games above are documented in the /reference folder, ready for you to develop into GameDig!

Don't see your game listed here?

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.

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 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

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 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. Usually, no action will be required from you. The 'port' option you pass GameDig should be the game's connection port. GameDig will attempt to calculate the query port automatically. If the query still fails, you may need to find your server's query port, and pass that to GameDig instead.

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.

Changelog

2.0

Breaking changes
  • Node 8 is now required
  • Removed the port_query option. You can now pass either the server's game port or query port in the port option, and GameDig will automatically discover the proper port to query. Passing the query port is more likely be successful in unusual cases, as otherwise it must be automatically derived from the game port.
  • Removed callback parameter from Gamedig.query. Only promises are now supported. If you would like to continue using callbacks, you can use node's util.callbackify function to convert the method to callback format.
  • Removed query field from response object, as it was poorly documented and unstable.
Minor Changes
  • Rewrote core to use promises extensively for better error-handling. Async chains have been dramatically simplified by using async/await across the codebase, eliminating callback chains and the 'async' dependency.
  • Replaced --output pretty cli parameter with --pretty.
  • You can now query from CLI using shorthand syntax: gamedig --type <gameid> <ip>[:<port>]
  • UDP socket is only opened if needed by a query.
  • Automatic query port detection -- If provided with a non-standard port, gamedig will attempt to discover if it is a game port or query port by querying twice: once to the port provided, and once to the port including the game's query port offset (if available).
  • Simplified detection of BC2 when using battlefield protocol.
  • Fixed buildandshoot not reading player list
  • Added new connect field to the response object. This will typically include the game's ip:port (the port will reflect the server's game port, even if you passed in a query port in your request). For some games, this may be a server ID or connection url if an IP:Port is not appropriate.
  • Added new ping field (in milliseconds) to the response object. Since icmp packets are often blocked by NATs, and node has poor support for raw sockets, this time is derived from the rtt of one of the UDP requests, tcp socket connection, or http requests made during the query.

1.0

  • First official release
  • Node.js 6.0 is now required