minecraft protocol

Parse and serialize minecraft packets, plus authentication and encryption.

Features

• 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
  • TODO - 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.

Minecraft Compatibility

Supports Minecraft version 1.4.7pre

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 });
});

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

  client
    ✓ pings the server (6164ms)
    ✓ connects successfully - online mode (2527ms)
    ✓ connects successfully - offline mode (1902ms)
    ✓ gets kicked when no credentials supplied in online mode (3720ms)
    ✓ does not crash for 10000ms (11731ms)
  mc-server
    ✓ starts listening and shuts down cleanly 
    ✓ kicks clients that do not log in (103ms)
    ✓ kicks clients that do not send keepalive packets (104ms)
    ✓ responds to ping requests 
    ✓ clients can log in and chat (43ms)
    ✓ gives correct reason for kicking clients when shutting down 


  11 tests complete (45 seconds)

Updating to a newer protocol version

In most cases you should only have to do the following:

1. In packets.json:

• Update protocolVersion to the correct number.
• Edit the data structure to reflect the new packet layout.

2. Update the "Minecraft Compatibility" section above in this README.
3. Run the test suite to make sure everything still works. See "Testing" above.