{"id":15384,"library":"steam-server-query","title":"Steam Master and Game Server Query","description":"This package provides a promise-based Node.js module for programmatically interacting with Steam's Master Server Query Protocol and Game Server Queries. It enables developers to fetch lists of active game servers from a Steam master server, supporting extensive filtering by region and various server properties (e.g., game directory, map, player count, appid). Additionally, it fully supports querying individual game servers for detailed information via A2S_INFO (server name, map, players), A2S_PLAYER (player list with scores and duration), and A2S_RULES (server-specific rules and values). The current stable version is 1.1.3, with recent releases focusing on improved socket stability, enhanced retry mechanisms for queries, and options to mitigate rate limiting during master server lookups. It ships with comprehensive TypeScript type definitions, ensuring robust usage in modern JavaScript and TypeScript environments. Its primary differentiator is its complete implementation of both Master and Game Server Query protocols with a resilient, promise-based API.","status":"active","version":"1.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/GiyoMoon/steam-server-query","tags":["javascript","steam","master server query","game server query","typescript"],"install":[{"cmd":"npm install steam-server-query","lang":"bash","label":"npm"},{"cmd":"yarn add steam-server-query","lang":"bash","label":"yarn"},{"cmd":"pnpm add steam-server-query","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses named exports. Prefer ES Modules.","wrong":"const { queryMasterServer } = require('steam-server-query');","symbol":"queryMasterServer","correct":"import { queryMasterServer } from 'steam-server-query';"},{"note":"All main query functions are named exports.","wrong":"import queryGameServerInfo from 'steam-server-query';","symbol":"queryGameServerInfo","correct":"import { queryGameServerInfo } from 'steam-server-query';"},{"note":"REGIONS is an enum and should be imported as a named export.","wrong":"import * as REGIONS from 'steam-server-query';","symbol":"REGIONS","correct":"import { REGIONS } from 'steam-server-query';"},{"note":"Import types using 'import type' for clarity and tree-shaking benefits in TypeScript.","symbol":"Filter","correct":"import type { Filter } from 'steam-server-query';"}],"quickstart":{"code":"import { queryMasterServer, queryGameServerInfo, queryGameServerPlayer, REGIONS } from 'steam-server-query';\n\nasync function runQuery() {\n  try {\n    console.log('Querying master server for all regions...');\n    const masterServers = [\n      'hl2master.steampowered.com:27011',\n      'hl2master.steampowered.com:27012'\n    ];\n\n    const gameServers = await queryMasterServer(masterServers[0], REGIONS.ALL, {\n      appid: 440, // Team Fortress 2\n      gamedir: 'tf',\n      empty: 1\n    }, 2000, 5); // Timeout 2s, max 5 hosts\n\n    if (gameServers.length === 0) {\n      console.log('No game servers found matching criteria.');\n      return;\n    }\n\n    console.log(`Found ${gameServers.length} game servers. Querying the first one: ${gameServers[0]}`);\n\n    const serverInfo = await queryGameServerInfo(gameServers[0]);\n    console.log('\\n--- Server Info ---');\n    console.log(`Name: ${serverInfo.name}`);\n    console.log(`Map: ${serverInfo.map}`);\n    console.log(`Players: ${serverInfo.players}/${serverInfo.maxPlayers}`);\n    console.log(`Game: ${serverInfo.game}`);\n\n    const playerInfo = await queryGameServerPlayer(gameServers[0]);\n    console.log('\\n--- Player Info ---');\n    playerInfo.players.forEach(player => {\n      console.log(`- ${player.name} (Score: ${player.score}, Duration: ${player.duration.toFixed(2)}s)`);\n    });\n\n    // Example of handling potential errors or missing player data\n    if (playerInfo.players.length === 0) {\n      console.log('No players found on this server.');\n    }\n\n  } catch (error) {\n    console.error('An error occurred during the query:', error.message);\n    if (error.code === 'ETIMEDOUT') {\n      console.error('The server query timed out. The server might be offline or unreachable.');\n    }\n  }\n}\n\nrunQuery();","lang":"typescript","description":"Demonstrates querying a Steam master server to find Team Fortress 2 servers, then querying the first found game server for its detailed information and player list."},"warnings":[{"fix":"Upgrade to `steam-server-query@1.1.1` or newer to ensure proper socket cleanup.","message":"Older versions of the library (prior to v1.1.1) had issues with UDP sockets not closing correctly after a request, leading to potential resource leaks or 'address already in use' errors. This was resolved in v1.1.1.","severity":"gotcha","affected_versions":"<1.1.1"},{"fix":"When calling `queryMasterServer`, utilize the `maxHosts` parameter to cap the number of returned servers, e.g., `queryMasterServer(..., maxHosts: 50)`. Consider adding delays between successive master server queries if fetching large lists.","message":"Master server queries can be rate-limited by Valve's servers if too many requests are made in a short period. The `maxHosts` option was introduced to help mitigate this by limiting the number of hosts returned.","severity":"gotcha","affected_versions":">=1.1.0"},{"fix":"Upgrade to `steam-server-query@1.1.3` or newer. If on an older version, manually implement retry logic when calling `queryGameServerPlayer`.","message":"A2S_PLAYER requests may sometimes require multiple attempts or 'challenge retries' due to the protocol specifics, which could lead to initial failures. This was addressed with an internal fix in v1.1.3.","severity":"gotcha","affected_versions":"<1.1.3"},{"fix":"Always ensure the `gameServer` string includes both the host (IP or domain) and the port, e.g., `'192.168.1.100:27015'` or `'mygameserver.com:27015'`.","message":"Game server query functions (`queryGameServerInfo`, `queryGameServerPlayer`, `queryGameServerRules`) expect the `gameServer` argument in `host:port` format. Providing just a hostname or an IP without a port will result in connection failures.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Increase the `timeout` parameter for the query function. Verify the `gameServer` address and port are correct and that the server is online and accessible from your network. Check firewall rules.","cause":"The queried game or master server did not respond within the specified timeout duration, or the server is offline/unreachable.","error":"Error: Request timed out"},{"fix":"For CommonJS, use `const { queryMasterServer, REGIONS } = require('steam-server-query');`. Ensure your project's `package.json` is not explicitly set to `\"type\": \"module\"` if you intend to use `require`.","cause":"This typically occurs in CommonJS environments (Node.js without type: 'module' in package.json) when trying to use ES module `import` syntax or an incorrect `require` pattern.","error":"TypeError: queryMasterServer is not a function"},{"fix":"This issue was largely resolved in `steam-server-query@1.1.1`. Ensure you are on version `1.1.1` or higher. If the problem persists, it may indicate another application is using the port, or a very rapid succession of queries without allowing the OS to release the port.","cause":"This error can occur when a UDP socket tries to bind to a port that is still in use, often due to improper socket closure in previous operations.","error":"Error: Address already in use"}],"ecosystem":"npm"}