View Source Elixir 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
[
{:elixir_a2s, "~> 0.2.5"}
]
end
Documentation is available on HexDocs and may also be generated with ExDoc.
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 Using A2S Directly guide for further details.
configuration
Configuration
The following configuration options are available for A2S.Client
:
:name
- Required, used as the name
of the top-level supervisor for A2S.Client
:port
- Port on which to open the UDP socket for communicating with game servers. Defaults to 20850
.
:idle_timeout
- Under the hood, A2S.Client
spins up one :gen_statem
processes per address queried. These serve two purposes - to handle all the hand-shaking and packet wrangling necessary to complete A2S queries, and to ensure queries are executed sequentially. After an address hasn't been queried for an extended period, these processes should terminate to free their memory. Defaults to 120_000
(2 minutes, expressed in milliseconds).
:recv_timeout
- Deadline to receive a response packet for each packet sent in the query sequence. Defaults to 3000
(3 seconds, expressed in milliseconds).
unsupported-games-features
Unsupported Games/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.
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)