minecraft protocol

Parse and serialize minecraft packets, plus authentication and encryption.

Features

• Supports Minecraft version 1.4.7
• 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 on and encryption off
  • Both online and offline mode
  • Respond to keep-alive packets.
  • Ping a server for status
• Server
  • Offline mode
  • Encryption and online mode
  • 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.

This package aims to be a low-level interface to the Minecraft protocol and no more. If you want a higher-level API with which to write bots, see mineflayer

Usage

Echo client example

var mc = require('minecraft-protocol');
var client = mc.createClient({
  host: "localhost", // optional
  port: 25565,       // optional
  username: "player",
  email: "email@example.com", // email and password are required only for
  password: "12345678",       // online-mode=true servers
});
client.on(0x03, function(packet) {
  // Listen for chat messages and echo them back.
  if (packet.message.indexOf(client.session.username) !== -1) return;
  client.write(0x03, {
    message: packet.message,
  });
});

Hello World server example

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(0x01, {
    entityId: client.id,
    levelType: 'default',
    gameMode: 0,
    dimension: 0,
    difficulty: 2,
    maxPlayers: server.maxPlayers
  });
  client.write(0x0d, {
    x: 0,
    y: 1.62,
    stance: 0,
    z: 0,
    yaw: 0,
    pitch: 0,
    onGround: true
  });
  client.write(0x03, { message: 'Hello, ' + client.username });
});

Installation

Linux

npm install minecraft-protocol

Windows

• Follow the Windows instructions from Obvious/ursa
• npm install minecraft-protocol

Documentation

mc.ping(options, callback)

callback(err, pingResults)

pingResults:

• prefix
• protocol
• version
• motd
• playerCount
• maxPlayers

Not Immediately Obvious Data Type Formats

entityMetadata

Value looks like this:

[
  {type: 'slot', value: slot, key: 3},
  {type: 'int', value: value, key: 4},
  ...
]

Where the key is the numeric metadata key and the value is the value of the correct data type.

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=username MC_EMAIL=email@example.com MC_PASSWORD=password npm test

Test Coverage

  packets
    ✓ 0x00 
    ✓ 0x01 
    ✓ 0x02 
    ✓ 0x03 
    ✓ 0x04 
    ✓ 0x05 
    ✓ 0x06 
    ✓ 0x07 
    ✓ 0x08 
    ✓ 0x09 
    ✓ 0x0a 
    ✓ 0x0b 
    ✓ 0x0c 
    ✓ 0x0d 
    ✓ 0x0e 
    ✓ 0x0f 
    ✓ 0x10 
    ✓ 0x11 
    ✓ 0x12 
    ✓ 0x13 
    ✓ 0x14 
    ✓ 0x16
    ✓ 0x17 
    ✓ 0x18 
    ✓ 0x19 
    ✓ 0x1a 
    ✓ 0x1c 
    ✓ 0x1d 
    ✓ 0x1e 
    ✓ 0x1f 
    ✓ 0x20 
    ✓ 0x21 
    ✓ 0x22 
    ✓ 0x23 
    ✓ 0x26 
    ✓ 0x27 
    ✓ 0x28 
    ✓ 0x29 
    ✓ 0x2a 
    ✓ 0x2b 
    ✓ 0x33 
    ✓ 0x34 
    ✓ 0x35 
    ✓ 0x36 
    ✓ 0x37 
    ✓ 0x38 
    ✓ 0x3c 
    ✓ 0x3d 
    ✓ 0x3e 
    ✓ 0x46 
    ✓ 0x47 
    ✓ 0x64 
    ✓ 0x65 
    ✓ 0x66 
    ✓ 0x67 
    ✓ 0x68 
    ✓ 0x69 
    ✓ 0x6a 
    ✓ 0x6b 
    ✓ 0x6c 
    ✓ 0x82 
    ✓ 0x83 
    ✓ 0x84 
    ✓ 0xc8 
    ✓ 0xc9 
    ✓ 0xca 
    ✓ 0xcb 
    ✓ 0xcc 
    ✓ 0xcd 
    ✓ 0xfa 
    ✓ 0xfc 
    ✓ 0xfd 
    ✓ 0xfe 
    ✓ 0xff 

  client
    ✓ pings the server
    ✓ connects successfully - online mode
    ✓ connects successfully - offline mode
    ✓ gets kicked when no credentials supplied in online mode
    ✓ does not crash for 10000ms

  mc-server
    ✓ starts listening and shuts down cleanly 
    ✓ kicks clients that do not log in
    ✓ kicks clients that do not send keepalive packets
    ✓ responds to ping requests 
    ✓ clients can log in and chat
    ✓ gives correct reason for kicking clients when shutting down 


  85 tests complete

History

0.6.7

Emit 'error' event instead of crashing when other computers abuse the minecraft protocol.

Big thanks to Robin Lambertz for this release.

0.6.6

• ping: fix calling callback twice when server sends kick
• server: send a kick packet when kicking clients. (thanks roblabla)
• ping: include latency property (thanks Jan Buschtöns)

0.6.5

• createServer: allow empty options
• server: support online mode and encryption (thanks roblabla)

0.6.4

• Allow minecraft username instead of mojang email. (thanks roblabla)

0.6.3

• y values when only 1 byte are always unsigned

0.6.2

• 0x0e: change face to unsigned byte

0.6.1

• 0x0d: fix incorrectly swapped stance and y