{"id":19826235,"url":"https://github.com/aternosorg/craftping","last_synced_at":"2026-02-25T14:09:03.959Z","repository":{"id":261462001,"uuid":"884381428","full_name":"aternosorg/craftping","owner":"aternosorg","description":null,"archived":false,"fork":false,"pushed_at":"2024-11-06T17:04:30.000Z","size":0,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-11-06T17:48:25.476Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aternosorg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-06T16:41:59.000Z","updated_at":"2024-11-06T17:03:54.000Z","dependencies_parsed_at":"2024-11-06T17:51:49.843Z","dependency_job_id":"2644e958-f660-4d31-bab6-3ffe882609cb","html_url":"https://github.com/aternosorg/craftping","commit_stats":null,"previous_names":["aternosorg/craftping"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fcraftping","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fcraftping/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fcraftping/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fcraftping/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aternosorg","download_url":"https://codeload.github.com/aternosorg/craftping/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224262074,"owners_count":17282267,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T11:09:49.979Z","updated_at":"2026-02-25T14:09:03.954Z","avatar_url":"https://github.com/aternosorg.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CraftPing\nA universal ping/query library for Minecraft servers. This library supports \nthe [Minecraft Query protocol](https://wiki.vg/Query), the [Minecraft Bedrock ping protocol](https://wiki.vg/Raknet_Protocol#Packets), as well as all three\ndifferent versions of the [Minecraft Java ping protocol](https://wiki.vg/Server_List_Ping).\n\n## Installation\n```bash\nnpm i craftping\n```\n\n## Usage\n### Query\nThe [Query protocol](https://wiki.vg/Query) is a UDP based protocol that allows getting basic information about a Minecraft server.\nNote that only servers with the `server.properties` option `enable-query` set to `true` will respond to queries.\n\nThe main advantage of the Query protocol over the ping protocol ist that it returns the\nfull list of players on the server, not just a small sample. It does, however, also have a few disadvantages, \nlike the fact that servers will return broken response packets if the MOTD (or any other string) [contains null bytes](https://bugs.mojang.com/browse/MC-221987)\nor [some other special characters](https://bugs.mojang.com/browse/MC-231035) in versions before 1.21.11.  \nThis library makes an effort to interpret these broken response packets correctly, but it is not always possible to do so.\n\n```js\nimport {QueryClient} from 'craftping';\n\nlet client = new QueryClient();\n\nlet basic = await client.queryBasic('localhost', 25565, AbortSignal.timeout(5000));\nlet full = await client.queryFull('localhost', 25565, AbortSignal.timeout(5000));\n\nawait client.close();\n```\nBasic and full query requests will return a [`BasicStatResponse`](src/Packet/Query/BasicStatResponse.js) \nand [`FullStatResponse`](src/Packet/Query/FullStatResponse.js) object respectively.\n\nNote that the query client needs to be closed manually, since it keeps its UDP socket open to reuse it for future queries.\n\n#### Query string encoding\n\nSince string encoding in query responses switched to UTF-8 in Minecraft 1.21.11, this library makes an effort to detect\nthe correct encoding automatically.  \n- In full stat responses, this works pretty reliably based on the version field.\n- Basic stat responses do not include the server version, so the library has to make a guess based on the content of the string.\nIf the whole string is valid UTF-8, it will be decoded as UTF-8. If it contains invalid UTF-8 sequences, it will be decoded as ISO-8859-1 instead.\n\nYou can force the string encoding using the `useLegacyStringEncoding` option, where `true` will force ISO-8859-1 encoding and `false` will force UTF-8 encoding.\nBy default, this option is set to `null`, which means that the library will try to detect the correct encoding automatically.\n\n```js\nlet useLegacyStringEncoding = true; // true, false, or null\nlet basic = await client.queryBasic('localhost', 25565, AbortSignal.timeout(5000), useLegacyStringEncoding);\nlet full = await client.queryFull('localhost', 25565, AbortSignal.timeout(5000), useLegacyStringEncoding);\n```\n\n### Java Edition Ping\nThe [Server List Ping protocol](https://wiki.vg/Server_List_Ping) is what the Minecraft client uses to show the server status in the in-game server list.\nThis protocol changed multiple times over the years, so you'd ideally want to know the version of the server you are pinging to use the correct protocol version.\n\nIf you do not know the server version, you can always use the pre 1.4 ping protocol, since all newer versions seem to be backwards compatible as of now.\nFinding the correct protocol should still be preferred, since pre 1.4 responses are missing a lot of information that is included in newer versions.\nIt is also unclear if server software not based on the Vanilla server will respond to pre 1.4 pings.\n\nSRV records are supported for Java Edition pings, but they are not resolved by default. You can enable SRV record resolution by setting the `resolveSrvRecords` option to `true`.\n\n```js\nimport {JavaPingClient} from 'craftping';\n\nlet client = new JavaPingClient();\n```\n\n#### Ping a Minecraft 1.7+ server\n```js\nlet response = await client.ping('localhost', 25565, {signal: AbortSignal.timeout(5000)});\n```\nUsing the modern ping protocol will return a [`JsonStatus`](src/JavaPing/Status/JsonStatus/JsonStatus.js).\n\n#### Ping a Minecraft 1.4 - 1.6 server\n```js\nlet response = await client.pingLegacyPost14('localhost', 25565, {signal: AbortSignal.timeout(5000)});\n```\n\n#### Ping a Minecraft beta 1.8 - release 1.3 server (or any server)\n```js\nlet response = await client.pingLegacyPre14('localhost', 25565, {signal: AbortSignal.timeout(5000)});\n```\n\n#### Ping a server that supports either of the two legacy ping versions\nSome custom server software seems to not respond to pre 1.4 pings, but will instead only respond to 1.4+ pings.\nThe only currently known instance of this is Better Than Adventure. If you are trying to ping a server that may or \nmay not support pre 1.4 pings, you can use the following code:\n```js\nlet response = await client.pingLegacyUniversal('localhost', 25565, {signal: AbortSignal.timeout(5000)});\n```\n\nNote that this weird hack involves sending the first half of a packet, then waiting for up to 500ms if the servers\nresponds, and if it does not, sending the second half of the packet. It may therefore run into problems if the timing is off.\n\nAll legacy ping versions will return a [`LegacyStatus`](src/JavaPing/Status/LegacyStatus.js) object.\nNote that for pre 1.4 pings, this object will not include the server version name and protocol version,\nas this information was not included in the response packets before Minecraft 1.4.\n\n#### Java Edition ping options\nJava Edition ping requests can be customized using the following options:\n - `protocolVersion`: The protocol version to announce to the server. Defaults to a sane value based on the used protocol.\n - `hostname`: The hostname to announce to the server. Defaults to the address/hostname used to connect.\n - `port`: The port to announce to the server. Defaults to the port used to connect.\n - `resolveSrvRecords`: Whether to resolve SRV records for the hostname. Defaults to `false`.\n - `resolver`: An instance of node:dns/promises.Resolver to use for resolving SRV records. Defaults to an instance with default options.\n - `signal`: An optional `AbortSignal` to cancel the request.\n\n### Bedrock Edition Ping\n\n```js\nimport {BedrockPingClient} from 'craftping';\n\nlet client = new BedrockPingClient();\n\nlet status = await client.ping('localhost', 19132, AbortSignal.timeout(5000));\n\nawait client.close();\n```\nPinging a Bedrock server will return an [`UnconnectedPong`](src/Packet/BedrockPing/UnconnectedPong.js) object.\n\nNote that the Bedrock ping client also needs to be closed manually, since it keeps its UDP socket open to reuse it for future requests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faternosorg%2Fcraftping","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faternosorg%2Fcraftping","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faternosorg%2Fcraftping/lists"}