### Install CraftPing

Source: https://github.com/aternosorg/craftping/blob/master/README.md

Install the craftping library using npm.

```bash
npm i craftping
```

--------------------------------

### Query Basic and Full Server Info

Source: https://github.com/aternosorg/craftping/blob/master/README.md

Use the Query protocol to get basic or full server statistics. Ensure the server has 'enable-query' set to true in server.properties. The client must be closed manually.

```javascript
import {QueryClient} from 'craftping';

let client = new QueryClient();

let basic = await client.queryBasic('localhost', 25565, AbortSignal.timeout(5000));
let full = await client.queryFull('localhost', 25565, AbortSignal.timeout(5000));

await client.close();
```

--------------------------------

### Query Protocol

Source: https://github.com/aternosorg/craftping/blob/master/README.md

Use the Query protocol to get basic or full information about a Minecraft server. Requires `enable-query` to be true in `server.properties`. Handles potential string encoding issues.

```APIDOC
## Query Protocol

### Description
Allows retrieving basic or full server information using the UDP-based Query protocol. Servers must have `enable-query` set to `true` in `server.properties` to respond.

### Client Initialization
```js
import {QueryClient} from 'craftping';

let client = new QueryClient();
```

### Basic Query
Retrieves basic server information.

```js
let basic = await client.queryBasic('localhost', 25565, AbortSignal.timeout(5000));
```

### Full Query
Retrieves detailed server information, including the player list.

```js
let full = await client.queryFull('localhost', 25565, AbortSignal.timeout(5000));
```

### Closing the Client
Manually close the client to release the UDP socket.

```js
await client.close();
```

### String Encoding Options
Control string encoding (UTF-8 or ISO-8859-1) for query responses. `null` attempts auto-detection.

```js
let useLegacyStringEncoding = true; // true, false, or null
let basic = await client.queryBasic('localhost', 25565, AbortSignal.timeout(5000), useLegacyStringEncoding);
let full = await client.queryFull('localhost', 25565, AbortSignal.timeout(5000), useLegacyStringEncoding);
```
```

--------------------------------

### Initialize JavaPingClient

Source: https://github.com/aternosorg/craftping/blob/master/README.md

Instantiate the JavaPingClient to query Java Edition servers. SRV record resolution can be enabled via options.

```javascript
import {JavaPingClient} from 'craftping';

let client = new JavaPingClient();
```

--------------------------------

### QueryClient.queryFull

Source: https://context7.com/aternosorg/craftping/llms.txt

Sends a UDP Query full stat request and returns a FullStatResponse, including player lists and version info. The client must be closed manually.

```APIDOC
## `QueryClient.queryFull(address, port, signal, useLegacyStringEncoding)` — Full Query stat

Sends a UDP Query full stat request and returns a `FullStatResponse`. In addition to the basic stat fields, it includes the complete online player list (all usernames), server version, plugin info, game ID, and encoding-aware string decoding. Encoding is auto-detected from the `version` field (UTF-8 from 1.21.11+, ISO-8859-1 before).

### Parameters
#### Path Parameters
- `address` (string) - Required - The server address.
- `port` (number) - Required - The server port.
- `signal` (AbortSignal) - Required - An AbortSignal to cancel the request.
- `useLegacyStringEncoding` (boolean | null) - Optional - Determines string encoding. `true` forces ISO-8859-1, `false` forces UTF-8, `null` auto-detects. Defaults to `null`.

### Request Example
```js
import { QueryClient } from 'craftping';

const client = new QueryClient();

try {
  const full = await client.queryFull('mc.example.com', 25565, AbortSignal.timeout(5000));

  console.log('MOTD:', full.getHostname());
  console.log('Version:', full.getVersion());
  console.log('Game ID:', full.getGameId());
  console.log('Plugins:', full.getPlugins());
  console.log('Map:', full.getMap());
  console.log('Players:', full.getNumplayers(), '/', full.getMaxplayers());

  const players = full.getPlayers();
  console.log('Online players:', players);
} finally {
  await client.close();
}
```

### Response
#### Success Response (`FullStatResponse` object)
- `getHostname()`: Returns the server's MOTD.
- `getVersion()`: Returns the server version (e.g., '1.21.1').
- `getGameId()`: Returns the game ID (e.g., 'MINECRAFT').
- `getPlugins()`: Returns plugin information (e.g., 'CraftBukkit: Plugin1; Plugin2').
- `getMap()`: Returns the map name.
- `getNumplayers()`: Returns the current number of players.
- `getMaxplayers()`: Returns the maximum number of players.
- `getPlayers()`: Returns an array of all online player usernames.

### Closing the Client
- `client.close()`: Must be called to release the UDP socket when no longer needed.
```

