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)
• 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 add forge support to minecraft-protocol

Projects Using node-minecraft-protocol

• mineflayer - create minecraft bots with a stable, high level API.
• mcserve - runs and monitors your minecraft server, provides real-time web interface, allow your users to create bots.
• flying-squid create minecraft servers with a high level API, also a minecraft server by itself.
• pakkit To monitor your packets
• minecraft-packet-debugger to easily debug your minecraft packets

Usage

Echo client example

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.with[0].text;
    var 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.

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
  version: '1.16'
});
server.on('login', function(client) {
  const w = {
    piglin_safe: {
      type: 'byte',
      value: 0
    },
    natural: {
      type: 'byte',
      value: 1
    },
    ambient_light: {
      type: 'float',
      value: 0
    },
    infiniburn: {
      type: 'string',
      value: 'minecraft:infiniburn_overworld'
    },
    respawn_anchor_works: {
      type: 'byte',
      value: 0
    },
    has_skylight: {
      type: 'byte',
      value: 1
    },
    bed_works: {
      type: 'byte',
      value: 1
    },
    has_raids: {
      type: 'byte',
      value: 1
    },
    name: {
      type: 'string',
      value: 'minecraft:overworld'
    },
    logical_height: {
      type: 'int',
      value: 256
    },
    shrunk: {
      type: 'byte',
      value: 0
    },
    ultrawarm: {
      type: 'byte',
      value: 0
    },
    has_ceiling: {
      type: 'byte',
      value: 0
    }
  }
  client.write('login', {
    entityId: client.id,
    levelType: 'default',
    gameMode: 0,
    previousGameMode: 255,
    worldNames: ['minecraft:overworld'],
    dimensionCodec: {name: '', type:'compound', value: {dimension: {type: 'list', value: {type: 'compound', value: [w]}}}},
    dimension: 'minecraft:overworld',
    worldName: 'minecraft:overworld',
    difficulty: 2,
    hashedSeed: [0, 0],
    maxPlayers: server.maxPlayers,
    reducedDebugInfo: false,
    enableRespawnScreen: true
  });
  client.write('position', {
    x: 0,
    y: 1.62,
    z: 0,
    yaw: 0,
    pitch: 0,
    flags: 0x00
  });
  var msg = {
    translate: 'chat.type.announcement',
    "with": [
      'Server',
      'Hello, world!'
    ]
  };
  client.write("chat", { message: JSON.stringify(msg), position: 0, sender: '0' });
});

Installation

npm install minecraft-protocol

Documentation

See doc See faq

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:

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

Related

• node-rcon can be used to access the rcon server in the minecraft server
• map-colors can be used to convert any image into a buffer of minecraft compatible colors