sourcemeter v1.0.0

SourceMeter

SourceMeter is a Node.js library written in TypeScript. It queries information from a running Source Dedicated Server (SRCDS) using UDP/IP packets.

Installation

npm i sourcemeter

Usage

Example values for properties address & port must be replaced with the remote server to be queried.

JavaScript

import { infoQuery } from 'sourcemeter'

const response = await infoQuery({
  address: '127.0.0.1',
  port: 12345,
})

TypeScript

import type { InfoQuery, RemoteDestination } from 'sourcemeter'
import { infoQuery } from 'sourcemeter'

const destination: RemoteDestination = {
  address: '127.0.0.1',
  port: 12345,
}

const response: InfoQuery = await infoQuery(destination)

Types reference

Built-in type definitions are available for supported IDEs and editors, including for non-TypeScript users.

Importing types with TypeScript is optional and suggested for type safety and readability.

Imports

import type { InfoQuery, RemoteDestination } from 'sourcemeter'

Request

RemoteDestination is the input parameter for infoQuery.

type RemoteDestination = {
  address: string
  port: number
}

Response

Specification: SRCDS server queries

The InfoQuery response object is JSON-serializable. Multiple fields are conditional to the value of extraDataFlag.

type InfoQuery = {
  antiCheat: boolean
  appID?: string
  bots: number
  extraDataFlag: number
  folder: string
  game: string
  keywords?: string
  map: string
  operatingSystem: 'Linux' | 'macOS' | 'Windows'
  passwordRequired: boolean
  platformID?: string
  players: number
  playersMax: number
  port?: number
  protocolVersion: number
  response: {
    address: string
    challenge?: number
    family: string
    latency: number
    messages: [
      {
        message: Buffer
        size: number
      }
      // {...},
    ]
    packetSplit: boolean
    port: number
    type: 'A2S_INFO'
  }
  serverName: string
  serverType: 'dedicated' | 'local' | 'proxy'
  serverVersion: string
  spectatorName?: number
  spectatorPort?: number
}

Compatibility

Simple query responses from A2S_INFO in a single non-split packet are compatible, including anti-reflection attack challenges (est. Dec. 2020). Multi-packet responses are currently incompatible.

Environment

node:buffer and node:dgram are Node.js dependencies that are incompatible with a browser environment, unless integrated with an API (see also: Next.js API route handler).

Games tested

• Valheim (2021)

Other games are likely compatible but have yet to be tested. For querying unsupported games in Node.js, try node-GameDig (est. 2013).

Use cases

• Functions as a service (FaaS)
• REST API routes
• Web applications

Next.js API route handler

• Vercel | Next.js API routes

import { infoQuery } from 'sourcemeter'

export default async function handler(req, res) {
  res.status(200).json(
    await infoQuery({
      address: '127.0.0.1',
      port: 12345,
    })
  )
}