Parker2991/node-minecraft-protocol
1
0
Fork 0
mirror of https://github.com/PrismarineJS/node-minecraft-protocol.git synced 2024-12-02 03:56:54 -05:00
Code Issues Projects Releases Packages Wiki Activity
node-minecraft-protocol/README.md
Romain Beaumont c7f950148a add flying-squid to users
2015-08-30 21:34:28 +02:00

272 lines
7.8 KiB
Markdown
Raw Blame History

# minecraft protocol
[![NPM version](https://img.shields.io/npm/v/minecraft-protocol.svg)](http://npmjs.com/package/minecraft-protocol)
[![Build Status](https://img.shields.io/circleci/project/PrismarineJS/node-minecraft-protocol/master.svg)](https://circleci.com/gh/PrismarineJS/node-minecraft-protocol)
[![Join the chat at https://gitter.im/PrismarineJS/node-minecraft-protocol](https://img.shields.io/badge/gitter-join%20chat-brightgreen.svg)](https://gitter.im/PrismarineJS/node-minecraft-protocol)
Parse and serialize minecraft packets, plus authentication and encryption.
## Features
* Supports Minecraft version 1.8.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. See Test Coverage section below.
* Optimized for rapidly staying up to date with Minecraft protocol updates.
## Projects Using node-minecraft-protocol
* [mineflayer](https://github.com/andrewrk/mineflayer/) - create minecraft
bots with a stable, high level API.
* [mcserve](https://github.com/andrewrk/mcserve) - runs and monitors your
minecraft server, provides real-time web interface, allow your users to
create bots.
* [flying-squid](https://github.com/mhsjlw/flying-squid) create minecraft
servers with a high level API, also a minecraft server by itself.
## Usage
### Echo client example
```js
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.using[0];
var msg = jsonMsg.using[1];
if (username === client.username) return;
client.write("chat", {
message: msg
});
}
});
```
If the server is in offline mode, you may leave out the `password` option.
### Hello World server example
```js
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('login', {
entityId: client.id,
levelType: 'default',
gameMode: 0,
dimension: 0,
difficulty: 2,
maxPlayers: server.maxPlayers
});
client.write('position', {
x: 0,
y: 1.62,
z: 0,
yaw: 0,
pitch: 0,
onGround: true
});
var msg = { translate: 'chat.type.announcement', using: [
'Server',
'Hello, ' + client.username
]};
client.write("chat", { message: JSON.stringify(msg) });
});
```
## Installation
`npm install minecraft-protocol`
URSA, an optional dependency, should improve login times
for servers. However, it can be somewhat complicated to install.
Follow the instructions from
[Obvious/ursa](https://github.com/Obvious/ursa)
## Documentation
See [doc](doc/README.md)
## 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=email@example.com MC_PASSWORD=password npm test`
### Test Coverage
```
packets
✓ 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
✓ login,ClientBound,0x03
✓ 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,ServerBound,0x18
✓ play,ServerBound,0x19
✓ 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
✓ play,ClientBound,0x41
✓ play,ClientBound,0x42
✓ play,ClientBound,0x43
✓ play,ClientBound,0x44
✓ play,ClientBound,0x45
✓ play,ClientBound,0x46
✓ play,ClientBound,0x47
✓ play,ClientBound,0x48
✓ play,ClientBound,0x49
client
✓ pings the server (65754ms)
✓ connects successfully - online mode (STUBBED)
✓ connects successfully - offline mode (STUBBED)
✓ gets kicked when no credentials supplied in online mode (67167ms)
✓ does not crash for 10000ms (69597ms)
mc-server
✓ starts listening and shuts down cleanly
✓ kicks clients that do not log in (133ms)
✓ kicks clients that do not send keepalive packets (122ms)
✓ responds to ping requests
✓ clients can log in and chat (39ms)
✓ kicks clients when invalid credentials (8430ms)
✓ gives correct reason for kicking clients when shutting down (42ms)
123 tests complete (4 minutes)
```
## Debugging
You can enable some protocol debugging output using `NODE_DEBUG` environment variable:
```bash
NODE_DEBUG="minecraft-protocol" node [...]
```
## History
See [history](HISTORY.md)
Reference in a new issue View git blame Copy permalink