--------------------------------

### QueryClient.queryBasic

Source: https://context7.com/aternosorg/craftping/llms.txt

Sends a UDP Query basic stat request and returns a BasicStatResponse. The server must have enable-query enabled. The client must be closed manually.

```APIDOC
## `QueryClient.queryBasic(address, port, signal, useLegacyStringEncoding)` — Basic Query stat

Sends a UDP Query basic stat request (after an automatic handshake) and returns a `BasicStatResponse`. Returns MOTD, game type, map name, player counts, host IP, and host port. The server must have `enable-query=true` in `server.properties`. The client keeps its UDP socket open and **must be closed manually**.

### Parameters
#### Path Parameters
- `address` (string) - Required - The server address.
- `port` (number) - Required - The server port.
- `signal` (AbortSignal) - Required - An AbortSignal to cancel the request.
- `useLegacyStringEncoding` (boolean | null) - Optional - Determines string encoding. `true` forces ISO-8859-1, `false` forces UTF-8, `null` auto-detects. Defaults to `null`.

### Request Example
```js
import { QueryClient } from 'craftping';

const client = new QueryClient();

try {
  const basic = await client.queryBasic('mc.example.com', 25565, AbortSignal.timeout(5000), null);

  console.log('MOTD:', basic.getHostname());
  console.log('Game type:', basic.getGametype());
  console.log('Map:', basic.getMap());
  console.log('Players:', basic.getNumplayers(), '/', basic.getMaxplayers());
  console.log('Host IP:', basic.getHostip());
  console.log('Host port:', basic.getHostport());
} finally {
  await client.close();
}
```

### Response
#### Success Response (`BasicStatResponse` object)
- `getHostname()`: Returns the server's MOTD.
- `getGametype()`: Returns the game type (e.g., 'SMP').
- `getMap()`: Returns the map name (e.g., 'world').
- `getNumplayers()`: Returns the current number of players.
- `getMaxplayers()`: Returns the maximum number of players.
- `getHostip()`: Returns the host IP address.
- `getHostport()`: Returns the host port.

### Closing the Client
- `client.close()`: Must be called to release the UDP socket when no longer needed.
```

--------------------------------

### JavaPingClient.pingLegacyPost14(address, port, options)

Source: https://context7.com/aternosorg/craftping/llms.txt

Sends the 1.4–1.6 legacy Server List Ping over TCP. Returns a LegacyStatus object with MOTD, player counts, and version information.

```APIDOC
## JavaPingClient.pingLegacyPost14(address, port, options) — Legacy Java Edition ping (1.4–1.6)

### Description
Sends the 1.4–1.6 legacy Server List Ping over TCP and returns a `LegacyStatus` object. Use this for servers running Minecraft versions between beta 1.4 and 1.6.x (inclusive). The response includes the server version name and numeric protocol version, in addition to MOTD and player counts.

### Method
POST

### Endpoint
`/pingLegacyPost14`

### Parameters
#### Path Parameters
- **address** (string) - Required - The hostname or IP address of the server.
- **port** (number) - Required - The port the server is listening on.
- **options** (object) - Optional - Configuration options for the ping.
  - **signal** (AbortSignal) - Optional - An AbortSignal to cancel the request.

### Request Example
```javascript
import { JavaPingClient } from 'craftping';

const client = new JavaPingClient();

const status = await client.pingLegacyPost14('mc.example.com', 25565, {
  signal: AbortSignal.timeout(5000),
});

// LegacyStatus fields
console.log('MOTD:', status.getMotd());                // e.g. "A Minecraft Server"
console.log('Version:', status.getServerVersion());    // e.g. "1.6.4"
console.log('Protocol:', status.getProtocolVersion()); // e.g. 78
console.log('Players:', status.getPlayerCount(), '/', status.getMaxPlayers());
```

### Response
#### Success Response (200)
- **status** (LegacyStatus) - An object containing legacy server status information.
  - **getMotd()**: Returns the server's MOTD.
  - **getServerVersion()**: Returns the server version name.
  - **getProtocolVersion()**: Returns the numeric protocol version.
  - **getPlayerCount()**: Returns the current number of players online.
  - **getMaxPlayers()**: Returns the maximum number of players allowed.

#### Response Example
```json
{
  "motd": "A Minecraft Server",
  "version": "1.6.4",
  "protocol": 78,
  "players": 42,
  "maxPlayers": 100
}
```
```

