npm package: @hytaleone/query
Description: TypeScript/JavaScript client for querying Hytale servers. Get server status, player count, player list, and plugin information via UDP protocol.
Author: HytaleOne
Latest version: 1.1.1

# @hytaleone/query

[![npm version](https://img.shields.io/npm/v/@hytaleone/query.svg)](https://www.npmjs.com/package/@hytaleone/query)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Query Hytale servers using the UDP query protocol. Get server status, player count, player list, and plugin information.

## Features

- **Server Status** - Get server name, MOTD, version, player count
- **Player List** - Retrieve online players with names and UUIDs
- **Plugin List** - See installed plugins with versions
- **V2 Protocol** - Enhanced protocol with challenge-based authentication and pagination
- **Zero dependencies** - Uses only Node.js built-in modules
- **TypeScript** - Full type definitions included
- **Dual format** - Works with both ESM and CommonJS

## Installation

```bash
npm install @hytaleone/query
```

## Usage

### V1 Protocol

```typescript
import { query } from '@hytaleone/query';

// Basic query
const info = await query('play.example.com', 5520);
console.log(`${info.serverName}: ${info.currentPlayers}/${info.maxPlayers}`);

// Check V2 support
if (info.supportsV2) {
  console.log('Server supports V2 protocol');
}

// Full query - includes players and plugins
const full = await query('play.example.com', 5520, { full: true });
console.log('Players:', full.players.map(p => p.name).join(', '));
console.log('Plugins:', full.plugins.map(p => p.id).join(', '));
```

### V2 Protocol

```typescript
import { query, queryV2 } from '@hytaleone/query';

// Check if server supports V2
const info = await query('play.example.com', 5520);

if (info.supportsV2) {
  // Basic V2 query
  const v2Info = await queryV2('play.example.com', 5520);
  console.log(`${v2Info.serverName}: ${v2Info.currentPlayers}/${v2Info.maxPlayers}`);

  // V2 query with players (single page)
  const withPlayers = await queryV2('play.example.com', 5520, { players: true });
  console.log('Players:', withPlayers.players.map(p => p.name).join(', '));
  console.log('Has more:', withPlayers.hasMore);

  // V2 query with all players (auto-pagination)
  const allPlayers = await queryV2('play.example.com', 5520, { players: 'all' });
  console.log(`All ${allPlayers.totalPlayers} players fetched`);
}
```

## API

### query(host, port?, options?)

Query a server using the V1 protocol.

```typescript
const info = await query('localhost', 5520, {
  timeout: 5000,
  full: true
});
```

**Options:**
- `timeout` - Query timeout in milliseconds (default: 5000)
- `full` - Include players and plugins (default: false)

**Returns `ServerInfo`:**
- `serverName` - Server display name
- `motd` - Message of the day
- `currentPlayers` - Current player count
- `maxPlayers` - Maximum player capacity
- `hostPort` - Server port
- `version` - Server version
- `protocolVersion` - Protocol version number
- `protocolHash` - Protocol hash
- `supportsV2` - Whether server supports V2 protocol
- `isNetworkMode` - Whether server is in network aggregation mode
- `v2Version` - V2 protocol version (0 if not supported)

**With `full: true`, also returns:**
- `players` - Array of `{ name, uuid }`
- `plugins` - Array of `{ id, version, enabled }`

### queryV2(host, port?, options?)

Query a server using the V2 protocol with challenge-based authentication.

```typescript
const info = await queryV2('localhost', 5520, {
  timeout: 5000,
  players: true,
  playerOffset: 0
});
```

**Options:**
- `timeout` - Query timeout in milliseconds (default: 5000)
- `players` - Request player list: `false` (default), `true` (single page), or `'all'` (auto-paginate)
- `playerOffset` - Starting offset for player pagination (default: 0)
- `authToken` - Optional authentication token for private servers

**Returns `ServerInfoV2`:**
- `serverName` - Server display name
- `motd` - Message of the day
- `currentPlayers` - Current player count
- `maxPlayers` - Maximum player capacity
- `version` - Server version
- `protocolVersion` - Protocol version number
- `protocolHash` - Protocol hash
- `isNetwork` - Whether response contains aggregated network data
- `host` - Server host (if provided by server)
- `hostPort` - Server port (if provided by server)

**With `players: true` or `players: 'all'`, also returns:**
- `players` - Array of `{ name, uuid }`
- `totalPlayers` - Total player count on server
- `offset` - Offset used for this response
- `hasMore` - Whether more players are available

### clearChallengeCache()

Clear the V2 challenge token cache. Useful for testing or forcing fresh challenges.

```typescript
import { clearChallengeCache } from '@hytaleone/query';

clearChallengeCache();
```

## V1 vs V2 Protocol

| Feature | V1 | V2 |
|---------|----|----|
| Authentication | None | Challenge-based |
| Player pagination | No | Yes |
| Network aggregation | No | Yes |
| Plugin list | Yes | No |

Use V1 for simple queries or when you need plugin information. Use V2 for servers with many players or when you need pagination support.

## Requirements

- Node.js >= 18
- Server must have the [HytaleOne Query Plugin](https://github.com/hytaleone/hytale-one-query-plugin) installed

## License

MIT

## Related

- [@hytaleone/votifier](https://www.npmjs.com/package/@hytaleone/votifier) - Send votes to Hytale and Minecraft servers

---

**[hytale.one](https://hytale.one/)** - Discover Hytale Servers