@hytaleone/query

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

npm install @hytaleone/query

Usage

V1 Protocol

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

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.

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.

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.

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 installed

License

MIT

Related

• @hytaleone/votifier - Send votes to Hytale and Minecraft servers

hytale.one - Discover Hytale Servers