npm package: @hloth/minecraft-query
Description: A JavaScript implementation of Minecraft's query protocol
Author: Viktor Shchelochkov
Latest version: 1.0.0

# @hloth/minecraft-query

The fastest lightweight JavaScript wrapper for Minecraft's query protocol. Get MOTD, online players, version and other metadata about Minecraft server in JS. Full TypeScript support, ESM-only, no dependencies, tested on [Bun](https://bun.sh) and Node.js v22. Works on Edge.

## Install

- Bun: `bun add @hloth/minecraft-query`
- NPM: `npm install @hloth/minecraft-query`
- Yarn: `yarn add @hloth/minecraft-query`
- PNPM: `pnpm add @hloth/minecraft-query`
- JSR: `jsr install @hloth/minecraft-query`

## Usage

```ts
import { getPlayers } from "@hloth/minecraft-query";

const players = await getPlayers("demo.mcstatus.io");
// -> ['player1', 'player2', 'jeb']
```

```ts
import { getBasicInfo } from "@hloth/minecraft-query";

const { motd, onlinePlayers, maxPlayers } = await getBasicInfo("demo.mcstatus.io");
// -> { motd: 'A Minecraft Server', onlinePlayers: 0, maxPlayers: 20 }
```

## API reference

`arg` can be either a hostname (with default port 25565) or an object of type:

```ts
type MinecraftQueryOptions = {
	/** Only host, no https protocol. E.g. `example.org`, not `https://example.org` */
	hostname: MinecraftHostname;
	/** Default is 25565 */
	port?: number;
	/** Default is 2000ms (2 seconds) */
	timeoutMs?: number;
	/** Default is 3 */
	retries?: number;
};
```

Two types of responses are:

Basic info:

```ts
type BasicResponse = {
	/** With Minecraft formatting characters */
	motd: string;
	/** Hardcoded to `SMP` */
	gametype: string | null;
	/** World name */
	map: string;
	onlinePlayers: number;
	maxPlayers: number;
	ipAddress: string;
};
```

and full info:

```ts
type FullResponse = BasicResponse & {
	/** Everything in BasicResponse and ... */
	/** Hardcoded to `MINECRAFT` */
	gameId: string;
	/** E.g. `1.20.1` */
	version: string;
	software: string | null;
	plugins: string[];
	port: number;
	players: string[];
};
```

### getBasicInfo(arg): Promise&lt;BasicResponse&gt;

Get MOTD, gametype, map, online players, max players and IP address of the server.

### getFullInfo(arg): Promise&lt;FullResponse&gt;

Get MOTD, gametype, map, online players, max players, IP address, game ID, version, server software, plugins, port and list of online players nicknames.

Syntax sugar helpers:

- `getMotd(): Promise<string>`
- `getGametype(): Promise<string | null>`
- `getMap(): Promise<string>`
- `getOnlinePlayers(): Promise<number>`
- `getMaxPlayers(): Promise<number>`
- `getIpAddress(): Promise<string>`
- `getGameId(): Promise<string>`
- `getVersion(): Promise<string>`
- `getSoftware(): Promise<string | null>`
- `getPlugins(): Promise<string[]>`
- `getPort(): Promise<number>`
- `getPlayers(): Promise<string[]>`

They are making the same getBasicInfo/getFullInfo call under the hood and returning only the requested property. If you need more than one property, consider using getBasicInfo/getFullInfo instead to avoid multiple network calls.

## License

[MIT](./LICENSE)

## Donate

[hloth.dev/donate](https://hloth.dev/donate) · Tor: [hlothdevzkti6suoksy7lcy7hmpxnr3msu5waokzaslsi2mnx5ouu4qd.onion/donate](http://hlothdevzkti6suoksy7lcy7hmpxnr3msu5waokzaslsi2mnx5ouu4qd.onion/donate)