Skip to content

Latest commit

 

History

History
281 lines (265 loc) · 8.29 KB

README.md

File metadata and controls

281 lines (265 loc) · 8.29 KB
Raw

Steam Server Query

npm version npm downloads license

Module which implements the Master Server Query Protocol and Game Server Queries. It is working with promises.

Install

npm install steam-server-query

API

Master Server Query

queryMasterServer(masterServer: string, region: REGIONS, filter?: Filter, timeout?: number, maxHosts?: number): Promise<string[]>

Fetch a Steam master server to retrieve a list of game server hosts.

  • masterServer: Host and port of the master server to call.
  • region: The region of the world where you wish to find servers in. Use REGIONS.ALL for all regions.
  • filter: Optional. Object which contains filters to be sent with the query. Default is { }.
  • timeout: Optional. Time in milliseconds after the socket request should fail. Default is 1 second.
  • maxHosts: Optional. Return a limited amount of hosts. Stops calling the master server after this limit is reached. Can be used to prevent getting rate limited.
  • Returns: A promise including an array of game server hosts.

Game Server Query

queryGameServerInfo(gameServer: string, attempts?: number, timeout?: number | number[]): Promise<InfoResponse>

Send a A2S_INFO request to a game server. Retrieves information like its name, the current map, the number of players and so on. Read more here.

queryGameServerPlayer(gameServer: string, attempts?: number, timeout?: number | number[]): Promise<PlayerResponse>

Send a A2S_PLAYER request to a game server. Retrieves the current playercount and for every player their name, score and duration. Read more here.

queryGameServerRules(gameServer: string, attempts?: number, timeout?: number | number[]): Promise<RulesResponse>

Send a A2S_RULES request to a game server. Retrieves the rule count and for every rule its name and value. Read more here.

Parameters for every Game Server Query function

  • gameServer: Host and port of the game server to call.
  • attempts: Optional. Number of call attempts to make. Default is 1 attempt.
  • timeout: Optional. Time in milliseconds after the socket request should fail. Default is 1000. Specify an array of timeouts if they should be different for every attempt. (Example for 3 attempts: [1000, 1000, 2000])
  • Returns: A promise including an object (Either type InfoResponse, PlayerResponse or RulesResponse)

Types

Master Server Query

REGIONS

enum REGIONS {
  'US_EAST_COAST' = 0x00,
  'US_WEST_COAST' = 0x01,
  'SOUTH_AMERICA' = 0x02,
  'EUROPE' = 0x03,
  'ASIA' = 0x04,
  'AUSTRALIA' = 0x05,
  'MIDDLE_EAST' = 0x06,
  'AFRICA' = 0x07,
  'ALL' = 0xFF
}

Filter

interface Filter extends BasicFilter {
  nor?: BasicFilter;
  nand?: BasicFilter;
}

interface BasicFilter {
  dedicated?: 1;
  secure?: 1;
  gamedir?: string;
  map?: string;
  linux?: 1;
  password?: 0;
  empty?: 1;
  full?: 1;
  proxy?: 1;
  appid?: number;
  napp?: number;
  noplayers?: 1;
  white?: 1;
  gametype?: string[];
  gamedata?: string[];
  gamedataor?: string[];
  name_match?: string;
  version_match?: string;
  collapse_addr_hash?: 1;
  gameaddr?: string;
}

Game Server Query

InfoResponse

interface InfoResponse {
  protocol: number;
  name: string;
  map: string;
  folder: string;
  game: string;
  appId: number;
  players: number;
  maxPlayers: number;
  bots: number;
  serverType: string;
  environment: string;
  visibility: number;
  vac: number;
  version: string;
  port?: number;
  serverId?: BigInt;
  spectatorPort?: number;
  spectatorName?: string;
  keywords?: string;
  gameId?: BigInt;
}

PlayerResponse

interface PlayerResponse {
  playerCount: number;
  players: Player[];
}

interface Player {
  index: number;
  name: string;
  score: number;
  duration: number;
}

