# minecraft protocol [![NPM version](https://img.shields.io/npm/v/minecraft-protocol.svg)](http://npmjs.com/package/minecraft-protocol) [![Build Status](https://img.shields.io/circleci/project/PrismarineJS/node-minecraft-protocol/master.svg)](https://circleci.com/gh/PrismarineJS/node-minecraft-protocol) [![Join the chat at https://gitter.im/PrismarineJS/node-minecraft-protocol](https://img.shields.io/badge/gitter-join%20chat-brightgreen.svg)](https://gitter.im/PrismarineJS/node-minecraft-protocol) Parse and serialize minecraft packets, plus authentication and encryption. ## Features * Supports Minecraft version 1.8.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. See Test Coverage section below. * Optimized for rapidly staying up to date with Minecraft protocol updates. ## Projects Using node-minecraft-protocol * [mineflayer](https://github.com/andrewrk/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/mhsjlw/flying-squid) create minecraft servers with a high level API, also a minecraft server by itself. ## Usage ### Echo client example ```js var mc = require('minecraft-protocol'); var client = mc.createClient({ host: "localhost", // optional port: 25565, // optional username: "email@example.com", password: "12345678", }); client.on('chat', function(packet) { // Listen for chat messages and echo them back. var jsonMsg = JSON.parse(packet.message); if (jsonMsg.translate == 'chat.type.announcement' || jsonMsg.translate == 'chat.type.text') { var username = jsonMsg.using[0]; var msg = jsonMsg.using[1]; if (username === client.username) return; client.write("chat", { message: msg }); } }); ``` If the server is in offline mode, you may leave out the `password` option. ### Hello World server example ```js var mc = require('minecraft-protocol'); var server = mc.createServer({ 'online-mode': true, // optional encryption: true, // optional host: '0.0.0.0', // optional port: 25565, // optional }); server.on('login', function(client) { client.write('login', { entityId: client.id, levelType: 'default', gameMode: 0, dimension: 0, difficulty: 2, maxPlayers: server.maxPlayers }); client.write('position', { x: 0, y: 1.62, z: 0, yaw: 0, pitch: 0, onGround: true }); var msg = { translate: 'chat.type.announcement', using: [ 'Server', 'Hello, ' + client.username ]}; client.write("chat", { message: JSON.stringify(msg) }); }); ``` ## Installation `npm install minecraft-protocol` URSA, an optional dependency, should improve login times for servers. However, it can be somewhat complicated to install. Follow the instructions from [Obvious/ursa](https://github.com/Obvious/ursa) ## Documentation See [doc](doc/README.md) ## Testing * Ensure your system has the `java` executable in `PATH`. * Download the appropriate version of `minecraft_server.jar`. * `MC_SERVER_JAR=path/to/minecraft_server.jar MC_USERNAME=email@example.com MC_PASSWORD=password npm test` ### Test Coverage ``` packets ✓ handshaking,ServerBound,0x00 ✓ status,ServerBound,0x00 ✓ status,ServerBound,0x01 ✓ status,ClientBound,0x00 ✓ status,ClientBound,0x01 ✓ login,ServerBound,0x00 ✓ login,ServerBound,0x01 ✓ login,ClientBound,0x00 ✓ login,ClientBound,0x01 ✓ login,ClientBound,0x02 ✓ login,ClientBound,0x03 ✓ play,ServerBound,0x00 ✓ play,ServerBound,0x01 ✓ play,ServerBound,0x02 ✓ play,ServerBound,0x03 ✓ play,ServerBound,0x04 ✓ play,ServerBound,0x05 ✓ play,ServerBound,0x06 ✓ play,ServerBound,0x07 ✓ play,ServerBound,0x08 ✓ play,ServerBound,0x09 ✓ play,ServerBound,0x0a ✓ play,ServerBound,0x0b ✓ play,ServerBound,0x0c ✓ play,ServerBound,0x0d ✓ play,ServerBound,0x0e ✓ play,ServerBound,0x0f ✓ play,ServerBound,0x10 ✓ play,ServerBound,0x11 ✓ play,ServerBound,0x12 ✓ play,ServerBound,0x13 ✓ play,ServerBound,0x14 ✓ play,ServerBound,0x15 ✓ play,ServerBound,0x16 ✓ play,ServerBound,0x17 ✓ play,ServerBound,0x18 ✓ play,ServerBound,0x19 ✓ play,ClientBound,0x00 ✓ play,ClientBound,0x01 ✓ play,ClientBound,0x02 ✓ play,ClientBound,0x03 ✓ play,ClientBound,0x04 ✓ play,ClientBound,0x05 ✓ play,ClientBound,0x06 ✓ play,ClientBound,0x07 ✓ play,ClientBound,0x08 ✓ play,ClientBound,0x09 ✓ play,ClientBound,0x0a ✓ play,ClientBound,0x0b ✓ play,ClientBound,0x0c ✓ play,ClientBound,0x0d ✓ play,ClientBound,0x0e ✓ play,ClientBound,0x0f ✓ play,ClientBound,0x10 ✓ play,ClientBound,0x11 ✓ play,ClientBound,0x12 ✓ play,ClientBound,0x13 ✓ play,ClientBound,0x14 ✓ play,ClientBound,0x15 ✓ play,ClientBound,0x16 ✓ play,ClientBound,0x17 ✓ play,ClientBound,0x18 ✓ play,ClientBound,0x19 ✓ play,ClientBound,0x1a ✓ play,ClientBound,0x1b ✓ play,ClientBound,0x1c ✓ play,ClientBound,0x1d ✓ play,ClientBound,0x1e ✓ play,ClientBound,0x1f ✓ play,ClientBound,0x20 ✓ play,ClientBound,0x21 ✓ play,ClientBound,0x22 ✓ play,ClientBound,0x23 ✓ play,ClientBound,0x24 ✓ play,ClientBound,0x25 ✓ play,ClientBound,0x26 ✓ play,ClientBound,0x27 ✓ play,ClientBound,0x28 ✓ play,ClientBound,0x29 ✓ play,ClientBound,0x2a ✓ play,ClientBound,0x2b ✓ play,ClientBound,0x2c ✓ play,ClientBound,0x2d ✓ play,ClientBound,0x2e ✓ play,ClientBound,0x2f ✓ play,ClientBound,0x30 ✓ play,ClientBound,0x31 ✓ play,ClientBound,0x32 ✓ play,ClientBound,0x33 ✓ play,ClientBound,0x34 ✓ play,ClientBound,0x35 ✓ play,ClientBound,0x36 ✓ play,ClientBound,0x37 ✓ play,ClientBound,0x38 ✓ play,ClientBound,0x39 ✓ play,ClientBound,0x3a ✓ play,ClientBound,0x3b ✓ play,ClientBound,0x3c ✓ play,ClientBound,0x3d ✓ play,ClientBound,0x3e ✓ play,ClientBound,0x3f ✓ play,ClientBound,0x40 ✓ play,ClientBound,0x41 ✓ play,ClientBound,0x42 ✓ play,ClientBound,0x43 ✓ play,ClientBound,0x44 ✓ play,ClientBound,0x45 ✓ play,ClientBound,0x46 ✓ play,ClientBound,0x47 ✓ play,ClientBound,0x48 ✓ play,ClientBound,0x49 client ✓ pings the server (65754ms) ✓ connects successfully - online mode (STUBBED) ✓ connects successfully - offline mode (STUBBED) ✓ gets kicked when no credentials supplied in online mode (67167ms) ✓ does not crash for 10000ms (69597ms) mc-server ✓ starts listening and shuts down cleanly ✓ kicks clients that do not log in (133ms) ✓ kicks clients that do not send keepalive packets (122ms) ✓ responds to ping requests ✓ clients can log in and chat (39ms) ✓ kicks clients when invalid credentials (8430ms) ✓ gives correct reason for kicking clients when shutting down (42ms) 123 tests complete (4 minutes) ``` ## Debugging You can enable some protocol debugging output using `NODE_DEBUG` environment variable: ```bash NODE_DEBUG="minecraft-protocol" node [...] ``` ## History See [history](HISTORY.md)