Nepotistic Pontifex Maximus

    steam-server-query
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.3 • Public • Published

    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.

    Install

    npm i steam-server-query

    DownloadsWeekly Downloads

    24

    Version

    1.1.3

    License

    MIT

    Unpacked Size

    38 kB

    Total Files

    15

    Last publish

    Collaborators

    • giyomoon