--------------------------------

### Ping Any Minecraft Server (Beta 1.8 - 1.3)

Source: https://github.com/aternosorg/craftping/blob/master/README.md

Use pingLegacyPre14 for older versions (beta 1.8 to release 1.3) or as a fallback for any server, as newer versions are generally backwards compatible.

```javascript
let response = await client.pingLegacyPre14('localhost', 25565, {signal: AbortSignal.timeout(5000)});
```

--------------------------------

### JavaPingClient.ping(address, port, options)

Source: https://context7.com/aternosorg/craftping/llms.txt

Sends a modern Server List Ping (1.7+) over TCP. Returns a JsonStatus object with detailed server information.

```APIDOC
## JavaPingClient.ping(address, port, options) — Modern Java Edition ping (1.7+)

### Description
Sends a modern Server List Ping over TCP and returns a `JsonStatus` object. This is the primary method for pinging any Minecraft Java server version 1.7 or newer. Accepts an optional `PingOptions` object supporting `signal` (AbortSignal), `resolveSrvRecords`, `protocolVersion`, `hostname`, `port`, and `resolver` fields.

### Method
POST

### Endpoint
`/ping`

### Parameters
#### Path Parameters
- **address** (string) - Required - The hostname or IP address of the server.
- **port** (number) - Required - The port the server is listening on.
- **options** (object) - Optional - Configuration options for the ping.
  - **signal** (AbortSignal) - Optional - An AbortSignal to cancel the request.
  - **resolveSrvRecords** (boolean) - Optional - Whether to resolve SRV records.
  - **protocolVersion** (number) - Optional - The protocol version to use for the ping.
  - **hostname** (string) - Optional - The hostname to use in the ping request.
  - **port** (number) - Optional - The port to use in the ping request if different from the main port.
  - **resolver** (object) - Optional - A custom DNS resolver.

### Request Example
```javascript
import { JavaPingClient, NetworkError, ProtocolError } from 'craftping';

const client = new JavaPingClient();

try {
  const status = await client.ping('mc.example.com', 25565, {
    signal: AbortSignal.timeout(5000),
    resolveSrvRecords: true, // resolve _minecraft._tcp SRV records
  });

  // JsonStatus fields
  const version = status.getVersion();
  console.log('Server version:', version.getName());    // e.g. "1.21.1"
  console.log('Protocol:', version.getProtocol());     // e.g. 767

  const players = status.getPlayers();
  console.log('Online:', players.getOnline());          // e.g. 42
  console.log('Max:', players.getMax());                // e.g. 100
  players.getSample().forEach(p => {
    console.log(' -', p.getName(), p.getId());          // name + UUID
  });

  console.log('MOTD:', status.getDescription());        // Minecraft Text Component object
  console.log('Favicon:', status.getFavicon());         // "data:image/png;base64,வைக்" or null
} catch (e) {
  if (e instanceof NetworkError) console.error('Network error:', e.message);
  if (e instanceof ProtocolError) console.error('Protocol error:', e.message);
}
```

### Response
#### Success Response (200)
- **status** (JsonStatus) - An object containing server status information.
  - **getVersion()**: Returns version information (name and protocol).
  - **getPlayers()**: Returns player information (online count, max count, and sample list).
  - **getDescription()**: Returns the server's MOTD.
  - **getFavicon()**: Returns the server's favicon as a base64 data URI or null.

#### Response Example
```json
{
  "version": {
    "name": "1.21.1",
    "protocol": 767
  },
  "players": {
    "online": 42,
    "max": 100,
    "sample": [
      {
        "name": "Player1",
        "id": "uuid1"
      }
    ]
  },
  "description": {"text": "A Minecraft Server"},
  "favicon": "data:image/png;base64,iVBORw0KGgo..."
}
```
```

--------------------------------

### Query Basic Java Server Stats

Source: https://context7.com/aternosorg/craftping/llms.txt

Sends a UDP Query basic stat request to a Java server. Requires 'enable-query=true' in server.properties. The client must be closed manually.

