2013-04-14 06:21:28 -04:00
# minecraft protocol [![NPM version](https://badge.fury.io/js/minecraft-protocol.png)](http://badge.fury.io/js/minecraft-protocol)
2012-12-24 13:55:46 -05:00
2013-01-01 21:02:07 -05:00
Parse and serialize minecraft packets, plus authentication and encryption.
2013-01-01 04:14:38 -05:00
2013-01-01 16:01:43 -05:00
## Features
2014-04-12 06:34:19 -04:00
* Supports Minecraft version 1.7.6
2013-01-04 23:16:48 -05:00
* Parses all packets and emits events with packet fields as JavaScript
2013-01-01 16:01:43 -05:00
objects.
* Send a packet by supplying fields as a JavaScript object.
2013-01-04 23:16:48 -05:00
* 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
2013-01-26 22:50:48 -05:00
- Encryption and online mode
2013-01-04 23:16:48 -05:00
- Handshake
- Keep-alive checking
- Ping status
* Robust test coverage. See Test Coverage section below.
2013-01-01 16:01:43 -05:00
* Optimized for rapidly staying up to date with Minecraft protocol updates.
2013-02-12 13:58:53 -05:00
## Projects Using node-minecraft-protocol
2014-01-23 21:36:25 -05:00
* [mineflayer ](https://github.com/andrewrk/mineflayer/ ) - create minecraft
2013-02-12 13:58:53 -05:00
bots with a stable, high level API.
2014-01-23 21:36:25 -05:00
* [mcserve ](https://github.com/andrewrk/mcserve ) - runs and monitors your
2013-02-12 13:58:53 -05:00
minecraft server, provides real-time web interface, allow your users to
create bots.
2013-01-07 14:42:28 -05:00
2013-01-01 23:39:31 -05:00
## Usage
2013-01-01 04:14:38 -05:00
2013-01-03 21:42:35 -05:00
### Echo client example
2013-01-01 23:39:31 -05:00
```js
var mc = require('minecraft-protocol');
var client = mc.createClient({
2013-01-30 19:56:43 -05:00
host: "localhost", // optional
port: 25565, // optional
username: "email@example.com",
password: "12345678",
2013-01-01 23:39:31 -05:00
});
2014-04-11 13:40:15 -04:00
client.on('chat', function(packet) {
2013-01-03 21:42:35 -05:00
// Listen for chat messages and echo them back.
2013-07-09 02:13:17 -04:00
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(0x03, {
message: msg
});
}
2013-01-01 23:39:31 -05:00
});
```
2013-01-02 01:12:42 -05:00
2013-01-30 19:56:43 -05:00
If the server is in offline mode, you may leave out the `password` option.
2013-01-03 22:01:17 -05:00
### Hello World server example
```js
var mc = require('minecraft-protocol');
var server = mc.createServer({
2013-01-04 01:45:57 -05:00
'online-mode': true, // optional
encryption: true, // optional
host: '0.0.0.0', // optional
port: 25565, // optional
2013-01-03 22:01:17 -05:00
});
2013-01-04 01:45:57 -05:00
server.on('login', function(client) {
2014-04-11 13:40:15 -04:00
client.write('login', {
2013-01-04 22:47:54 -05:00
entityId: client.id,
2013-01-03 22:01:17 -05:00
levelType: 'default',
gameMode: 0,
dimension: 0,
difficulty: 2,
2013-01-04 01:45:57 -05:00
maxPlayers: server.maxPlayers
2013-01-03 22:01:17 -05:00
});
2014-04-11 13:40:15 -04:00
client.write('position', {
2013-01-03 22:01:17 -05:00
x: 0,
y: 1.62,
z: 0,
yaw: 0,
pitch: 0,
onGround: true
});
2014-04-11 13:40:15 -04:00
var msg = { translate: 'chat.type.announcement', using: [
2013-07-09 02:13:17 -04:00
'Server',
'Hello, ' + client.username
2013-07-09 05:18:26 -04:00
]};
2013-07-09 02:13:17 -04:00
client.write(0x03, { message: JSON.stringify(msg) });
2013-01-03 22:01:17 -05:00
});
```
2013-01-05 00:55:24 -05:00
## Installation
`npm install minecraft-protocol`
2014-04-14 23:55:20 -04:00
On Windows, first follow the Windows instructions from
[Obvious/ursa ](https://github.com/Obvious/ursa )
2013-01-05 00:55:24 -05:00
2013-01-08 01:52:56 -05:00
## Documentation
### mc.ping(options, callback)
`callback(err, pingResults)`
`pingResults` :
* `prefix`
* `protocol`
* `version`
* `motd`
* `playerCount`
* `maxPlayers`
2013-02-03 18:11:19 -05:00
### mc.createServer(options)
Returns a `Server` instance and starts listening.
### Server
#### server.onlineModeExceptions
This is a plain old JavaScript object. Add a key with the username you want to
be exempt from online mode or offline mode (whatever mode the server is in).
2013-02-03 18:53:34 -05:00
Make sure the entries in this object are all lower case.
2014-04-11 13:40:15 -04:00
#### server.clients
Javascript object mapping a `Client` from a clientId.
### server.playerCount
The amount of players currently present on the server.
2013-02-03 18:11:19 -05:00
#### server.maxPlayers
2014-04-11 13:40:15 -04:00
The maximum amount of players allowed on the server.
#### server.motd
The motd that is sent to the player when he is pinging the server
#### server.favicon
A base64 data string representing the favicon that will appear next to the server
on the mojang client's multiplayer list.
### mc.createClient(option)
Returns a `Client` instance and perform login
### Client
#### client.state
The internal state that is used to figure out which protocol state we are in during
packet parsing. This is one of the protocol.states.
#### client.isServer
True if this is a connection going from the server to the client,
False if it is a connection from client to server.
#### client.socket
Returns the internal nodejs Socket used to communicate with this client.
#### client.uuid
A string representation of the client's UUID. Note that UUIDs are unique for
each players, while playerNames, as of 1.7.7, are not unique and can change.
### client.username
The user's username.
### client.session
The user's session, as returned by the Yggdrasil system.
2013-01-08 01:52:56 -05:00
### Not Immediately Obvious Data Type Formats
2014-04-11 13:40:15 -04:00
Note : almost all data formats can be understood by looking at the packet
structure in lib/protocol.js
2013-01-08 01:52:56 -05:00
#### entityMetadata
2013-01-08 02:44:17 -05:00
Value looks like this:
2013-01-08 01:52:56 -05:00
```js
[
2013-01-08 02:44:17 -05:00
{type: 'slot', value: slot, key: 3},
{type: 'int', value: value, key: 4},
2013-01-08 01:52:56 -05:00
...
]
```
Where the key is the numeric metadata key and the value is the value of the
correct data type.
2013-01-02 01:12:42 -05:00
## Testing
* Ensure your system has the `java` executable in `PATH` .
2013-01-02 01:47:18 -05:00
* Download the appropriate version of `minecraft_server.jar` .
2013-01-31 04:04:38 -05:00
* `MC_SERVER_JAR=path/to/minecraft_server.jar MC_USERNAME=email@example.com MC_PASSWORD=password npm test`
2013-01-02 01:47:18 -05:00
2013-01-04 23:16:48 -05:00
### Test Coverage
```
2013-01-08 01:52:56 -05:00
packets
2014-04-11 13:40:15 -04:00
√ 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
√ 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,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
2013-01-08 01:52:56 -05:00
2013-01-04 23:16:48 -05:00
client
2014-04-11 13:40:15 -04:00
√ pings the server (32734ms)
√ connects successfully - online mode (23367ms)
√ connects successfully - offline mode (10261ms)
√ gets kicked when no credentials supplied in online mode (18400ms)
√ does not crash for 10000ms (24780ms)
2013-01-04 23:16:48 -05:00
mc-server
2014-04-11 13:40:15 -04:00
√ starts listening and shuts down cleanly (73ms)
√ kicks clients that do not log in (295ms)
√ kicks clients that do not send keepalive packets (266ms)
√ responds to ping requests (168ms)
√ clients can log in and chat (158ms)
√ kicks clients when invalid credentials (680ms)
√ gives correct reason for kicking clients when shutting down (123ms)
2013-01-04 23:16:48 -05:00
2014-04-11 13:40:15 -04:00
111 tests complete (3 minutes)
2013-01-04 23:16:48 -05:00
```
2013-01-26 15:35:52 -05:00
2013-04-15 00:52:32 -04:00
# Debugging
You can enable some protocol debugging output using `NODE_DEBUG` environment variable:
```bash
NODE_DEBUG="minecraft-protocol" node [...]
```
2013-01-26 15:35:52 -05:00
## History
2014-04-12 06:34:19 -04:00
### 0.12.1
* Updated protocol version to support 1.7.6
2014-04-11 13:40:15 -04:00
### 0.12.0
* Updated protocol version to support 1.7.2
* Overhaul the serializer backend to be more general-purpose and future-proof.
* Support listening packets by name (thanks [deathcap ](https://github.com/deathcap ))
* Support reading/writing a raw buffer to the socket.
2013-01-26 15:35:52 -05:00
2013-09-26 18:34:10 -04:00
### 0.11.6
* Updated protocol version to support 1.6.4 (thanks [Matt Bell ](https://github.com/mappum ))
2013-08-26 18:36:08 -04:00
### 0.11.5
* Fix handling of some conditional fields (thanks [Florian Wesch ](https://github.com/dividuum ))
2013-08-12 17:26:46 -04:00
### 0.11.4
* Chat packet string max length fix (thanks [Robin Lambertz ](https://github.com/roblabla ))
2013-07-13 06:14:48 -04:00
### 0.11.3
* packet 0x2c: packet writing fixed, UUID format simplified, tests updated
2013-07-11 06:33:09 -04:00
### 0.11.2
* 1.6.2 support fixes: updated 0x2c packets to include `elementList` and added 0x85 *Tile Editor Open* packets
2013-07-11 00:29:38 -04:00
### 0.11.1
* support minecraft protocol 1.6.2 / protocol version 74 (thanks [Matt Bell ](https://github.com/mappum ))
2013-07-09 04:20:37 -04:00
### 0.11.0
* support minecraft protocol 1.6.1 / protocol version 73 (thanks [Matt Bell ](https://github.com/mappum ))
2014-01-23 21:36:25 -05:00
* *note:* chat packets have a new format (see [the examples ](https://github.com/andrewrk/node-minecraft-protocol/tree/master/examples ) for how to upgrade).
2013-07-09 04:20:37 -04:00
2013-05-04 22:09:05 -04:00
### 0.10.1
* support minecraft protocol 1.5.2 / protocol version 61
2013-04-15 01:35:48 -04:00
### 0.10.0
* Added SRV record support when connecting to a server (thanks [Matt Stith ](https://github.com/stith ))
* 0x66: `shift` renamed to `mode` and changed from bool to byte
2013-04-08 11:04:35 -04:00
### 0.9.0
2013-04-15 01:03:28 -04:00
* 0xce: create changed from bool to byte (thanks [Robin Lambertz ](https://github.com/roblabla ))
2013-04-08 11:04:35 -04:00
2013-04-07 15:08:51 -04:00
### 0.8.1
2013-04-15 01:03:28 -04:00
* fix buffer length checking bug in readSlot() (thanks [Xabier de Zuazo ](https://github.com/zuazo ))
* fix C2 calculation bug (fixed #35 ) (thanks [Xabier de Zuazo ](https://github.com/zuazo ))
* fix oob Buffer at readEntityMetadata (fixed #40 ) (thanks [Xabier de Zuazo ](https://github.com/zuazo ))
2013-04-07 15:08:51 -04:00
2013-04-06 11:08:33 -04:00
### 0.8.0
2013-04-15 01:03:28 -04:00
* fix remaining bugs for 1.5.1 protocol (thanks [Xabier de Zuazo ](https://github.com/zuazo ))
* writing packets is 6% faster (thanks [Matt Bell ](https://github.com/mappum ))
2013-04-06 11:08:33 -04:00
2013-03-13 23:34:31 -04:00
### 0.7.9
2013-04-15 01:03:28 -04:00
* support minecraft protocol 1.5 / protocol version 60 (thanks [Matt Bell ](https://github.com/mappum ))
2013-03-13 23:34:31 -04:00
2013-02-10 21:06:45 -05:00
### 0.7.8
* server: ability to change `motd` and `maxPlayers`
* server: fix incorrect `playerCount`
2013-02-03 22:14:15 -05:00
### 0.7.7
* server: fix crash when client disconnects quickly
2013-02-03 18:57:43 -05:00
### 0.7.6
* onlineModeExceptions are all lowercase now. fixes security hole.
2013-02-03 18:22:44 -05:00
### 0.7.5
* server: add `onlineModeExceptions` . When server is in:
- online mode: these usernames are exempt from online mode.
- offline mode: these usernames must authenticate.
2013-02-03 16:36:53 -05:00
### 0.7.4
* server: online mode: don't log in client until username verification
2013-02-03 15:38:52 -05:00
### 0.7.3
* revert removing socket delays to reduce latency as it was causing
errors and test failures.
* server: Client now emits more predictable 'end' events.
2013-02-03 14:36:15 -05:00
### 0.7.2
* fix objectData writer. This fixes sending an 0x17 packet.
2013-02-02 02:45:33 -05:00
### 0.7.1
2013-04-15 01:03:28 -04:00
* remove socket delays to reduce latency. (thanks [Matt Bell ](https://github.com/mappum ))
2013-02-02 02:45:33 -05:00
2013-01-30 20:04:45 -05:00
### 0.7.0
* `createServer` : rename `encryption-enabled` option to `encryption` to stay
2013-04-15 01:03:28 -04:00
consistent with the examples. (thanks [Robin Lambertz ](https://github.com/roblabla ))
2013-01-30 20:04:45 -05:00
* `createClient` : don't require both `email` and `username` .
- The `username` and `password` arguments are used to authenticate with the
official minecraft servers and determine the case-correct username. If
you have migrated your user account to a mojang login, `username` looks
like an email address.
- If you leave out the `password` argument, `username` is used to connect
directly to the server. In this case you will get kicked if the server is
in online mode.
2013-01-29 12:52:07 -05:00
### 0.6.7
Emit 'error' event instead of crashing when other computers abuse the
minecraft protocol.
Big thanks to [Robin Lambertz ](https://github.com/roblabla ) for this release.
2013-01-27 19:40:56 -05:00
### 0.6.6
* ping: fix calling callback twice when server sends kick
2013-04-15 01:03:28 -04:00
* server: send a kick packet when kicking clients. (thanks [Robin Lambertz ](https://github.com/roblabla ))
* ping: include latency property (thanks [Jan Buschtöns ](https://github.com/silvinci ))
2013-01-27 19:40:56 -05:00
2013-01-26 22:50:48 -05:00
### 0.6.5
* createServer: allow empty options
2013-04-15 01:03:28 -04:00
* server: support online mode and encryption (thanks [Robin Lambertz ](https://github.com/roblabla ))
2013-01-26 22:50:48 -05:00
2013-01-26 15:35:52 -05:00
### 0.6.4
2013-04-15 01:03:28 -04:00
* Allow minecraft username instead of mojang email. (thanks [Robin Lambertz ](https://github.com/roblabla ))
2013-01-26 15:35:52 -05:00
### 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