Nimble Pirate Monitor

    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/gamedig package

    4.0.5 • Public • Published

    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');
        type: 'minecraft',
        host: ''
    }).then((state) => {
    }).catch((error) => {
        console.log("Server is offline");

    Query Options


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


    • 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)
    • givenPortOnly: boolean - Only attempt to query server on given port. (default false)
    • debug: boolean - Enables massive amounts of debug logging to stdout. (default false)
    • requestRules: boolean - Valve games only. Additional 'rules' may be fetched into the raw field. (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
      • name: string - If the player's name is unknown, the string will be empty.
      • raw: object - Additional information about the player if available (unstable)
        • The content of this field MAY change on a per-protocol basis between GameDig patch releases (although not typical).
    • 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


    GameDig Type ID Name See Also
    7d2d 7 Days to Die (2013) Valve Protocol
    ageofchivalry Age of Chivalry (2007) Valve Protocol
    aoe2 Age of Empires 2 (1999)
    alienarena Alien Arena (2004)
    alienswarm Alien Swarm (2010) Valve Protocol
    avp2 Aliens versus Predator 2 (2001)
    avp2010 Aliens vs. Predator (2010) Valve Protocol
    americasarmy America's Army (2002)
    americasarmy2 America's Army 2 (2003)
    americasarmy3 America's Army 3 (2009) Valve Protocol
    americasarmypg America's Army: Proving Grounds (2015) Valve Protocol
    arcasimracing Arca Sim Racing (2008)
    arkse Ark: Survival Evolved (2017) Valve Protocol
    arma2 ARMA 2 (2009) Valve Protocol
    arma2oa ARMA 2: Operation Arrowhead (2010) Valve Protocol
    arma3 ARMA 3 (2013) Valve Protocol
    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) Valve Protocol
    baldursgate Baldur's Gate (1998)
    barotrauma Barotrauma (2019) Valve Protocol
    bat1944 Battalion 1944 (2018) Valve Protocol
    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) Valve Protocol
    breed Breed (2004)
    brink Brink (2011) Valve Protocol
    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) Valve Protocol
    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) Valve Protocol
    contagion Contagion (2011) Valve Protocol
    contactjack Contract J.A.C.K. (2003)
    cs15 Counter-Strike 1.5 (2002)
    cs16 Counter-Strike 1.6 (2003) Valve Protocol
    cs2d Counter-Strike: 2D (2004)
    cscz Counter-Strike: Condition Zero (2004) Valve Protocol
    csgo Counter-Strike: Global Offensive (2012) Notes, Valve Protocol
    css Counter-Strike: Source (2004) Valve Protocol
    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) Valve Protocol
    dmomam Dark Messiah of Might and Magic (2006) Valve Protocol
    darkesthour Darkest Hour: Europe '44-'45 (2008)
    dod Day of Defeat (2003) Valve Protocol
    dods Day of Defeat: Source (2005) Valve Protocol
    doi Day of Infamy (2017) Valve Protocol
    daysofwar Days of War (2017) Valve Protocol
    dayz DayZ (2018) Valve Protocol
    dayzmod DayZ Mod (2013) Valve Protocol
    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) Valve Protocol
    dirttrackracing2 Dirt Track Racing 2 (2002)
    discord Discord Notes
    doom3 Doom 3 (2004)
    dota2 Dota 2 (2013) Valve Protocol
    drakan Drakan: Order of the Flame (1999)
    empyrion Empyrion - Galactic Survival (2015) Valve Protocol
    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) Valve Protocol
    ffow Frontlines: Fuel of War (2008)
    garrysmod Garry's Mod (2004) Valve Protocol
    Geneshift (2017)
    giantscitizenkabuto Giants: Citizen Kabuto (2000)
    globaloperations Global Operations (2002)
    ges GoldenEye: Source (2010) Valve Protocol
    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)
    groundbreach Ground Breach (2018) Valve Protocol
    gunmanchronicles Gunman Chronicles (2000) Valve Protocol
    hl2dm Half-Life 2: Deathmatch (2004) Valve Protocol
    hldm Half-Life Deathmatch (1998) Valve Protocol
    hldms Half-Life Deathmatch: Source (2005) Valve Protocol
    halo Halo (2003)
    halo2 Halo 2 (2007)
    hll Hell Let Loose Valve Protocol
    heretic2 Heretic II (1998)
    hexen2 Hexen II (1997)
    had2 Hidden & Dangerous 2 (2003)
    homefront Homefront (2011) Valve Protocol
    homeworld2 Homeworld 2 (2003)
    hurtworld Hurtworld (2015) Valve Protocol
    igi2 I.G.I.-2: Covert Strike (2003)
    il2 IL-2 Sturmovik (2001)
    insurgency Insurgency (2014) Valve Protocol
    insurgencysandstorm Insurgency: Sandstorm (2018) Valve Protocol
    ironstorm Iron Storm (2002)
    jamesbondnightfire James Bond 007: Nightfire (2002)
    jc2mp Just Cause 2 - Multiplayer (2010)
    jc3mp Just Cause 3 - Multiplayer (2017) Valve Protocol
    kspdmp Kerbal Space Program - DMP Multiplayer (2015)
    killingfloor Killing Floor (2009)
    killingfloor2 Killing Floor 2 (2016) Valve Protocol
    kingpin Kingpin: Life of Crime (1999)
    kisspc Kiss: Psycho Circus: The Nightmare Child (2000)
    kzmod Kreedz Climbing (2017) Valve Protocol
    left4dead Left 4 Dead (2008) Valve Protocol
    left4dead2 Left 4 Dead 2 (2009) Valve Protocol
    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) Valve Protocol
    Minecraft (2009)
    Minecraft: Bedrock Edition (2011)
    mnc Monday Night Combat (2011) Valve Protocol
    mordhau Mordhau (2019) Valve Protocol
    mumble Mumble - GTmurmur Plugin (2005) Notes
    mumbleping Mumble - Lightweight (2005) Notes
    nascarthunder2004 NASCAR Thunder 2004 (2003)
    ns Natural Selection (2002) Valve Protocol
    ns2 Natural Selection 2 (2012) Valve Protocol
    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) Valve Protocol
    nolf2 No One Lives Forever 2: A Spy in H.A.R.M.'s Way (2002)
    nucleardawn Nuclear Dawn (2011) Valve Protocol
    openarena OpenArena (2005)
    openttd OpenTTD (2004)
    Operation Flashpoint: Cold War Crisis (2001)
    flashpointresistance Operation Flashpoint: Resistance (2002)
    painkiller Painkiller
    pixark PixARK (2018) Valve Protocol
    ps Post Scriptum
    postal2 Postal 2
    prey Prey
    primalcarnage Primal Carnage: Extinction Valve Protocol
    prbf2 Project Reality: Battlefield 2 (2005)
    przomboid Project Zomboid Valve Protocol
    quake1 Quake 1: QuakeWorld (1996)
    quake2 Quake 2 (1997)
    quake3 Quake 3: Arena (1999)
    quake4 Quake 4 (2005)
    quakelive Quake Live (2010) Valve Protocol
    ragdollkungfu Rag Doll Kung Fu Valve Protocol
    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 Valve Protocol
    redorchestraost Red Orchestra: Ostfront 41-45
    redline Redline
    rtcw Return to Castle Wolfenstein
    rfactor rFactor
    ricochet Ricochet Valve Protocol
    riseofnations Rise of Nations
    rs2 Rising Storm 2: Vietnam Valve Protocol
    rune Rune
    rust Rust Valve Protocol
    stalker S.T.A.L.K.E.R.
    samp San Andreas Multiplayer
    savage2 Savage 2: A Tortured Soul (2008)
    ss Serious Sam
    ss2 Serious Sam 2
    shatteredhorizon Shattered Horizon Valve Protocol
    shogo Shogo
    shootmania Shootmania Notes
    sin SiN
    sinep SiN Episodes Valve Protocol
    soldat Soldat
    sof Soldier of Fortune
    sof2 Soldier of Fortune 2
    spaceengineers Space Engineers Valve Protocol
    squad Squad Valve Protocol
    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 Valve Protocol
    starmade StarMade
    starsiege Starsiege (2009)
    suicidesurvival Suicide Survival Valve Protocol
    svencoop Sven Coop Valve Protocol
    swat4 SWAT 4
    synergy Synergy Valve Protocol
    tacticalops Tactical Ops
    takeonhelicopters Take On Helicopters (2011)
    teamfactor Team Factor
    tf2 Team Fortress 2 Valve Protocol
    tfc Team Fortress Classic Valve Protocol
    teamspeak2 Teamspeak 2
    teamspeak3 Teamspeak 3 Notes
    terminus Terminus
    Terraria - TShock (2011) Notes
    forrest The Forrest (2014) Valve Protocol
    hidden The Hidden (2005) Valve Protocol
    nolf The Operative: No One Lives Forever (2000)
    ship The Ship Valve Protocol
    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 Valve Protocol
    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 Valve Protocol
    urbanterror Urban Terror
    v8supercar V8 Supercar Challenge
    valheim Valheim (2021) Notes, Valve Protocol
    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 Valve Protocol
    zps Zombie Panic: Source Valve Protocol

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


    You must set the guildId request field to the server's guild ID. Do not provide an IP. The Guild ID can be found in server widget settings (Server ID) or by enabling developer mode in client settings and right-clicking the server's icon. In order to retrieve information from discord server's they must have the Enable server widget option enabled.


    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

    In the extremely unusual case that your server host responds to queries on a non-default port (the default is 10011), you can specify their host query port using the teamspeakQueryPort option.


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


    Valheim servers will only respond to queries if they are started in public mode (-public 1).


    DayZ stores some of it's servers information inside the tags attribute. Make sure to set requestRules: true to access it. Some data inside dayzMods attribute may be fuzzy, due to how mods are loaded into the servers. Alternatively, some servers may have a third party tool that you can use to get the mods information. If it's installed, you can access it via browser with the game servers IP:PORT, but add up 10 to the port. (eg. if game port is 2302 then use 2312).

    Valve Protocol

    For many valve games, additional 'rules' may be fetched into the unstable raw field by passing the additional option: requestRules: true. Beware that this may increase query time.

    Common Issues

    Firewalls block incoming UDP

    (replit / docker / some VPS providers)

    Most game query protocols require a UDP request and response. This means that in some environments, gamedig may not be able to receive the reponse required due to environmental restrictions.

    Some examples include:

    • Docker containers
      • You may need to run the container in --network host mode so that gamedig can bind a UDP listen port.
      • Alternatively, you can forward a single UDP port to your container, and force gamedig to listen on that port using the instructions in the section down below.
    • replit
      • Most online IDEs run in an isolated container, which will never receive UDP responses from outside networks.
    • Various VPS / server providers
      • Even if your server provider doesn't explicitly block incoming UDP packets, some server hosts block other server hosts from connecting to them for DDOS-mitigation and anti-botting purposes.

    Gamedig doesn't work in the browser

    Gamedig cannot operate within a browser. This means you cannot package it as part of your webpack / browserify / rollup / parcel package. Even if you were able to get it packaged into a bundle, unfortunately no browsers support the UDP protocols required to query server status from most game servers. As an alternative, we'd recommend using gamedig on your server-side, then expose your own API to your webapp's frontend displaying the status information. If your application is thin (with no constant server component), you may wish to investigate a server-less lambda provider.

    Specifying a listen UDP port override

    In some very rare scenarios, you may need to bind / listen on a fixed local UDP port. The is usually not needed except behind some extremely strict firewalls, or within a docker container (where you only wish to forward a single UDP port). To use a fixed listen udp port, construct a new Gamedig object like this:

    const gamedig = new Gamedig({
        listenUdpPort: 13337

    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

    Alternatively, if you don't want to install gamedig globally, you can run it with npx:

    npx gamedig --type minecraft

    The output of the command will be in JSON format. Additional advanced parameters can be passed in as well: --debug, --pretty, --socketTimeout 5000, --requestRules etc.




    npm i gamedig

    DownloadsWeekly Downloads






    Unpacked Size

    214 kB

    Total Files


    Last publish


    • mmorrisontx