Source Server Queries for Node.JS


A Node.JS library for sending Source Server Queries (SSQ) to source engine powered game servers (TF2, L4D, etc.).

I recommend glancing over the following Valve dev wiki page about SSQ:

I created this library and shortly after didn't need it anymore. It should work fine, but has not been aggresively tested.

Some long messages may be split into chunks or compressed. Neither of these modes are currently supported. If you see an error like:

SSQ response used unsupported split packet mode.

then you're out of luck. Currently I only get this message when requesting the rules list from some servers.

The API is very simple. All functions are passed a server string (dotted quad ipv4 address or domain name), a port number, and a callback function that takes an error as the first parameter and the returned data as the second parameter.

All the below examples assume this library is imported as ssq:

var ssq = require('node-ssq');

Sets the timeout in milliseconds (ms) for all SSQ requests (Default: 2000ms, available as ssq.DEFAULT_TIMEOUT). Because SSQ requests are sent over UDP instead of TCP, timeouts are the only way of determining if a request has failed.

Note: If data that comes in after a timeout has expired will be silently dropped.'', 1337, function (err, data) {});

Pings the server. This message has been deprecated by Valve, and doesn't serve much of a use...'', 1337, function (err, data) {});

Returns a single object with a lot of data about the server.

{ netver: 17,
  servername: 'Reddit Unofficial Gaming Community - East Coast',
  map: 'pl_upward',
  gamedirectory: 'tf',
  gamedescription: 'Team Fortress',
  appid: 440,
  numplayers: 23,
  maxplayers: 24,
  numbots: 0,
  servertype: 'd',
  os: 'l',
  password: 0,
  vacsecured: 1,
  gameversion: '',
  EDF: 177,

  // The following properties are each individually optional
  port: 27015,
  steamID: <Buffer 02 e4 1e 81 af 0c 40 01>,
  sourceTV: { port: 27020, name: 'SourceTV' },
  keywords: '_registered,alltalk,east,nocrits,nodmgspread,payload,reddit,replays,rugc',
  gameID: <Buffer b8 01 00 00 00 00 00 00> }

Most of these values should be self explanatory.

The EDF value is a flag for the optional values. You shouldn't need to look at this flag yourself.

steamID and gameID are 64 bit values, so they are returned as node.js Buffer objects with 8 bytes. Note that all JavaScript numbers are 64-bit floating point numbers, with only 53 bits of precision, so 64 bit values should not be handled as primitive JavaScript numbers.

ssq.players('', 1337, function (err, data) {});

Returns an array of players. Sample data:

[{ index: 0,
   name: 'Sample Name',
   score: 2,
   duration: 267.5876159667969 }, ...]

Note that the index attribute seems to always be 0, and the duration is in seconds.

ssq.rules('', 1337, function (err, data) {});

Returns an array of server rules. Sample data:

[{ name: 'sv_cheats', value: '1'}, ...]
ssq.get_challenge('', 1337, function (err, data) {});

Queries the server for a challenge number, used by some of the requests. This method probably won't be needed by anybody, but is provided for completeness of the SSQ API.

<Buffer b8 a4 c3 0f>