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.16.5), 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, 1.20.2, 1.20.3 and 1.20.4)
- 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 - 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 - A tool to capture Minecraft packets in a buffer then view them in a browser.
- aresrpg - An open-source mmorpg minecraft server.
- SteveProxy - Proxy for Minecraft with the ability to change the gameplay using plugins.
- and several thousands others
Installation
npm install minecraft-protocol
Documentation
Usage
Echo client example
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:
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
For a more up to date example, see examples/server/server.js.
const mc = require('minecraft-protocol')
const nbt = require('prismarine-nbt')
const server = mc.createServer({
'online-mode': true, // optional
encryption: true, // optional
host: '0.0.0.0', // optional
port: 25565, // optional
version: '1.20.4'
})
const mcData = require('minecraft-data')(server.version)
function chatText (text) {
return mcData.supportFeature('chatPacketsUseNbtComponents')
? nbt.comp({ text: nbt.string(text) })
: JSON.stringify({ text })
}
server.on('playerJoin', function(client) {
const loginPacket = mcData.loginPacket
client.write('login', {
...loginPacket,
entityId: client.id,
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 message = {
translate: 'chat.type.announcement',
with: [
'Server',
'Hello, world!'
]
}
if (mcData.supportFeature('signedChat')) {
client.write('player_chat', {
plainMessage: message,
signedChatContent: '',
unsignedChatContent: chatText(message),
type: 0,
senderUuid: 'd3527a0b-bc03-45d5-a878-2aafdd8c8a43', // random
senderName: JSON.stringify({ text: 'me' }),
senderTeam: undefined,
timestamp: Date.now(),
salt: 0n,
signature: mcData.supportFeature('useChatSessions') ? undefined : Buffer.alloc(0),
previousMessages: [],
filterType: 0,
networkName: JSON.stringify({ text: 'me' })
})
} else {
client.write('chat', { message: JSON.stringify({ text: message }), position: 0, sender: 'me' })
}
})
Testing
- Ensure your system has the
java
executable inPATH
. 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