Results

Understanding results

Home · Result-field reference · Filters

GameQ::process() returns one associative array per server, keyed by the server's explicit id or its resolved address and client port.

$results = $gameQ->process();
$server = $results['main'];

Result layers

A result contains three useful layers:

1. GameQ metadata such as gq_online, address, ports, type, transport, and join link.
2. Normalized fields such as gq_hostname, gq_numplayers, and normalized player keys. These come from the default normalize filter.
3. Protocol-native fields returned by the game server, retained so callers can use information that has no universal equivalent.

[
    'gq_online' => true,
    'gq_type' => 'css',
    'gq_protocol' => 'source',
    'gq_hostname' => 'Example server',
    'gq_numplayers' => 8,
    'gq_maxplayers' => 32,
    'game_id' => 240,
    'players' => [
        ['gq_name' => 'Player', 'gq_score' => 12, 'name' => 'Player', 'score' => 12],
    ],
    'teams' => [],
]

The available protocol-native fields differ by server implementation and even by server version. Application code should use normalized fields for common UI and consult native fields only for protocol-specific features.

Online and offline

gq_online means that GameQ received and parsed a non-empty response. It does not guarantee that players can join, that authentication succeeds, or that every optional query completed.

With normal non-debug processing, a timeout or handled protocol error generally produces an offline-shaped result instead of removing the server:

[
    'gq_online' => false,
    'gq_address' => '192.0.2.10',
    'gq_port_client' => 27015,
    'gq_port_query' => 27015,
    'gq_type' => 'css',
    'gq_protocol' => 'source',
    // normalized fields are null and players/teams are empty
]

Some protocols can return basic information while an optional player, rules, HTTP, or master-list query is unavailable. Test the fields your feature actually needs.

Type versus protocol

• gq_type is the identifier supplied to GameQ, for example css or ut2004.
• gq_protocol is the underlying parser family, for example source.
• gq_name is the human-readable name declared by the selected protocol class.

This distinction is useful when several games share A2S, GameSpy, Quake, Unreal, or RakNet framing.

Players and teams

players and teams are lists of associative arrays when those records are available. Empty lists can mean zero players, a server that does not expose the list, an optional query that was disabled, or a partial response.

Never assume every player contains name, score, ping, and time. Normalize defensively:

foreach ($server['players'] as $player) {
    $name = is_string($player['gq_name'] ?? null)
        ? $player['gq_name']
        : 'Unknown player';

    $score = is_numeric($player['gq_score'] ?? null)
        ? (int) $player['gq_score']
        : null;
}

Encoding and presentation

Text parsed by protocol classes is normalized to UTF-8 where the source protocol requires conversion. Responses are still untrusted network input:

• escape strings for HTML with htmlspecialchars();
• encode JSON with JSON_THROW_ON_ERROR in application code;
• impose UI length limits;
• do not interpret server text as markup, commands, paths, or templates.

See security for public-facing integrations.