mirror of
https://github.com/PrismarineJS/node-minecraft-protocol.git
synced 2024-11-14 19:04:59 -05:00
960df173cc
* 1.20 * Add 1.20 to README * bump mcdata * clean --------- Co-authored-by: Romain Beaumont <romain.rom1@gmail.com>
203 lines
7.1 KiB
Markdown
203 lines
7.1 KiB
Markdown
# minecraft protocol
|
|
[](https://www.npmjs.com/package/minecraft-protocol)
|
|
[](https://github.com/PrismarineJS/node-minecraft-protocol/actions?query=workflow%3A%22CI%22)
|
|
[](https://discord.gg/GsEFRM8)
|
|
[](https://gitter.im/PrismarineJS/general)
|
|
[](https://irc.gitter.im/)
|
|
|
|
[](https://gitpod.io/#https://github.com/PrismarineJS/node-minecraft-protocol)
|
|
|
|
Parse and serialize minecraft packets, plus authentication and encryption.
|
|
|
|
## Features
|
|
|
|
* Supports Minecraft PC version 1.7.10, 1.8.8, 1.9 (15w40b, 1.9, 1.9.1-pre2, 1.9.2, 1.9.4),
|
|
1.10 (16w20a, 1.10-pre1, 1.10, 1.10.1, 1.10.2), 1.11 (16w35a, 1.11, 1.11.2), 1.12 (17w15a, 17w18b, 1.12-pre4, 1.12, 1.12.1, 1.12.2), and 1.13 (17w50a, 1.13, 1.13.1, 1.13.2-pre1, 1.13.2-pre2, 1.13.2), 1.14 (1.14, 1.14.1, 1.14.3, 1.14.4)
|
|
, 1.15 (1.15, 1.15.1, 1.15.2) and 1.16 (20w13b, 20w14a, 1.16-rc1, 1.16, 1.16.1, 1.16.2, 1.16.3, 1.16.4), 1.17 (21w07a, 1.17, 1.17.1), 1.18 (1.18, 1.18.1 and 1.18.2), 1.19 (1.19, 1.19.1, 1.19.2, 1.19.3, 1.19.4), 1.20 (1.20, 1.20.1)
|
|
* Parses all packets and emits events with packet fields as JavaScript
|
|
objects.
|
|
* Send a packet by supplying fields as a JavaScript object.
|
|
* Client
|
|
- Authenticating and logging in
|
|
- Encryption
|
|
- Compression
|
|
- Both online and offline mode
|
|
- Respond to keep-alive packets.
|
|
- Ping a server for status
|
|
* Server
|
|
- Online/Offline mode
|
|
- Encryption
|
|
- Compression
|
|
- Handshake
|
|
- Keep-alive checking
|
|
- Ping status
|
|
* Robust test coverage.
|
|
* Optimized for rapidly staying up to date with Minecraft protocol updates.
|
|
|
|
Want to contribute on something important for PrismarineJS ? go to https://github.com/PrismarineJS/mineflayer/wiki/Big-Prismarine-projects
|
|
|
|
## Third Party Plugins
|
|
|
|
node-minecraft-protocol is pluggable.
|
|
|
|
* [minecraft-protocol-forge](https://github.com/PrismarineJS/node-minecraft-protocol-forge) add forge support to minecraft-protocol
|
|
|
|
## Projects Using node-minecraft-protocol
|
|
|
|
* [mineflayer](https://github.com/PrismarineJS/mineflayer/) - Create minecraft
|
|
bots with a stable, high level API.
|
|
* [mcserve](https://github.com/andrewrk/mcserve) - Runs and monitors your
|
|
minecraft server, provides real-time web interface, allow your users to
|
|
create bots.
|
|
* [flying-squid](https://github.com/PrismarineJS/flying-squid) - Create minecraft
|
|
servers with a high level API, also a minecraft server by itself.
|
|
* [pakkit](https://github.com/Heath123/pakkit) - A GUI tool to monitor Minecraft packets in real time, allowing you to view their data and interactively edit and resend them.
|
|
* [minecraft-packet-debugger](https://github.com/wvffle/minecraft-packet-debugger) - A tool to capture Minecraft packets in a buffer then view them in a browser.
|
|
* [aresrpg](https://github.com/aresrpg/aresrpg) - An open-source mmorpg minecraft server.
|
|
* [SteveProxy](https://github.com/SteveProxy/proxy) - Proxy for Minecraft with the ability to change the gameplay using plugins.
|
|
* and [several thousands others](https://github.com/PrismarineJS/node-minecraft-protocol/network/dependents?package_id=UGFja2FnZS0xODEzMDk0OQ%3D%3D)
|
|
|
|
## Installation
|
|
|
|
`npm install minecraft-protocol`
|
|
|
|
## Documentation
|
|
|
|
* [API doc](API.md)
|
|
* [faq](FAQ.md)
|
|
* [protocol doc](https://minecraft-data.prismarine.js.org/?d=protocol) and [wiki.vg/Protocol](https://wiki.vg/Protocol)
|
|
|
|
## Usage
|
|
|
|
### Echo client example
|
|
|
|
```js
|
|
const mc = require('minecraft-protocol');
|
|
const client = mc.createClient({
|
|
host: "localhost", // optional
|
|
port: 25565, // optional
|
|
username: "email@example.com",
|
|
password: "12345678",
|
|
auth: 'microsoft' // optional; by default uses offline mode, if using a microsoft account, set to 'microsoft'
|
|
});
|
|
|
|
client.on('chat', function(packet) {
|
|
// Listen for chat messages and echo them back.
|
|
const jsonMsg = JSON.parse(packet.message);
|
|
|
|
if (jsonMsg.translate == 'chat.type.announcement' || jsonMsg.translate == 'chat.type.text') {
|
|
const username = jsonMsg.with[0].text;
|
|
const msg = jsonMsg.with[1];
|
|
|
|
if (username === client.username) return;
|
|
|
|
client.write('chat', {message: msg.text});
|
|
}
|
|
});
|
|
```
|
|
|
|
If the server is in offline mode, you may leave out the `password` option and switch auth to `offline`.
|
|
You can also leave out `password` when using a Microsoft account. If provided, password based auth will be attempted first which may fail. *Note:* if using a Microsoft account, your account age must be >= 18 years old.
|
|
|
|
### Client example joining a Realm
|
|
|
|
Example to connect to a Realm that the authenticating account is owner of or has been invited to:
|
|
|
|
```js
|
|
const mc = require('minecraft-protocol');
|
|
const client = mc.createClient({
|
|
realms: {
|
|
pickRealm: (realms) => realms[0] // Function which recieves an array of joined/owned Realms and must return a single Realm. Can be async
|
|
},
|
|
auth: 'microsoft'
|
|
})
|
|
```
|
|
|
|
### Hello World server example
|
|
|
|
```js
|
|
const mc = require('minecraft-protocol');
|
|
const server = mc.createServer({
|
|
'online-mode': true, // optional
|
|
encryption: true, // optional
|
|
host: '0.0.0.0', // optional
|
|
port: 25565, // optional
|
|
version: '1.16.3'
|
|
});
|
|
const mcData = require('minecraft-data')(server.version)
|
|
|
|
server.on('login', function(client) {
|
|
const loginPacket = mcData.loginPacket
|
|
|
|
client.write('login', {
|
|
entityId: client.id,
|
|
isHardcore: false,
|
|
gameMode: 0,
|
|
previousGameMode: 255,
|
|
worldNames: loginPacket.worldNames,
|
|
dimensionCodec: loginPacket.dimensionCodec,
|
|
dimension: loginPacket.dimension,
|
|
worldName: 'minecraft:overworld',
|
|
hashedSeed: [0, 0],
|
|
maxPlayers: server.maxPlayers,
|
|
viewDistance: 10,
|
|
reducedDebugInfo: false,
|
|
enableRespawnScreen: true,
|
|
isDebug: false,
|
|
isFlat: false
|
|
});
|
|
|
|
client.write('position', {
|
|
x: 0,
|
|
y: 255,
|
|
z: 0,
|
|
yaw: 0,
|
|
pitch: 0,
|
|
flags: 0x00
|
|
});
|
|
|
|
const msg = {
|
|
translate: 'chat.type.announcement',
|
|
"with": [
|
|
'Server',
|
|
'Hello, world!'
|
|
]
|
|
};
|
|
|
|
client.write("chat", { message: JSON.stringify(msg), position: 0, sender: '0' });
|
|
});
|
|
```
|
|
|
|
## Testing
|
|
|
|
* Ensure your system has the `java` executable in `PATH`.
|
|
* `MC_SERVER_JAR_DIR=some/path/to/store/minecraft/server/ MC_USERNAME=email@example.com MC_PASSWORD=password npm test`
|
|
|
|
## Debugging
|
|
|
|
You can enable some protocol debugging output using `DEBUG` environment variable:
|
|
|
|
```bash
|
|
DEBUG="minecraft-protocol" node [...]
|
|
```
|
|
|
|
On Windows:
|
|
```
|
|
set DEBUG=minecraft-protocol
|
|
node your_script.js
|
|
```
|
|
|
|
## Contribute
|
|
|
|
Please read https://github.com/PrismarineJS/prismarine-contribute
|
|
|
|
## History
|
|
|
|
See [history](HISTORY.md)
|
|
|
|
## Related
|
|
|
|
* [node-rcon](https://github.com/pushrax/node-rcon) can be used to access the rcon server in the minecraft server
|
|
* [map-colors][aresmapcolor] can be used to convert any image into a buffer of minecraft compatible colors
|
|
|
|
[aresmapcolor]: https://github.com/AresRPG/aresrpg-map-colors
|