mineping/README.md

# mineping

This JavaScript library provides an implementation of the Minecraft server ping protocol. **It allows you to gather information about a Minecraft server**, such as the MOTD, current online players, server icon (Java Edition only), and more.

Mirror on my [<img src="https://git.zeldon.ru/assets/img/logo.svg" align="center" width="20" height="20"/> Git](https://git.zeldon.ru/zeldon/mineping)

## Requirements

> **[Node.js](https://nodejs.org/) 14 or newer is required**

## Install

To install `mineping`, simply run the following command:

```
npm i @minescope/mineping
```

## Loading and configuration the module

### ES Modules (ESM)
If you are using ES Modules, you can import the library like this:

```js
import { pingJava, pingBedrock } from '@minescope/mineping';
```

### CommonJS

`mineping` is an ESM-only module — you are not able to import it with `require()`.
If you cannot switch to ESM, you can use the async `import()` function from CommonJS to load `mineping` asynchronously:

```js
const pingJava = (...args) => import('@minescope/mineping').then(module => module.pingJava(...args));
const pingBedrock = (...args) => import('@minescope/mineping').then(module => module.pingBedrock(...args));
```

## Usage

Ping a Java server with default options:

```js
import { pingJava } from '@minescope/mineping';

const data = await pingJava('mc.hypixel.net');
console.log(data);
```

Ping a Bedrock server with custom options:

```js
import { pingBedrock } from '@minescope/mineping';

const data = await pingBedrock('mco.mineplex.com', {
    port: 19132,
    timeout: 500
});
console.log(data);
```

> More complex example can be found in the `example` folder!

## Acknowledgements

Special thanks to the following projects:

- [mcping](https://github.com/Scetch/mcping) crate for Rust
- [mcping-js](https://github.com/Cryptkeeper/mcping-js) library for quering Minecraft Java Edition servers