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

import de.marcandreher.a2sjava.api.GameServerAPI;
import de.marcandreher.a2sjava.protocol.ServerInfo;

// Create API instance
GameServerAPI api = GameServerAPI.createDefault();

// Get all available servers
List<InetSocketAddress> servers = api.getAllServers();

// Query information for specific servers
Map<InetSocketAddress, ServerInfo> serverInfo = api.getServersInfo(servers.subList(0, 10));

// Display results
serverInfo.forEach((address, info) -> {
    System.out.println(address + " - " + info.getName() + 
                      " (" + info.getPlayers() + "/" + info.getMaxPlayers() + ")");
});

Regional Filtering

import de.marcandreher.a2sjava.protocol.MasterQueryFilter;

// Get European servers only
List<InetSocketAddress> euServers = api.getServersByRegion(MasterQueryFilter.REGION_EUROPE);

// Get servers for specific game (Counter-Strike: Source)
List<InetSocketAddress> csServers = api.getServersByAppId(240);

Advanced Filtering

import de.marcandreher.a2sjava.utils.ServerUtils;

// Filter servers with utilities
List<InetSocketAddress> activeServers = ServerUtils.filterByMinPlayers(serverInfoMap, 5);
List<InetSocketAddress> publicServers = ServerUtils.filterPublicServers(serverInfoMap);
List<InetSocketAddress> availableServers = ServerUtils.filterNotFull(serverInfoMap);

// Sort by popularity
List<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 server
GameServerAPI api = GameServerAPI.createDefault();

// Custom master server
GameServerAPI api = new GameServerAPI(new GameServerAPI.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.