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)