```javascript
import { QueryClient } from 'craftping';

const client = new QueryClient();

try {
  // useLegacyStringEncoding: true = force ISO-8859-1, false = force UTF-8, null = auto-detect
  const basic = await client.queryBasic('mc.example.com', 25565, AbortSignal.timeout(5000), null);

  console.log('MOTD:', basic.getHostname());        // server MOTD
  console.log('Game type:', basic.getGametype());   // e.g. "SMP"
  console.log('Map:', basic.getMap());              // e.g. "world"
  console.log('Players:', basic.getNumplayers(), '/', basic.getMaxplayers());
  console.log('Host IP:', basic.getHostip());
  console.log('Host port:', basic.getHostport());
} finally {
  await client.close();
}
```

--------------------------------

### JavaPingClient.pingLegacyUniversal

Source: https://context7.com/aternosorg/craftping/llms.txt

Attempts to ping a Java Edition server using a hybrid approach compatible with pre-1.4 and 1.4–1.6 protocols. It returns a LegacyStatus object.

```APIDOC
## `JavaPingClient.pingLegacyUniversal(address, port, options)` — Universal legacy ping

Attempts to ping a server using a hybrid approach that works for both pre-1.4 servers and servers that only support the 1.4–1.6 protocol (e.g., Better Than Adventure). It sends the first byte of the pre-1.4 request, waits up to 500 ms for a response, and falls back to the 1.4+ format if there is no reply. Returns a `LegacyStatus` object.

### Parameters
#### Path Parameters
- `address` (string) - Required - The server address.
- `port` (number) - Required - The server port.
- `options` (object) - Optional - Configuration options.
  - `signal` (AbortSignal) - Optional - An AbortSignal to cancel the request.
  - `pingType` (string) - Optional - The type of ping to send. Defaults to 'MC|PingHost'.

### Request Example
```js
import { JavaPingClient } from 'craftping';

const client = new JavaPingClient();

const status = await client.pingLegacyUniversal('mc.example.com', 25565, {
  signal: AbortSignal.timeout(8000),
  pingType: 'MC|PingHost',
});

console.log('MOTD:', status.getMotd());
console.log('Players:', status.getPlayerCount(), '/', status.getMaxPlayers());
console.log('Version:', status.getServerVersion() ?? '(pre-1.4, not available)');
```

### Response
#### Success Response (`LegacyStatus` object)
- `getMotd()`: Returns the server's Message of the Day.
- `getPlayerCount()`: Returns the current number of players.
- `getMaxPlayers()`: Returns the maximum number of players.
- `getServerVersion()`: Returns the server version (available for post-1.4 responses).
- `getProtocolVersion()`: Returns the protocol version (available for post-1.4 responses).

### Response Example
```js
// Assuming a successful response for a post-1.4 server
console.log('MOTD:', status.getMotd()); // e.g., 'A Minecraft Server'
console.log('Players:', status.getPlayerCount(), '/', status.getMaxPlayers()); // e.g., '10 / 20'
console.log('Version:', status.getServerVersion()); // e.g., '1.19.4'

// Assuming a successful response for a pre-1.4 server
console.log('MOTD:', status.getMotd()); // e.g., 'A Minecraft Server'
console.log('Players:', status.getPlayerCount(), '/', status.getMaxPlayers()); // e.g., '5 / 10'
console.log('Version:', status.getServerVersion() ?? '(pre-1.4, not available)'); // '(pre-1.4, not available)'
```
```

--------------------------------

### JavaPingClient.pingLegacyPre14(address, port, options)

Source: https://context7.com/aternosorg/craftping/llms.txt

Sends the oldest Server List Ping protocol (pre-1.4) over TCP. Returns a LegacyStatus object with MOTD and player counts, but no version information.

```APIDOC
## JavaPingClient.pingLegacyPre14(address, port, options) — Legacy Java Edition ping (pre-1.4)

### Description
Sends the oldest Server List Ping protocol (Minecraft beta 1.8 – release 1.3) and returns a `LegacyStatus` object. The pre-1.4 response does **not** include server version name or protocol version; those fields will be `null`. This protocol is also accepted by all newer server versions as a fallback.

### Method
POST

### Endpoint
`/pingLegacyPre14`

### Parameters
#### Path Parameters
- **address** (string) - Required - The hostname or IP address of the server.
- **port** (number) - Required - The port the server is listening on.
- **options** (object) - Optional - Configuration options for the ping.
  - **signal** (AbortSignal) - Optional - An AbortSignal to cancel the request.

### Request Example
```javascript
import { JavaPingClient } from 'craftping';

const client = new JavaPingClient();

