Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/woodendoors7/minecraftstatuspinger
🟩 A Minecraft Status Pinger
https://github.com/woodendoors7/minecraftstatuspinger
javascript javascript-library minecraft minecraft-cheat minecraft-datapack minecraft-forge minecraft-hack minecraft-library minecraft-mod minecraft-modpack minecraft-ping minecraft-pinger minecraft-plugin minecraft-protocol minecraft-server protocol tcp typescript typescript-library
Last synced: about 2 months ago
JSON representation
🟩 A Minecraft Status Pinger
- Host: GitHub
- URL: https://github.com/woodendoors7/minecraftstatuspinger
- Owner: woodendoors7
- License: gpl-3.0
- Created: 2022-12-21T20:21:28.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-26T19:17:53.000Z (3 months ago)
- Last Synced: 2024-11-03T06:08:37.318Z (about 2 months ago)
- Topics: javascript, javascript-library, minecraft, minecraft-cheat, minecraft-datapack, minecraft-forge, minecraft-hack, minecraft-library, minecraft-mod, minecraft-modpack, minecraft-ping, minecraft-pinger, minecraft-plugin, minecraft-protocol, minecraft-server, protocol, tcp, typescript, typescript-library
- Language: TypeScript
- Homepage: https://pinger.floppa.hair
- Size: 178 KB
- Stars: 29
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
A modern, small, fast, performant, zero dependency TypeScript library made for pinging and getting status of Minecraft servers.
### What can this be used for?
- Getting server **Latency (ping)**
- Getting server **MOTD**
- Downloading server **Thumbnail (favicon)**
- Viewing Server **Version**
- Fetching **Player Count** and **Playerlist**
**And in general, checking the status of Minecraft servers!**
## Getting started
### Requirements
- NodeJS or Deno (used to run JavaScript code)
- NPM (used to install Node packages)
### Installation
```bat
npm install minecraftstatuspinger
```
### Basic Example
```typescript
import mc from "minecraftstatuspinger";
let result = await mc.lookup({ host: "mc.hypixel.net" })
console.log(result);
```
Advanced Example
```typescript
import mc from "minecraftstatuspinger";
let result = await mc.lookup({
host: "mc.hypixel.net",
port: 25565,
ping: true,
protocolVersion: 764,
timeout: 10000,
throwOnParseError: true,
disableSRV: false,
disableJSONParse: false
})
console.log(result);
```
## Docs
* .lookup(): *`((options: ServerStatusOptions) => Promise)`*
* **options:** ServerStatusOptions
* `host:` string
> Either an IP, or a hostname of the server. (alias: hostname)
* `port?:` number `default: 25565`
> Port of the server. SRV lookup is disabled when using ports other than 25565.
* `timeout?:` number `default: 10000`
> How long until an error is thrown if the transaction still hasn't finished. Default is 10 seconds.
* `ping?:` boolean `default: true`
> Whether to send a payload at the end to measure the server latency. If false, the `latency` field will be null.
* `protocolVersion?:` number `default: 764`
> Protocol version to send to the server to simulate different Minecraft client versions. Here, you can see the [Protocol Version Numbers](https://wiki.vg/Protocol_version_numbers). The current default protocol version is for 1.20.2 (764) and will be irregularly updated to newer versions.
* `throwOnParseError?:` boolean `default: true`
> Whether to throw an error if the status packet fails to parse the status field. The `statusRaw` field is always included.
* `disableSrv?:` boolean `default: false`
> Whether to force skip SRV lookups. Useful when only pinging IP addresses and not hostnames (domains).
* `disableJSONParse?:` boolean `default: false`
> Whether to skip JSON parsing. Useful if you only want a raw plaintext response. If true, the `status` field will be undefined.
* ServerStatus
* `latency?:` number
> The time it takes to receive back a response after sending a small payload to a server, in milliseconds. Will be null if the `ping` option is false.
* `status?:` DynamicObject
> Parsed status response from the server. Will be null if the status fails to parse, or if disableJSONParse is true. Example of a valid Status Response.
* `statusRaw:` string
> Plaintext status response in the form of JSON. Useful when `status` fails to parse.
* .setDnsServers(): `((serverArray: string[]) => Promise)`
> It wraps the `dns.setServers` function, useful for looking up SRV records through different DNS servers.
The first IP in the array will always be used first, others will be tried if the first one is unreachable.
Accepts an array of hostnames or IP addresses of DNS servers. It will either return true, or throw an error.
Usage:
```js
// For example:
mc.setDnsServers(["9.9.9.9", "1.1.1.1", "8.8.8.8"])
// (Quad9, Cloudflare, Google)
// Cloudflare is usually the fastest for DNS queries.
```
If you never changed the DNS settings of your computer, the default DNS server will be your ISP's.
❗ I recommend changing your default DNS servers if you're doing thousands of lookups, such as for mass scanning.
### Changelog
**[View Changelog](https://pinger.floppa.hair/changelog/)**,
Latest version: v1.1.5
### Contact
If you have some questions, you can message me through Discord - **woodendoors7**
### Acknowledgements
[TINY Readme](https://gist.github.com/noperator/4eba8fae61a23dc6cb1fa8fbb9122d45)
### To-do
- [x] Do SRV lookups
- [ ] Parse MOTDs
- [ ] Support versions less than 1.7.
- [ ] Support Bedrock
### License
This project is licensed under the [GNU General Public License v3.0](LICENSE).