View Source A2S

A library for communicating with game servers running Valve's A2S server query protocol.

installation

Installation

The package can be installed by adding a2s to your list of dependencies in mix.exs:

def deps do
  [
    {:a2s, "~> 0.2.0"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/a2s.

usage

Usage

There's two general ways to use this library:

via-a2s-client

Via A2S.Client

An easy to use client that should cover most use-cases. Add A2S.Client to your app's supervision tree:

children = [
  {A2S.Client, [name: MyA2SCli]}
]

Or start the client dynamically:

A2S.Client.start_link([name: MyA2SCli])

Afterwards querying a game server's as simple as:

A2S.Client.query(:info, {{127, 0, 0, 1}, 20000}) # ipv4 address followed by port

via-a2s

Via A2S

This module provides the means form requests, sign challenges, and parse responses for the A2S protocol. You can utilize this module directly in your application for tighter integration, but in turn you'll have to handle the networking or handshaking necessary to execute A2S queries.

See the roll your own guide and the internals of A2S.Client may serve as a good reference in that regard.

unsupported-games-and-features

Unsupported Games and Features

The features and game servers listed below are unsupported due to disuse and to favor maintainability.

Source 2006 / "Pre-Orange Box" servers

Would require supporting compression in multipacket responses. Not only adds code complexity, but would require users to have bzip2 installed.

Other game servers utilizing multi-packet compression

(see above)

GoldSrc Servers not using the standard protocol

Should impact exceedingly few applications as many GoldSrc servers use the current standard anyway.

The Ship

Uses proprietary fields only worth supporting out of posterity-sake.

A2A_PING

Considered deprecated by Valve and is unsupported by many if not almost all most engines.

A2S_SERVERQUERY_GETCHALLENGE

Only used by a handful of niche games. Normal challenge flow should work anyway.

issues

Issues

If you'd like to report an issue, please include as much information as possible to reproduce the issue.

debugging

Debugging

A2S.Client uses Erlang's gen_statem behavior to function and therefore requires the following Logger configuration to report exceptions and crashes:

config :logger,
  handle_otp_reports: true,
  handle_sasl_reports: true

or in a REPL:

Logger.configure(handle_otp_reports: true)
Logger.configure(handle_sasl_reports: true)

much-todo

(Much) Todo:

  • Make statem timeouts configurable
  • Fix A2S.Supervisor startup arguments (currently ignored)
  • Fix Registry static name of :a2s_registry
  • Improve hexdocs, review moduledocs, and readme
    • Explain internals of A2S, design motivations for this library, and a roll-your-own guide.
  • Write proper tests
  • Test with significant concurrent usage
  • Add more typespecs (maybe)