samp_query

A dependency-free Dart implementation of the SA-MP / Open.MP UDP query protocol.

samp_query lets Dart and Flutter applications query SA-MP and Open.MP server metadata using pure Dart UDP sockets.

Features

• Server information: hostname, game mode, language, player counts, password state
• Server rules as Map<String, String>
• Compact player list
• Detailed player list with ids and ping values
• Protocol ping using the official four-byte challenge echo
• Per-query timeout handling
• Pure Dart networking with RawDatagramSocket

Installation

Add the package to your pubspec.yaml:

dependencies:
  samp_query: ^0.1.0

Then import it:

import 'package:samp_query/samp_query.dart';

Platform Support

Platform	Supported
Android	✅
iOS	✅
Windows	✅
macOS	✅
Linux	✅
Web	❌

❌ Web is not supported because the query protocol relies on raw UDP sockets from dart:io, which are unavailable in browsers.

Basic Usage

final query = SampQuery();

final info = await query.info('51.68.12.34', 7777);

print(info.hostname);
print('${info.players}/${info.maxPlayers}');

SampQuery Methods

All methods create a UDP socket for a single request, wait for one response, parse it, and close the socket. Each method accepts the same target parameters:

Parameter	Type	Description
host	String	Server IP address or hostname. The client resolves it to IPv4 before sending the query packet.
port	int	Server query port. SA-MP and Open.MP servers commonly use 7777.

Method	Returns	Fetches	Usage
info(host, port)	Future<ServerInfo>	Basic server metadata: hostname, game mode, language, current players, max players, and password state.	final info = await query.info('51.68.12.34', 7777);
rules(host, port)	Future<Map<String, String>>	Server rules as key/value pairs, such as weburl, gravity, mapname, or custom rule values exposed by the server.	final rules = await query.rules('51.68.12.34', 7777);
players(host, port)	Future<List<Player>>	Compact player list with each player's name and score.	final players = await query.players('51.68.12.34', 7777);
detailedPlayers(host, port)	Future<List<DetailedPlayer>>	Detailed player list with player id, name, score, and ping in milliseconds.	final detailed = await query.detailedPlayers('51.68.12.34', 7777);
ping(host, port)	Future<Duration>	Round-trip latency measured with the protocol ping challenge.	final ping = await query.ping('51.68.12.34', 7777);

Exceptions

Exception	When It Is Thrown	Typical Cause
SampTimeoutException	A server does not respond before the configured timeout.	Server is offline, UDP traffic is blocked, wrong host/port, or timeout is too short.
SampProtocolException	A query cannot be completed because of a protocol or socket-level problem.	Invalid port, IPv6-only address, DNS/socket failure, or unsupported query target.
SampInvalidPacketException	A server response is malformed or does not match the expected query packet.	Truncated packet, invalid SAMP signature, mismatched opcode, mismatched address/port, or malformed response body.

API Example

final query = SampQuery();

final info = await query.info('51.68.12.34', 7777);
final rules = await query.rules('51.68.12.34', 7777);
final players = await query.players('51.68.12.34', 7777);
final detailedPlayers = await query.detailedPlayers('51.68.12.34', 7777);
final ping = await query.ping('51.68.12.34', 7777);

Timeout Configuration

The default timeout is 5 seconds. Configure it when creating the client:

final query = SampQuery(
  timeout: Duration(seconds: 10),
);

Timeouts throw SampTimeoutException.

Example Output

Hostname: open.mp Server
Gamemode: Freeroam
Language: English
Players: 42
Max Players: 100

Rules:
weburl: open.mp
gravity: 0.008

Players:
Alice: 1500
Bob: 900

Detailed Players:
#0 Alice: score=1500, ping=64ms
#1 Bob: score=900, ping=91ms

Ping: 52ms

Known Limitations

• Only IPv4 query packets are supported, matching the SA-MP query packet format.
• RCON is not implemented.
• Web is not supported.
• Each query opens a UDP socket, sends one packet, waits for one response, and closes the socket.

License

MIT. See LICENSE.