npm version License: MIT

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

• 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

npm install @hytaleone/query

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(', '));

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`);
}

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 }

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

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

import { clearChallengeCache } from '@hytaleone/query';
clearChallengeCache();

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

• Node.js >= 18
• Server must have the HytaleOne Query Plugin installed

MIT

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

hytale.one - Discover Hytale Servers