const status = await client.pingLegacyPre14('mc.example.com', 25565, {
  signal: AbortSignal.timeout(5000),
});

console.log('MOTD:', status.getMotd());                // e.g. "A Minecraft Server"
console.log('Players:', status.getPlayerCount(), '/', status.getMaxPlayers());
console.log('Version:', status.getServerVersion());    // null (not available pre-1.4)
console.log('Protocol:', status.getProtocolVersion()); // null (not available pre-1.4)
```

### Response
#### Success Response (200)
- **status** (LegacyStatus) - An object containing legacy server status information.
  - **getMotd()**: Returns the server's MOTD.
  - **getPlayerCount()**: Returns the current number of players online.
  - **getMaxPlayers()**: Returns the maximum number of players allowed.
  - **getServerVersion()**: Returns null (not available for this protocol).
  - **getProtocolVersion()**: Returns null (not available for this protocol).

#### Response Example
```json
{
  "motd": "A Minecraft Server",
  "players": 42,
  "maxPlayers": 100,
  "version": null,
  "protocol": null
}
```
```

--------------------------------

### Ping Multiple Servers Concurrently

Source: https://context7.com/aternosorg/craftping/llms.txt

Utilize `Promise.allSettled` to ping multiple servers concurrently. `BedrockPingClient` and `QueryClient` efficiently reuse a single UDP socket for all concurrent requests.

```javascript
import { JavaPingClient, BedrockPingClient, QueryClient } from 'craftping';

const javaClient = new JavaPingClient();
const bedrockClient = new BedrockPingClient();
const queryClient = new QueryClient();

const servers = [
  { host: 'java1.example.com', port: 25565 },
  { host: 'java2.example.com', port: 25566 },
  { host: 'bedrock.example.com', port: 19132, bedrock: true },
];

const signal = AbortSignal.timeout(5000);

const results = await Promise.allSettled([
  javaClient.ping('java1.example.com', 25565, { signal }),
  javaClient.ping('java2.example.com', 25566, { signal }),
  bedrockClient.ping('bedrock.example.com', 19132, signal),
  queryClient.queryFull('java1.example.com', 25565, signal),
]);

for (const [i, result] of results.entries()) {
  if (result.status === 'fulfilled') {
    console.log(`Server ${i}: online`);
  } else {
    console.log(`Server ${i}: offline —`, result.reason.message);
  }
}

await bedrockClient.close();
await queryClient.close();
```

--------------------------------

### Query Full Java Server Stats

Source: https://context7.com/aternosorg/craftping/llms.txt

Sends a UDP Query full stat request to a Java server, including player list and version info. Encoding is auto-detected. The client must be closed manually.

```javascript
import { QueryClient } from 'craftping';

const client = new QueryClient();

try {
  const full = await client.queryFull('mc.example.com', 25565, AbortSignal.timeout(5000));

  console.log('MOTD:', full.getHostname());
  console.log('Version:', full.getVersion());          // e.g. "1.21.1"
  console.log('Game ID:', full.getGameId());           // e.g. "MINECRAFT"
  console.log('Plugins:', full.getPlugins());          // e.g. "CraftBukkit: Plugin1; Plugin2"
  console.log('Map:', full.getMap());
  console.log('Players:', full.getNumplayers(), '/', full.getMaxplayers());

  // Full player list (all online players, not just a sample)
  const players = full.getPlayers();
  console.log('Online players:', players);             // e.g. ["Steve", "Alex", "Notch"]
} finally {
  await client.close();
}
```

--------------------------------

### Ping Legacy Java Edition Server (pre-1.4)

Source: https://context7.com/aternosorg/craftping/llms.txt

Use pingLegacyPre14 to send the oldest Server List Ping protocol (Minecraft beta 1.8 – release 1.3) over TCP. This method is for older Minecraft versions. The response does not include server version name or protocol version, returning null for those fields.

```javascript
import { JavaPingClient } from 'craftping';

const client = new JavaPingClient();

const status = await client.pingLegacyPre14('mc.example.com', 25565, {
  signal: AbortSignal.timeout(5000),
});

console.log('MOTD:', status.getMotd());                // e.g. "A Minecraft Server"
console.log('Players:', status.getPlayerCount(), '/', status.getMaxPlayers());
console.log('Version:', status.getServerVersion());    // null (not available pre-1.4)
console.log('Protocol:', status.getProtocolVersion()); // null (not available pre-1.4)
```

--------------------------------

### Force Query String Encoding

