Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including gamedig with all npm packages installed. Try it out:

var gamedig = require("gamedig")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

gamedig v2.0.22

Query for the status of any game server in Node.JS

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

Query Options

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)

Return Value

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.
  • 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).

Games List

Supported

GameDig Type IDNameNotes
7d2d7 Days to Die (2013)
ageofchivalryAge of Chivalry (2007)
aoe2Age of Empires 2 (1999)
alienarenaAlien Arena (2004)
alienswarmAlien Swarm (2010)
avp2Aliens versus Predator 2 (2001)
avp2010Aliens vs. Predator (2010)
americasarmyAmerica's Army (2002)
americasarmy2America's Army 2 (2003)
americasarmy3America's Army 3 (2009)
americasarmypgAmerica's Army: Proving Grounds (2015)
arcasimracingArca Sim Racing (2008)
arkseArk: Survival Evolved (2017)
arma2ARMA 2 (2009)
arma2oaARMA 2: Operation Arrowhead (2010)
arma3ARMA 3 (2013)
armaARMA: Armed Assault (2007)
armacwaARMA: Cold War Assault (2011)
armarARMA: Resistance (2011)
armagetronArmagetron Advanced (2001)
assettocorsaAssetto Corsa (2014)
atlasAtlas (2018)
baldursgateBaldur's Gate (1998)
bat1944Battalion 1944 (2018)
bf1942Battlefield 1942 (2002)
bf2Battlefield 2 (2005)
bf2142Battlefield 2142 (2006)
bf3Battlefield 3 (2011)
bf4Battlefield 4 (2013)
bfhBattlefield Hardline (2015)
bfvBattlefield Vietnam (2004)
bfbc2Battlefield: Bad Company 2 (2010)
breachBreach (2011)
breedBreed (2004)
brinkBrink (2011)
buildandshootBuild and Shoot / Ace of Spades Classic (2012)
codCall of Duty (2003)
cod2Call of Duty 2 (2005)
cod3Call of Duty 3 (2006)
cod4Call of Duty 4: Modern Warfare (2007)
codmw2Call of Duty: Modern Warfare 2 (2009)
codmw3Call of Duty: Modern Warfare 3 (2011)
coduoCall of Duty: United Offensive (2004)
codwawCall of Duty: World at War (2008)
callofjuarezCall of Juarez (2006)
chaserChaser (2003)
chromeChrome (2003)
codenameeagleCodename Eagle (2000)
cacrenegadeCommand and Conquer: Renegade (2002)
commandos3Commandos 3: Destination Berlin (2003)
conanexilesConan Exiles (2018)
contagionContagion (2011)
contactjackContract J.A.C.K. (2003)
cs15Counter-Strike 1.5 (2002)
cs16Counter-Strike 1.6 (2003)
cs2dCounter-Strike: 2D (2004)
csczCounter-Strike: Condition Zero (2004)
csgoCounter-Strike: Global Offensive (2012)Notes
cssCounter-Strike: Source (2004)
crossracingCross Racing Championship Extreme 2005 (2005)
crysisCrysis (2007)
crysis2Crysis 2 (2011)
crysiswarsCrysis Wars (2008)
daikatanaDaikatana (2000)
dnlDark and Light (2017)
dmomamDark Messiah of Might and Magic (2006)
darkesthourDarkest Hour: Europe '44-'45 (2008)
dodDay of Defeat (2003)
dodsDay of Defeat: Source (2005)
doiDay of Infamy (2017)
daysofwarDays of War (2017)
dayzDayZ (2018)
dayzmodDayZ Mod (2013)
deadlydozenptDeadly Dozen: Pacific Theater (2002)
dh2005Deer Hunter 2005 (2004)
descent3Descent 3 (1999)
deusexDeus Ex (2000)
devastationDevastation (2003)
dinoddayDino D-Day (2011)
dirttrackracing2Dirt Track Racing 2 (2002)
doom3Doom 3 (2004)
dota2Dota 2 (2013)
drakanDrakan: Order of the Flame (1999)
empyrionEmpyrion - Galactic Survival (2015)
etqwEnemy Territory: Quake Wars (2007)
fearF.E.A.R. (2005)
f1c9902F1 Challenge '99-'02 (2002)
farcryFar Cry (2004)
farcry2Far Cry 2 (2008)
f12002Formula One 2002 (2002)
fortressforeverFortress Forever (2007)
ffowFrontlines: Fuel of War (2008)
garrysmodGarry's Mod (2004)
geneshift
mutantfactions
Geneshift (2017)
giantscitizenkabutoGiants: Citizen Kabuto (2000)
globaloperationsGlobal Operations (2002)
gesGoldenEye: Source (2010)
goreGore: Ultimate Soldier (2002)
fivemGrand Theft Auto V - FiveM (2013)
mtasaGrand Theft Auto: San Andreas - Multi Theft Auto (2004)
mtavcGrand Theft Auto: Vice City - Multi Theft Auto (2002)
gunmanchroniclesGunman Chronicles (2000)
hl2dmHalf-Life 2: Deathmatch (2004)
hldmHalf-Life Deathmatch (1998)
hldmsHalf-Life Deathmatch: Source (2005)
haloHalo (2003)
halo2Halo 2 (2007)
hllHell Let Loose
heretic2Heretic II (1998)
hexen2Hexen II (1997)
had2Hidden & Dangerous 2 (2003)
homefrontHomefront (2011)
homeworld2Homeworld 2 (2003)
hurtworldHurtworld (2015)
igi2I.G.I.-2: Covert Strike (2003)
il2IL-2 Sturmovik (2001)
insurgencyInsurgency (2014)
insurgencysandstormInsurgency: Sandstorm (2018)
ironstormIron Storm (2002)
jamesbondnightfireJames Bond 007: Nightfire (2002)
jc2mpJust Cause 2 - Multiplayer (2010)
jc3mpJust Cause 3 - Multiplayer (2017)
kspdmpKerbal Space Program - DMP Multiplayer (2015)
killingfloorKilling Floor (2009)
killingfloor2Killing Floor 2 (2016)
kingpinKingpin: Life of Crime (1999)
kisspcKiss: Psycho Circus: The Nightmare Child (2000)
kzmodKreedz Climbing (2017)
left4deadLeft 4 Dead (2008)
left4dead2Left 4 Dead 2 (2009)
m2mpMafia II - Multiplayer (2010)
m2oMafia II - Online (2010)
moh2010Medal of Honor (2010)
mohabMedal of Honor: Airborne (2007)
mohaaMedal of Honor: Allied Assault (2002)
mohbtMedal of Honor: Allied Assault Breakthrough (2003)
mohshMedal of Honor: Allied Assault Spearhead (2002)
mohpaMedal of Honor: Pacific Assault (2004)
mohwfMedal of Honor: Warfighter (2012)
medievalengineersMedieval Engineers (2015)
minecraft
minecraftping
Minecraft (2009)
minecraftpe
minecraftbe
Minecraft: Bedrock Edition (2011)
mncMonday Night Combat (2011)
mordhauMordhau (2019)
mumbleMumble - GTmurmur Plugin (2005)Notes
mumblepingMumble - Lightweight (2005)Notes
nascarthunder2004NASCAR Thunder 2004 (2003)
nsNatural Selection (2002)
ns2Natural Selection 2 (2012)
nfshp2Need for Speed: Hot Pursuit 2 (2002)
nabNerf Arena Blast (1999)
netpanzernetPanzer (2002)
nwnNeverwinter Nights (2002)
nwn2Neverwinter Nights 2 (2006)
nexuizNexuiz (2005)
nitrofamilyNitro Family (2004)
nmrihNo More Room in Hell (2011)
nolf2No One Lives Forever 2: A Spy in H.A.R.M.'s Way (2002)
nucleardawnNuclear Dawn (2011)
openarenaOpenArena (2005)
openttdOpenTTD (2004)
operationflashpoint
flashpoint
Operation Flashpoint: Cold War Crisis (2001)
flashpointresistanceOperation Flashpoint: Resistance (2002)
painkillerPainkiller
pixarkPixARK (2018)
postal2Postal 2
preyPrey
primalcarnagePrimal Carnage: Extinction
prbf2Project Reality: Battlefield 2 (2005)
quake1Quake 1: QuakeWorld (1996)
quake2Quake 2 (1997)
quake3Quake 3: Arena (1999)
quake4Quake 4 (2005)
quakeliveQuake Live (2010)
ragdollkungfuRag Doll Kung Fu
r6Rainbow Six
r6roguespearRainbow Six 2: Rogue Spear
r6ravenshieldRainbow Six 3: Raven Shield
rallisportchallengeRalliSport Challenge
rallymastersRally Masters
redorchestraRed Orchestra
redorchestra2Red Orchestra 2
redorchestraostRed Orchestra: Ostfront 41-45
redlineRedline
rtcwReturn to Castle Wolfenstein
rfactorrFactor
ricochetRicochet
riseofnationsRise of Nations
rs2Rising Storm 2: Vietnam
runeRune
rustRust
stalkerS.T.A.L.K.E.R.
sampSan Andreas Multiplayer
ssSerious Sam
ss2Serious Sam 2
shatteredhorizonShattered Horizon
shogoShogo
shootmaniaShootmaniaNotes
sinSiN
sinepSiN Episodes
soldatSoldat
sofSoldier of Fortune
sof2Soldier of Fortune 2
spaceengineersSpace Engineers
squadSquad
stbcStar Trek: Bridge Commander
stvefStar Trek: Voyager - Elite Force
stvef2Star Trek: Voyager - Elite Force 2
swjk2Star Wars Jedi Knight II: Jedi Outcast (2002)
swjkStar Wars Jedi Knight: Jedi Academy (2003)
swbfStar Wars: Battlefront
swbf2Star Wars: Battlefront 2
swrcStar Wars: Republic Commando
starboundStarbound
starmadeStarMade
starsiegeStarsiege (2009)
suicidesurvivalSuicide Survival
svencoopSven Coop
swat4SWAT 4
synergySynergy
tacticalopsTactical Ops
takeonhelicoptersTake On Helicopters (2011)
teamfactorTeam Factor
tf2Team Fortress 2
tfcTeam Fortress Classic
teamspeak2Teamspeak 2
teamspeak3Teamspeak 3Notes
terminusTerminus
terraria
tshock
Terraria - TShock (2011)Notes
forrestThe Forrest (2014)
hiddenThe Hidden (2005)
nolfThe Operative: No One Lives Forever (2000)
shipThe Ship
grawTom Clancy's Ghost Recon Advanced Warfighter (2006)
graw2Tom Clancy's Ghost Recon Advanced Warfighter 2 (2007)
thps3Tony Hawk's Pro Skater 3
thps4Tony Hawk's Pro Skater 4
thu2Tony Hawk's Underground 2
toweruniteTower Unite
trackmania2Trackmania 2Notes
trackmaniaforeverTrackmania ForeverNotes
tremulousTremulous
tribes1Tribes 1: Starsiege
tribesvengeanceTribes: Vengeance
tron20Tron 2.0
turok2Turok 2
universalcombatUniversal Combat
unrealUnreal
utUnreal Tournament
ut2003Unreal Tournament 2003
ut2004Unreal Tournament 2004
ut3Unreal Tournament 3
unturnedunturned
urbanterrorUrban Terror
v8supercarV8 Supercar Challenge
ventriloVentrilo
vcmpVice City Multiplayer
vietcongVietcong
vietcong2Vietcong 2
warsowWarsow
wheeloftimeWheel of Time
wolfenstein2009Wolfenstein 2009
wolfensteinetWolfenstein: Enemy Territory
xpandrallyXpand Rally
zombiemasterZombie Master
zpsZombie Panic: Source

Not supported (yet)

  • 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

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

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

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:

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.

Metadata

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free