Result Fields

Normalized result fields

Home · Understanding results · Filters

GameQ retains protocol-native fields and adds common fields with the gq_ prefix. Consumers should prefer these fields for cross-game features.

Always-added metadata

These keys are added by the query pipeline even when a server is offline:

Field	Typical type	Meaning
gq_online	bool	A non-empty protocol response was parsed successfully.
gq_address	string	Resolved IP address queried by GameQ.
gq_port_client	int	Client/connect port supplied in host.
gq_port_query	int	Calculated or explicitly configured query port.
gq_protocol	string	Underlying protocol family, such as source or gamespy3.
gq_type	string	Selected GameQ identifier, such as css or ut2004.
gq_name	string	Human-readable name declared by the protocol class.
gq_transport	string|null	Native query transport such as udp, tcp, tls, or ssl.
gq_joinlink	string	Protocol-specific join URI where supported, otherwise an empty string.

gq_online describes query success, not gameplay health or joinability.

Default normalized server fields

The default normalize filter adds the fields a protocol knows how to map:

Field	Typical type	Meaning
gq_dedicated	bool|int|null	Dedicated/listen-server indicator.
gq_gametype	string|null	Game mode or game type.
gq_hostname	string|null	Display name reported by the server.
gq_mapname	string|null	Current map or world.
gq_maxplayers	int|string|null	Maximum player capacity.
gq_mod	string|null	Mod, game directory, or variant.
gq_numplayers	int|string|null	Current player count.
gq_password	bool|int|string|null	Password/protection indicator.
players	list<array<string, mixed>>	Player records, or an empty list.
teams	list<array<string, mixed>>	Team records, or an empty list.

Older protocols often encode numbers and booleans as strings. Normalize values in the consuming application before strict display or arithmetic:

$playerCount = is_numeric($server['gq_numplayers'] ?? null)
    ? (int) $server['gq_numplayers']
    : null;

Normalized player and team keys

Where the selected protocol supplies matching source fields, player entries can contain:

• gq_name
• gq_kills
• gq_deaths
• gq_score
• gq_ping

Team entries can contain:

• gq_name
• gq_score

These are additions. Original protocol keys such as name, score, ping, or protocol-specific statistics remain available.

Optional filter fields

The secondstohuman filter creates gq_<source-key>_human, for example:

[
    'time' => 3723.8,
    'gq_time_human' => '01:02:03',
]

Protocol-native data

Native keys are intentionally not standardized. Depending on the selected family, they can include Source rules, GameSpy or Quake cvars, Unreal metadata, Frostbite data, Minecraft plugins, TeamSpeak clients and channels, or fields supplied by an HTTP API, query plugin, or master list.

When building a protocol-specific feature:

1. capture representative results from several server versions;
2. handle missing keys and differing scalar types;
3. keep normalized fields as the fallback;
4. escape all server-provided strings for their output context;
5. add fixture-backed tests if the application relies on a previously undocumented field.