Source: https://github.com/aternosorg/craftping/blob/master/README.md

Manually set the string encoding for query responses. Use 'true' for ISO-8859-1, 'false' for UTF-8, or 'null' for automatic detection. This is useful when the server version is unknown or response packets are malformed.

```javascript
let useLegacyStringEncoding = true; // true, false, or null
let basic = await client.queryBasic('localhost', 25565, AbortSignal.timeout(5000), useLegacyStringEncoding);
let full = await client.queryFull('localhost', 25565, AbortSignal.timeout(5000), useLegacyStringEncoding);
```

--------------------------------

### Ping Legacy Java Edition Server (1.4–1.6)

Source: https://context7.com/aternosorg/craftping/llms.txt

Use pingLegacyPost14 to send the 1.4–1.6 legacy Server List Ping over TCP. This method is for Minecraft versions between beta 1.4 and 1.6.x. The response includes MOTD, player counts, server version name, and numeric protocol version.

```javascript
import { JavaPingClient } from 'craftping';

const client = new JavaPingClient();

const status = await client.pingLegacyPost14('mc.example.com', 25565, {
  signal: AbortSignal.timeout(5000),
});

// LegacyStatus fields
console.log('MOTD:', status.getMotd());                // e.g. "A Minecraft Server"
console.log('Version:', status.getServerVersion());    // e.g. "1.6.4"
console.log('Protocol:', status.getProtocolVersion()); // e.g. 78
console.log('Players:', status.getPlayerCount(), '/', status.getMaxPlayers());
```

--------------------------------

### Ping Legacy Universal Java Server

Source: https://github.com/aternosorg/craftping/blob/master/README.md

Use this method to ping Java Edition servers that might not support pre-1.4 ping versions. It includes a timeout for the request.

```javascript
let response = await client.pingLegacyUniversal('localhost', 25565, {signal: AbortSignal.timeout(5000)});
```

--------------------------------

### Ping Legacy Universal Java Server

Source: https://context7.com/aternosorg/craftping/llms.txt

Pings a Java server using a hybrid approach for pre-1.4 and 1.4-1.6 protocols. Requires AbortSignal for timeout.

```javascript
import { JavaPingClient } from 'craftping';

const client = new JavaPingClient();

const status = await client.pingLegacyUniversal('mc.example.com', 25565, {
  signal: AbortSignal.timeout(8000),
  pingType: 'MC|PingHost', // optional, defaults to LegacyPingHostPluginMessage.DEFAULT_TYPE
});

console.log('MOTD:', status.getMotd());
console.log('Players:', status.getPlayerCount(), '/', status.getMaxPlayers());
// serverVersion / protocolVersion present only if post-1.4 response was received
console.log('Version:', status.getServerVersion() ?? '(pre-1.4, not available)');
```

--------------------------------

### Ping Bedrock Edition Server

Source: https://context7.com/aternosorg/craftping/llms.txt

Pings a Bedrock Edition server using RakNet UDP. The client must be closed manually to release the UDP socket. Handles NetworkError.

```javascript
import { BedrockPingClient, NetworkError } from 'craftping';

const client = new BedrockPingClient();

try {
  const pong = await client.ping('bedrock.example.com', 19132, AbortSignal.timeout(5000));

  console.log('Edition:', pong.getEdition());              // "MCPE" or "MCEE"
  console.log('MOTD line 1:', pong.getMotdLine1());        // Server name
  console.log('MOTD line 2:', pong.getMotdLine2());        // World/sub-title
  console.log('Version:', pong.getVersionName());          // e.g. "1.21.0"
  console.log('Protocol:', pong.getProtocolVersion());     // e.g. 671
  console.log('Players:', pong.getPlayerCount(), '/', pong.getMaxPlayerCount());
  console.log('Game mode:', pong.getGameMode());           // e.g. "Survival"
  console.log('Server GUID:', pong.getServerGUID());       // BigInt
  console.log('IPv4 port:', pong.getIpv4Port());           // number or null
  console.log('IPv6 port:', pong.getIpv6Port());           // number or null
} catch (e) {
  if (e instanceof NetworkError) console.error('Network error:', e.message);
} finally {
  await client.close(); // always close to release the UDP socket
}
```

--------------------------------

### Ping Modern Java Edition Server (1.7+)

Source: https://context7.com/aternosorg/craftping/llms.txt

Use JavaPingClient to send a modern Server List Ping over TCP. This method is suitable for Minecraft Java servers version 1.7 and newer. It supports AbortSignal for timeouts and SRV record resolution.

