A2S Java - Game Server Protocol API

A comprehensive Java library for querying Valve game servers using the A2S (Application-to-Server) protocol and master server queries.

Features

• Master Server Queries: Retrieve lists of game servers from Valve master servers
• A2S Protocol Support: Query individual game servers for detailed information
• Regional Filtering: Filter servers by geographic region
• Game-Specific Queries: Find servers by Steam App ID
• Rate Limiting: Built-in protection against flooding servers
• Utility Functions: Helper methods for filtering and analyzing server data
• Type Safety: Strongly-typed server information objects
• Exception Handling: Comprehensive error handling with custom exceptions

Architecture

The library is organized into several packages:

de.marcandreher.a2sjava
├── api/ # High-level API classes
├── protocol/ # Low-level protocol implementations
├── exceptions/ # Custom exception classes
├── utils/ # Utility functions
└── examples/ # Usage examples

Core Components

• GameServerAPI: Main high-level API for common operations
• MasterServerClient: Handles master server communication
• A2SClient: Manages A2S protocol queries
• ServerInfo: Immutable data class containing server information
• MasterQueryFilter: Configuration for filtering server queries

Quick Start

Basic Usage

importde.marcandreher.a2sjava.api.GameServerAPI;
importde.marcandreher.a2sjava.protocol.ServerInfo;
// Create API instanceGameServerAPIapi = GameServerAPI.createDefault();
// Get all available serversList<InetSocketAddress> servers = api.getAllServers();
// Query information for specific serversMap<InetSocketAddress, ServerInfo> serverInfo = api.getServersInfo(servers.subList(0, 10));
// Display resultsserverInfo.forEach((address, info) -> {
System.out.println(address + " - " + info.getName() + " (" + info.getPlayers() + "/" + info.getMaxPlayers() + ")");
});

Regional Filtering

importde.marcandreher.a2sjava.protocol.MasterQueryFilter;
// Get European servers onlyList<InetSocketAddress> euServers = api.getServersByRegion(MasterQueryFilter.REGION_EUROPE);
// Get servers for specific game (Counter-Strike: Source)List<InetSocketAddress> csServers = api.getServersByAppId(240);

Advanced Filtering

importde.marcandreher.a2sjava.utils.ServerUtils;
// Filter servers with utilitiesList<InetSocketAddress> activeServers = ServerUtils.filterByMinPlayers(serverInfoMap, 5);
List<InetSocketAddress> publicServers = ServerUtils.filterPublicServers(serverInfoMap);
List<InetSocketAddress> availableServers = ServerUtils.filterNotFull(serverInfoMap);
// Sort by popularityList<InetSocketAddress> popularServers = ServerUtils.sortByPlayerCount(serverInfoMap);

API Reference

GameServerAPI

The main entry point for the library:

• getAllServers(): Get all servers from master server
• getServers(MasterQueryFilter): Get servers with custom filter
• getServerInfo(InetSocketAddress): Get info for a specific server
• getServersInfo(List<InetSocketAddress>): Get info for multiple servers
• getServersByAppId(int): Find servers by Steam App ID
• getServersByRegion(byte): Find servers by region

ServerInfo

Contains detailed information about a game server:

• Basic Info: name, map, game, protocol version
• Player Data: current players, max players, bot count
• Server Details: type, environment (OS), VAC status, password protection
• Extended Data: Steam ID, port, SourceTV information (when available)

MasterQueryFilter

Configure master server queries:

• Regions: REGION_ALL, REGION_US_EAST, REGION_EUROPE, etc.
• Custom Filters: Game directory, app ID, and other criteria
• Factory Methods: createBasicFilter(), forRegion(), custom()

ServerUtils

Utility functions for working with server data:

• Filtering: By player count, game, availability, access
• Sorting: By popularity, name, or custom criteria
• Statistics: Total players, averages, server counts
• Formatting: Human-readable server descriptions

Configuration

Master Servers

The library includes predefined configurations for Valve master servers:

// Default Steam master serverGameServerAPIapi = GameServerAPI.createDefault();
// Custom master serverGameServerAPIapi = newGameServerAPI(newGameServerAPI.ServerConfig("custom-host", 27011));

Timeouts and Rate Limiting

• Socket Timeout: 3 seconds (configurable in client classes)
• Rate Limiting: 50ms default delay between A2S queries
• Custom Delays: Adjustable per query batch

Examples

See the examples package for comprehensive usage examples:

• Basic Queries: Simple server listing and information retrieval
• Game-Specific: Finding servers for particular games
• Regional Analysis: Comparing servers across regions
• Server Monitoring: Tracking server status over time
• Advanced Filtering: Complex server selection criteria

Error Handling

The library uses a hierarchy of custom exceptions:

• GameServerException: Base exception for all errors
• MasterServerException: Master server query failures
• A2SException: A2S protocol errors

All network operations are wrapped in try-catch blocks and return Optional values where appropriate.

Thread Safety

• Immutable Objects: All data classes are immutable
• Stateless Clients: Protocol clients can be safely shared between threads
• No Global State: Each API instance maintains its own configuration

Requirements

• Java 8 or higher
• No external dependencies (uses only standard library)

License

See LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

Support

For issues and questions, please use the GitHub issue tracker.