RulesResponse

interface RulesResponse {
  ruleCount: number;
  rules: Rule[];
}

interface Rule {
  name: string;
  value: string;
}

Examples

Master Server Protocol

To retrieve all servers from the game Witch It with players on it:

import { queryMasterServer, REGIONS } from 'steam-server-query';

queryMasterServer('hl2master.steampowered.com:27011', REGIONS.ALL, { empty: 1, appid: 559650 }).then(servers => {
  console.log(servers);
}).catch((err) => {
  console.error(err);
});

Response (shortened):

[
  "176.57.181.178:27003"
  "176.57.181.178:27008"
  "176.57.171.49:27005"
  "176.57.181.178:27005"
]

Game Server Protocol

A2S_INFO

To retrieve information about the game server with the address 176.57.181.178:27003:

import { queryGameServerInfo } from 'steam-server-query';

queryGameServerInfo('176.57.181.178:27003').then(infoResponse => {
  console.log(infoResponse);
}).catch((err) => {
  console.error(err);
});

Response:

{
  "protocol": 17,
  "name": "EU04",
  "map": "RandomMapCycle",
  "folder": "WitchIt",
  "game": "Witch Hunt",
  "appId": 0,
  "players": 10,
  "maxPlayers": 16,
  "bots": 0,
  "serverType": "d",
  "environment": "l",
  "visibility": 0,
  "vac": 1,
  "version": "1.0.0.0",
  "port": 7780,
  "keywords": "BUILDID:0,OWNINGID:90154510593238022,OWNINGNAME:EU04,SESSIONFLAGS:683,GameMode_s:Hide and Seek,PlayerCount_i:10,MatchTime_i:265",
  "gameId": 559650
}

A2S_PLAYER

To retrieve players playing on the game server with the address 176.57.181.178:27003:

import { queryGameServerPlayer } from 'steam-server-query';

queryGameServerPlayer('176.57.181.178:27003').then(playerResponse => {
  console.log(playerResponse);
}).catch((err) => {
  console.error(err);
});

Response (shortened):

{
  "playerCount": 10,
  "players": [
    {
      "index": 0,
      "name": "Player_1",
      "score": 0,
      "duration": 1969.7518310546875
    },
    {
      "index": 0,
      "name": "Player_2",
      "score": 0,
      "duration": 1958.9234619140625
    },
    {
      "index": 0,
      "name": "Player_3",
      "score": 0,
      "duration": 1509.9417724609375
    }
  ]
}

A2S_RULES

To retrieve rules of the game server with the address 176.57.181.178:27003:

import { queryGameServerRules } from 'steam-server-query';

queryGameServerRules('176.57.181.178:27003').then(rulesResponse => {
  console.log(rulesResponse);
}).catch((err) => {
  console.error(err);
});

Response:

{
  "ruleCount": 14,
  "rules": [
    { "name": "CONMETHOD", "value": "P2P" },
    { "name": "GameMode_s", "value": "Hide and Seek" },
    { "name": "MatchStarted_b", "value": "true" },
    { "name": "MatchTime_i", "value": "265" },
    { "name": "OWNINGID", "value": "90154510593238022" },
    { "name": "OWNINGNAME", "value": "EU04" },
    { "name": "P2PADDR", "value": "90154510593238022" },
    { "name": "P2PPORT", "value": "7780" },
    { "name": "PlayerCount_i", "value": "10" },
    { "name": "SESSIONFLAGS", "value": "683" },
    { "name": "SessionName_s", "value": "EU04" },
    { "name": "StartTime_s", "value": "2021.12.29-00.47.20" },
    { "name": "Tournament_b", "value": "false" },
    { "name": "VersionNumber_s", "value": "1.2.3" }
  ]
}

Notes

  • The master servers are rate limited. Requests with large outputs (6000+ servers) will probably reach this limit and a timeout error will be thrown.

Links

License

This repository and the code inside it is licensed under the MIT License. Read LICENSE for more information.