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.
npm install gamedig
const Gamedig = require('gamedig');
Gamedig.query({
type: 'minecraft',
host: 'mc.example.com'
}).then((state) => {
console.log(state);
}).catch((error) => {
console.log("Server is offline");
});
Typical
- type: string - One of the game IDs listed in the game list below
- host: string - Hostname or IP of the game server
- port: number (optional) - Connection port or query port for the game server. Some games utilize a separate "query" port. If specifying the game port does not seem to work as expected, passing in this query port may work instead. (defaults to protocol default port)
Advanced
- maxAttempts: number - Number of attempts to query server in case of failure. (default 1)
- socketTimeout: number - 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: number - Milliseconds allowed for an entire query attempt. This timeout is not commonly hit, as the socketTimeout typically fires first. (default 10000)
- debug: boolean - Enables massive amounts of debug logging to stdout. (default false)
The returned state object will contain the following keys:
- name: string - Server name
- map: string - Current server game map
- password: boolean - If a password is required
- maxplayers: number
- players: array of objects
- Each object may or may not contain name, ping, score, team, address.
- The number of players online can be determined by
players.length
. - For servers which do not provide player names, this may be an array
of empty objects (ex.
[{},{},{}]
), one for each player without a name.
- bots: array of objects - Same schema as
players
- connect: string
- This will typically include the game's
ip:port
- The port will reflect the server's game port, even if your request specified the game's query port in the request.
- For some games, this may be a server ID or connection url if an IP:Port is not appropriate for end-users.
- This will typically include the game's
- ping: number
- Round trip time to the server (in milliseconds).
- Note that this is not the RTT of an ICMP echo, as ICMP packets are often blocked by NATs and node has poor support for raw sockets.
- This value is derived from the RTT of one of the query packets, which is usually quite accurate, but may add a bit due to server lag.
- raw: freeform object (unstable)
- Contains all information received from the server in a disorganized format.
- The content of this field MAY change on a per-protocol basis between GameDig patch releases (although not typical).
GameDig Type ID | Name | Notes |
---|---|---|
7d2d |
7 Days to Die (2013) | |
ageofchivalry |
Age of Chivalry (2007) | |
aoe2 |
Age of Empires 2 (1999) | |
alienarena |
Alien Arena (2004) | |
alienswarm |
Alien Swarm (2010) | |
avp2 |
Aliens versus Predator 2 (2001) | |
avp2010 |
Aliens vs. Predator (2010) | |
americasarmy |
America's Army (2002) | |
americasarmy2 |
America's Army 2 (2003) | |
americasarmy3 |
America's Army 3 (2009) | |
americasarmypg |
America's Army: Proving Grounds (2015) | |
arcasimracing |
Arca Sim Racing (2008) | |
arkse |
Ark: Survival Evolved (2017) | |
arma2 |
ARMA 2 (2009) | |
arma2oa |
ARMA 2: Operation Arrowhead (2010) | |
arma3 |
ARMA 3 (2013) | |
arma |
ARMA: Armed Assault (2007) | |
armacwa |
ARMA: Cold War Assault (2011) | |
armar |
ARMA: Resistance (2011) | |
armagetron |
Armagetron Advanced (2001) | |
assettocorsa |
Assetto Corsa (2014) | |
atlas |
Atlas (2018) | |
baldursgate |
Baldur's Gate (1998) | |
bat1944 |
Battalion 1944 (2018) | |
bf1942 |
Battlefield 1942 (2002) | |
bf2 |
Battlefield 2 (2005) | |
bf2142 |
Battlefield 2142 (2006) | |
bf3 |
Battlefield 3 (2011) | |
bf4 |
Battlefield 4 (2013) | |
bfh |
Battlefield Hardline (2015) | |
bfv |
Battlefield Vietnam (2004) | |
bfbc2 |
Battlefield: Bad Company 2 (2010) | |
breach |
Breach (2011) | |
breed |
Breed (2004) | |
brink |
Brink (2011) | |
buildandshoot |
Build and Shoot / Ace of Spades Classic (2012) | |
cod |
Call of Duty (2003) | |
cod2 |
Call of Duty 2 (2005) | |
cod3 |
Call of Duty 3 (2006) | |
cod4 |
Call of Duty 4: Modern Warfare (2007) | |
codmw2 |
Call of Duty: Modern Warfare 2 (2009) | |
codmw3 |
Call of Duty: Modern Warfare 3 (2011) | |
coduo |
Call of Duty: United Offensive (2004) | |
codwaw |
Call of Duty: World at War (2008) | |
callofjuarez |
Call of Juarez (2006) | |
chaser |
Chaser (2003) | |
chrome |
Chrome (2003) | |
codenameeagle |
Codename Eagle (2000) | |
cacrenegade |
Command and Conquer: Renegade (2002) | |
commandos3 |
Commandos 3: Destination Berlin (2003) | |
conanexiles |
Conan Exiles (2018) | |
contagion |
Contagion (2011) | |
contactjack |
Contract J.A.C.K. (2003) | |
cs15 |
Counter-Strike 1.5 (2002) | |
cs16 |
Counter-Strike 1.6 (2003) | |
cs2d |
Counter-Strike: 2D (2004) | |
cscz |
Counter-Strike: Condition Zero (2004) | |
csgo |
Counter-Strike: Global Offensive (2012) | Notes |
css |
Counter-Strike: Source (2004) | |
crossracing |
Cross Racing Championship Extreme 2005 (2005) | |
crysis |
Crysis (2007) | |
crysis2 |
Crysis 2 (2011) | |
crysiswars |
Crysis Wars (2008) | |
daikatana |
Daikatana (2000) | |
dnl |
Dark and Light (2017) | |
dmomam |
Dark Messiah of Might and Magic (2006) | |
darkesthour |
Darkest Hour: Europe '44-'45 (2008) | |
dod |
Day of Defeat (2003) | |
dods |
Day of Defeat: Source (2005) | |
doi |
Day of Infamy (2017) | |
daysofwar |
Days of War (2017) | |
dayz |
DayZ (2018) | |
dayzmod |
DayZ Mod (2013) | |
deadlydozenpt |
Deadly Dozen: Pacific Theater (2002) | |
dh2005 |
Deer Hunter 2005 (2004) | |
descent3 |
Descent 3 (1999) | |
deusex |
Deus Ex (2000) | |
devastation |
Devastation (2003) | |
dinodday |
Dino D-Day (2011) | |
dirttrackracing2 |
Dirt Track Racing 2 (2002) | |
doom3 |
Doom 3 (2004) | |
dota2 |
Dota 2 (2013) | |
drakan |
Drakan: Order of the Flame (1999) | |
empyrion |
Empyrion - Galactic Survival (2015) | |
etqw |
Enemy Territory: Quake Wars (2007) | |
fear |
F.E.A.R. (2005) | |
f1c9902 |
F1 Challenge '99-'02 (2002) | |
farcry |
Far Cry (2004) | |
farcry2 |
Far Cry 2 (2008) | |
f12002 |
Formula One 2002 (2002) | |
fortressforever |
Fortress Forever (2007) | |
ffow |
Frontlines: Fuel of War (2008) | |
garrysmod |
Garry's Mod (2004) | |
geneshift mutantfactions |
Geneshift (2017) | |
giantscitizenkabuto |
Giants: Citizen Kabuto (2000) | |
globaloperations |
Global Operations (2002) | |
ges |
GoldenEye: Source (2010) | |
gore |
Gore: Ultimate Soldier (2002) | |
fivem |
Grand Theft Auto V - FiveM (2013) | |
mtasa |
Grand Theft Auto: San Andreas - Multi Theft Auto (2004) | |
mtavc |
Grand Theft Auto: Vice City - Multi Theft Auto (2002) | |
gunmanchronicles |
Gunman Chronicles (2000) | |
hl2dm |
Half-Life 2: Deathmatch (2004) | |
hldm |
Half-Life Deathmatch (1998) | |
hldms |
Half-Life Deathmatch: Source (2005) | |
halo |
Halo (2003) | |
halo2 |
Halo 2 (2007) | |
hll |
Hell Let Loose | |
heretic2 |
Heretic II (1998) | |
hexen2 |
Hexen II (1997) | |
had2 |
Hidden & Dangerous 2 (2003) | |
homefront |
Homefront (2011) | |
homeworld2 |
Homeworld 2 (2003) | |
hurtworld |
Hurtworld (2015) | |
igi2 |
I.G.I.-2: Covert Strike (2003) | |
il2 |
IL-2 Sturmovik (2001) | |
insurgency |
Insurgency (2014) | |
insurgencysandstorm |
Insurgency: Sandstorm (2018) | |
ironstorm |
Iron Storm (2002) | |
jamesbondnightfire |
James Bond 007: Nightfire (2002) | |
jc2mp |
Just Cause 2 - Multiplayer (2010) | |
jc3mp |
Just Cause 3 - Multiplayer (2017) | |
kspdmp |
Kerbal Space Program - DMP Multiplayer (2015) | |
killingfloor |
Killing Floor (2009) | |
killingfloor2 |
Killing Floor 2 (2016) | |
kingpin |
Kingpin: Life of Crime (1999) | |
kisspc |
Kiss: Psycho Circus: The Nightmare Child (2000) | |
kzmod |
Kreedz Climbing (2017) | |
left4dead |
Left 4 Dead (2008) | |
left4dead2 |
Left 4 Dead 2 (2009) | |
m2mp |
Mafia II - Multiplayer (2010) | |
m2o |
Mafia II - Online (2010) | |
moh2010 |
Medal of Honor (2010) | |
mohab |
Medal of Honor: Airborne (2007) | |
mohaa |
Medal of Honor: Allied Assault (2002) | |
mohbt |
Medal of Honor: Allied Assault Breakthrough (2003) | |
mohsh |
Medal of Honor: Allied Assault Spearhead (2002) | |
mohpa |
Medal of Honor: Pacific Assault (2004) | |
mohwf |
Medal of Honor: Warfighter (2012) | |
medievalengineers |
Medieval Engineers (2015) | |
minecraft minecraftping |
Minecraft (2009) | |
minecraftpe minecraftbe |
Minecraft: Bedrock Edition (2011) | |
mnc |
Monday Night Combat (2011) | |
mordhau |
Mordhau (2019) | |
mumble |
Mumble - GTmurmur Plugin (2005) | Notes |
mumbleping |
Mumble - Lightweight (2005) | Notes |
nascarthunder2004 |
NASCAR Thunder 2004 (2003) | |
ns |
Natural Selection (2002) | |
ns2 |
Natural Selection 2 (2012) | |
nfshp2 |
Need for Speed: Hot Pursuit 2 (2002) | |
nab |
Nerf Arena Blast (1999) | |
netpanzer |
netPanzer (2002) | |
nwn |
Neverwinter Nights (2002) | |
nwn2 |
Neverwinter Nights 2 (2006) | |
nexuiz |
Nexuiz (2005) | |
nitrofamily |
Nitro Family (2004) | |
nmrih |
No More Room in Hell (2011) | |
nolf2 |
No One Lives Forever 2: A Spy in H.A.R.M.'s Way (2002) | |
nucleardawn |
Nuclear Dawn (2011) | |
openarena |
OpenArena (2005) | |
openttd |
OpenTTD (2004) | |
operationflashpoint flashpoint |
Operation Flashpoint: Cold War Crisis (2001) | |
flashpointresistance |
Operation Flashpoint: Resistance (2002) | |
painkiller |
Painkiller | |
pixark |
PixARK (2018) | |
postal2 |
Postal 2 | |
prey |
Prey | |
primalcarnage |
Primal Carnage: Extinction | |
prbf2 |
Project Reality: Battlefield 2 (2005) | |
quake1 |
Quake 1: QuakeWorld (1996) | |
quake2 |
Quake 2 (1997) | |
quake3 |
Quake 3: Arena (1999) | |
quake4 |
Quake 4 (2005) | |
quakelive |
Quake Live (2010) | |
ragdollkungfu |
Rag Doll Kung Fu | |
r6 |
Rainbow Six | |
r6roguespear |
Rainbow Six 2: Rogue Spear | |
r6ravenshield |
Rainbow Six 3: Raven Shield | |
rallisportchallenge |
RalliSport Challenge | |
rallymasters |
Rally Masters | |
redorchestra |
Red Orchestra | |
redorchestra2 |
Red Orchestra 2 | |
redorchestraost |
Red Orchestra: Ostfront 41-45 | |
redline |
Redline | |
rtcw |
Return to Castle Wolfenstein | |
rfactor |
rFactor | |
ricochet |
Ricochet | |
riseofnations |
Rise of Nations | |
rs2 |
Rising Storm 2: Vietnam | |
rune |
Rune | |
rust |
Rust | |
stalker |
S.T.A.L.K.E.R. | |
samp |
San Andreas Multiplayer | |
ss |
Serious Sam | |
ss2 |
Serious Sam 2 | |
shatteredhorizon |
Shattered Horizon | |
shogo |
Shogo | |
shootmania |
Shootmania | Notes |
sin |
SiN | |
sinep |
SiN Episodes | |
soldat |
Soldat | |
sof |
Soldier of Fortune | |
sof2 |
Soldier of Fortune 2 | |
spaceengineers |
Space Engineers | |
squad |
Squad | |
stbc |
Star Trek: Bridge Commander | |
stvef |
Star Trek: Voyager - Elite Force | |
stvef2 |
Star Trek: Voyager - Elite Force 2 | |
swjk2 |
Star Wars Jedi Knight II: Jedi Outcast (2002) | |
swjk |
Star Wars Jedi Knight: Jedi Academy (2003) | |
swbf |
Star Wars: Battlefront | |
swbf2 |
Star Wars: Battlefront 2 | |
swrc |
Star Wars: Republic Commando | |
starbound |
Starbound | |
starmade |
StarMade | |
starsiege |
Starsiege (2009) | |
suicidesurvival |
Suicide Survival | |
svencoop |
Sven Coop | |
swat4 |
SWAT 4 | |
synergy |
Synergy | |
tacticalops |
Tactical Ops | |
takeonhelicopters |
Take On Helicopters (2011) | |
teamfactor |
Team Factor | |
tf2 |
Team Fortress 2 | |
tfc |
Team Fortress Classic | |
teamspeak2 |
Teamspeak 2 | |
teamspeak3 |
Teamspeak 3 | Notes |
terminus |
Terminus | |
terraria tshock |
Terraria - TShock (2011) | Notes |
forrest |
The Forrest (2014) | |
hidden |
The Hidden (2005) | |
nolf |
The Operative: No One Lives Forever (2000) | |
ship |
The Ship | |
graw |
Tom Clancy's Ghost Recon Advanced Warfighter (2006) | |
graw2 |
Tom Clancy's Ghost Recon Advanced Warfighter 2 (2007) | |
thps3 |
Tony Hawk's Pro Skater 3 | |
thps4 |
Tony Hawk's Pro Skater 4 | |
thu2 |
Tony Hawk's Underground 2 | |
towerunite |
Tower Unite | |
trackmania2 |
Trackmania 2 | Notes |
trackmaniaforever |
Trackmania Forever | Notes |
tremulous |
Tremulous | |
tribes1 |
Tribes 1: Starsiege | |
tribesvengeance |
Tribes: Vengeance | |
tron20 |
Tron 2.0 | |
turok2 |
Turok 2 | |
universalcombat |
Universal Combat | |
unreal |
Unreal | |
ut |
Unreal Tournament | |
ut2003 |
Unreal Tournament 2003 | |
ut2004 |
Unreal Tournament 2004 | |
ut3 |
Unreal Tournament 3 | |
unturned |
unturned | |
urbanterror |
Urban Terror | |
v8supercar |
V8 Supercar Challenge | |
ventrilo |
Ventrilo | |
vcmp |
Vice City Multiplayer | |
vietcong |
Vietcong | |
vietcong2 |
Vietcong 2 | |
warsow |
Warsow | |
wheeloftime |
Wheel of Time | |
wolfenstein2009 |
Wolfenstein 2009 | |
wolfensteinet |
Wolfenstein: Enemy Territory | |
xpandrally |
Xpand Rally | |
zombiemaster |
Zombie Master | |
zps |
Zombie Panic: Source |
- Cube Engine (cube):
- Cube 1
- Assault Cube
- Cube 2: Sauerbraten
- Blood Frontier
- Alien vs Predator
- Armed Assault 2: Operation Arrowhead
- Battlefield Bad Company 2: Vietnam
- BFRIS
- Call of Duty: Black Ops 1 and 2 (no documentation, may require rcon)
- Crysis Warhead
- Days of War
- DirtyBomb
- Doom - Skulltag
- Doom - ZDaemon
- ECO Global Survival (Ref)
- Farming Simulator
- Freelancer
- Ghost Recon
- GRAV Online
- GTA Network (Ref)
- GTR 2
- Haze
- Hexen World
- Lost Heaven
- Multi Theft Auto
- Pariah
- Plain Sight
- Purge Jihad
- Red Eclipse
- Red Faction
- S.T.A.L.K.E.R. Clear Sky
- Savage: The Battle For Newerth
- Savage 2: A Tortured Soul
- SiN 1 Multiplayer
- South Park
- Star Wars Jedi Knight: Dark Forces II
- Star Wars: X-Wing Alliance
- Sum of All Fears
- Teeworlds
- Tibia (Ref)
- Titanfall
- Tribes 2
- Unreal 2 XMP
- World in Conflict
- World Opponent Network
- Wurm Unlimited
Want support for one of these games? Please open an issue to show your interest! Know how to code? Protocol details for many of the games above are documented at https://github.com/gamedig/legacy-query-library-archive , 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
To receive a full player list response from CS:GO servers, the server must have set the cvar: host_players_show 2
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
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
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
Requires tshock server mod, and a REST user token, which can be passed to GameDig with the additional option: token
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:
gamedig --type minecraft mc.example.com:11234
The output of the command will be in JSON format. Additional advanced parameters can be passed in
as well: --debug
, --pretty
, --socketTimeout 5000
, etc.