```javascript
import { JavaPingClient, NetworkError, ProtocolError } from 'craftping';

const client = new JavaPingClient();

try {
  const status = await client.ping('mc.example.com', 25565, {
    signal: AbortSignal.timeout(5000),
    resolveSrvRecords: true, // resolve _minecraft._tcp SRV records
  });

  // JsonStatus fields
  const version = status.getVersion();
  console.log('Server version:', version.getName());    // e.g. "1.21.1"
  console.log('Protocol:', version.getProtocol());     // e.g. 767

  const players = status.getPlayers();
  console.log('Online:', players.getOnline());          // e.g. 42
  console.log('Max:', players.getMax());                // e.g. 100
  players.getSample().forEach(p => {
    console.log(' -', p.getName(), p.getId());          // name + UUID
  });

  console.log('MOTD:', status.getDescription());        // Minecraft Text Component object
  console.log('Favicon:', status.getFavicon());         // "data:image/png;base64,..." or null
} catch (e) {
  if (e instanceof NetworkError) console.error('Network error:', e.message);
  if (e instanceof ProtocolError) console.error('Protocol error:', e.message);
}
```

--------------------------------

### Handle Network and Protocol Errors

Source: https://context7.com/aternosorg/craftping/llms.txt

Use a try-catch block to handle `NetworkError` for socket issues and `ProtocolError` for server response problems. Also, catch `AbortError` or `TimeoutError` for request timeouts.

```javascript
import { JavaPingClient, BedrockPingClient, QueryClient, NetworkError, ProtocolError } from 'craftping';

async function safePing(host, port) {
  const client = new JavaPingClient();
  try {
    const status = await client.ping(host, port, { signal: AbortSignal.timeout(3000) });
    return { ok: true, motd: status.getDescription(), players: status.getPlayers().getOnline() };
  } catch (e) {
    if (e instanceof NetworkError) {
      return { ok: false, reason: 'network', message: e.message };
    }
    if (e instanceof ProtocolError) {
      return { ok: false, reason: 'protocol', message: e.message };
    }
    if (e.name === 'AbortError' || e.name === 'TimeoutError') {
      return { ok: false, reason: 'timeout', message: 'Request timed out' };
    }
    throw e; // unexpected error
  }
}

console.log(await safePing('mc.example.com', 25565));
// { ok: true, motd: { text: 'Welcome!' }, players: 5 }
// or { ok: false, reason: 'timeout', message: 'Request timed out' }
```

--------------------------------

### Ping Bedrock Edition Server

Source: https://github.com/aternosorg/craftping/blob/master/README.md

Pings a Bedrock Edition server and returns an UnconnectedPong object. Remember to close the client manually after use as it keeps a UDP socket open.

```javascript
import {BedrockPingClient} from 'craftping';

let client = new BedrockPingClient();

let status = await client.ping('localhost', 19132, AbortSignal.timeout(5000));

await client.close();
```

--------------------------------

### BedrockPingClient.ping

Source: https://context7.com/aternosorg/craftping/llms.txt

Pings a Minecraft Bedrock Edition server using the RakNet UDP Unconnected Ping packet and returns an UnconnectedPong object. The client must be closed manually.

```APIDOC
## `BedrockPingClient.ping(address, port, signal)` — Bedrock Edition ping

Pings a Minecraft Bedrock (PE/MCPE/MCBE) server using the RakNet UDP Unconnected Ping packet and returns an `UnconnectedPong` object. The `BedrockPingClient` reuses a single UDP socket across multiple calls and **must be closed manually** when no longer needed.

### Parameters
#### Path Parameters
- `address` (string) - Required - The server address.
- `port` (number) - Required - The server port.
- `signal` (AbortSignal) - Required - An AbortSignal to cancel the request.

### Request Example
```js
import { BedrockPingClient, NetworkError } from 'craftping';

const client = new BedrockPingClient();

try {
  const pong = await client.ping('bedrock.example.com', 19132, AbortSignal.timeout(5000));

  console.log('Edition:', pong.getEdition());
  console.log('MOTD line 1:', pong.getMotdLine1());
  console.log('MOTD line 2:', pong.getMotdLine2());
  console.log('Version:', pong.getVersionName());
  console.log('Protocol:', pong.getProtocolVersion());
  console.log('Players:', pong.getPlayerCount(), '/', pong.getMaxPlayerCount());
  console.log('Game mode:', pong.getGameMode());
  console.log('Server GUID:', pong.getServerGUID());
  console.log('IPv4 port:', pong.getIpv4Port());
  console.log('IPv6 port:', pong.getIpv6Port());
} catch (e) {
  if (e instanceof NetworkError) console.error('Network error:', e.message);
} finally {
  await client.close(); // always close to release the UDP socket
}
```

### Response
#### Success Response (`UnconnectedPong` object)
- `getEdition()`: Returns the server edition ('MCPE' or 'MCEE').
- `getMotdLine1()`: Returns the first line of the server's MOTD.
- `getMotdLine2()`: Returns the second line of the server's MOTD.
- `getVersionName()`: Returns the server version name (e.g., '1.21.0').
- `getProtocolVersion()`: Returns the server protocol version (e.g., 671).
- `getPlayerCount()`: Returns the current number of players.
- `getMaxPlayerCount()`: Returns the maximum number of players.
- `getGameMode()`: Returns the server's game mode (e.g., 'Survival').
- `getServerGUID()`: Returns the server's GUID as a BigInt.
- `getIpv4Port()`: Returns the IPv4 port or null.
- `getIpv6Port()`: Returns the IPv6 port or null.

### Closing the Client
- `client.close()`: Must be called to release the UDP socket when no longer needed.
```

--------------------------------

### Ping Minecraft 1.7+ Server

Source: https://github.com/aternosorg/craftping/blob/master/README.md

Use the modern ping protocol for Minecraft 1.7 and later. This returns a JsonStatus object.

```javascript
let response = await client.ping('localhost', 25565, {signal: AbortSignal.timeout(5000)});
```

--------------------------------

### Java Edition Ping Protocol

Source: https://github.com/aternosorg/craftping/blob/master/README.md

Ping Minecraft Java Edition servers using the protocol version that matches the server. Supports SRV record resolution.

```APIDOC
## Java Edition Ping Protocol

### Description
Ping Minecraft Java Edition servers using the client-side Server List Ping protocol. This protocol has evolved, so using the correct version is recommended for complete information.

### Client Initialization
```js
import {JavaPingClient} from 'craftping';

let client = new JavaPingClient();
```

### Ping Minecraft 1.7+ Server
Uses the modern JSON status response format.

```js
let response = await client.ping('localhost', 25565, {signal: AbortSignal.timeout(5000)});
```

### Ping Minecraft 1.4 - 1.6 Server
Uses the legacy ping protocol for versions 1.4 through 1.6.

```js
let response = await client.pingLegacyPost14('localhost', 25565, {signal: AbortSignal.timeout(5000)});
```

### Ping Beta 1.8 - Release 1.3 Server (or any server)
Uses the oldest compatible ping protocol, suitable for older versions or as a fallback.

```js
let response = await client.pingLegacyPre14('localhost', 25565, {signal: AbortSignal.timeout(5000)});
```

### SRV Record Resolution
Enable SRV record resolution by passing an option to the client or ping methods.

```js
// Example with ping method (assuming client is initialized)
let response = await client.ping('example.com', 25565, {signal: AbortSignal.timeout(5000), resolveSrvRecords: true});
```
```

--------------------------------

### Prevent Process Hang with `unref()`

Source: https://context7.com/aternosorg/craftping/llms.txt

Call `unref()` on BedrockPingClient or QueryClient to allow the Node.js process to exit naturally, even if the UDP socket is not explicitly closed. This is useful for one-off checks.

```javascript
import { BedrockPingClient, QueryClient } from 'craftping';

// Bedrock client that won't prevent process exit
const bedrockClient = new BedrockPingClient();
bedrockClient.unref();
const pong = await bedrockClient.ping('bedrock.example.com', 19132, AbortSignal.timeout(5000));
console.log(pong.getMotdLine1());
// No need to call client.close() if process is about to exit

// Query client used for a one-off check
const queryClient = new QueryClient();
queryClient.unref();
const full = await queryClient.queryFull('mc.example.com', 25565, AbortSignal.timeout(5000));
console.log(full.getPlayers());
```

--------------------------------

### Ping Minecraft 1.4-1.6 Server

Source: https://github.com/aternosorg/craftping/blob/master/README.md

Use the pingLegacyPost14 method for Minecraft versions 1.4 through 1.6.

```javascript
let response = await client.pingLegacyPost14('localhost', 25565, {signal: AbortSignal.timeout(5000)});
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.