From 653e8d05eed146ced69bfcab4af722a5fc69b791 Mon Sep 17 00:00:00 2001 From: Romain Beaumont Date: Fri, 29 May 2015 13:24:12 +0200 Subject: [PATCH] split the readme.md into 2 new files : history.md and doc/readme.md, fix #183 --- HISTORY.md | 208 +++++++++++++++++++++++++++++++ README.md | 333 +------------------------------------------------- doc/README.md | 126 +++++++++++++++++++ 3 files changed, 337 insertions(+), 330 deletions(-) create mode 100644 HISTORY.md create mode 100644 doc/README.md diff --git a/HISTORY.md b/HISTORY.md new file mode 100644 index 0000000..7a28618 --- /dev/null +++ b/HISTORY.md @@ -0,0 +1,208 @@ +# History + +## 0.14.0 + + * Huge rewrite of the internals, using transform streams, which eliminates two + classes of problems from node-minecraft-protocol : + * Uncatchable errors being triggered inside the protocol parser + * Packets ariving out of order, causing several race conditions + * All the attributes that were previously exposed via `mc.protocol` are now directly + attached to the `mc` object, e.g. `mc.protocol.states` => `mc.states`. This is + prone to further changes. + * open_window now reports the entityId correctly for horses + * Properly handle the set_compression packet + * Fix small bug in scoreboard_team and player_info packets causing crashes + * Fix the login implementation logging out people from their launchers. + +## 0.13.4 + + * Added hook to modify server ping (thanks [Brian Schlenker](https://github.com/bschlenk)) + * Exposed the Client class to the browser, after removing node-specific details + * Fixed the examples + * Silenced the "DID NOT PARSE THE WHOLE THING" debug message, and made it print more useful info + * Updated ursa-purejs dependency, which in turned fixed windows version of node-minecraft-protocol. + +## 0.13.3 + + * Fixed readPosition for negative packets (thanks [rom1504](https://github.com/rom1504)) + +## 0.13.2 + + * Fixed particle packet. + * Fixed release. 0.13.1 release was missing an entire folder. + +## 0.13.1 + + * Externalized rsa-wrap library to its own npm module, named ursa-native + * Fixed broken bed-related packets (thanks [rom1504](https://github.com/rom1504)) + +## 0.13.0 + + * Updated protocol version to support 1.8.1 (thanks [wtfaremyinitials](https://github.com/wtfaremyinitials)) + * Lots of changes in how some formats are handled. + * Crypto now defaults to a pure-js library if URSA is missing, making the lib easier to use on windows. + * Fix a bug in yggdrasil handling of sessions, making reloading a session impossible (thanks [Frase](https://github.com/mrfrase3)) + * Set noDelay on the TCP streams, making the bot a lot less laggy. + +## 0.12.3 + + * Fix for/in used over array, causing glitches with augmented Array prototypes (thanks [pelikhan](https://github.com/pelikhan)) + +## 0.12.2 + + * Updated protocol version to support 1.7.10 + * Some bug fixes in parser (thanks [Luke Young](https://github.com/innoying)) + * 'raw' event to catch all raw buffers (thanks [deathcap](https://github.com/deathcap)) + * Misc bug fixes + +## 0.12.1 + + * Updated protocol version to support 1.7.6 + +## 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. + +## 0.11.6 + + * Updated protocol version to support 1.6.4 (thanks [Matt Bell](https://github.com/mappum)) + +## 0.11.5 + + * Fix handling of some conditional fields (thanks [Florian Wesch](https://github.com/dividuum)) + +## 0.11.4 + + * Chat packet string max length fix (thanks [Robin Lambertz](https://github.com/roblabla)) + +## 0.11.3 + + * packet 0x2c: packet writing fixed, UUID format simplified, tests updated + +## 0.11.2 + + * 1.6.2 support fixes: updated 0x2c packets to include `elementList` and added 0x85 *Tile Editor Open* packets + +## 0.11.1 + + * support minecraft protocol 1.6.2 / protocol version 74 (thanks [Matt Bell](https://github.com/mappum)) + +## 0.11.0 + + * support minecraft protocol 1.6.1 / protocol version 73 (thanks [Matt Bell](https://github.com/mappum)) + * *note:* chat packets have a new format (see [the examples](https://github.com/andrewrk/node-minecraft-protocol/tree/master/examples) for how to upgrade). + +## 0.10.1 + + * support minecraft protocol 1.5.2 / protocol version 61 + +## 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 + +## 0.9.0 + + * 0xce: create changed from bool to byte (thanks [Robin Lambertz](https://github.com/roblabla)) + +## 0.8.1 + + * 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)) + +## 0.8.0 + + * 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)) + +## 0.7.9 + + * support minecraft protocol 1.5 / protocol version 60 (thanks [Matt Bell](https://github.com/mappum)) + +## 0.7.8 + + * server: ability to change `motd` and `maxPlayers` + * server: fix incorrect `playerCount` + +## 0.7.7 + + * server: fix crash when client disconnects quickly + +## 0.7.6 + + * onlineModeExceptions are all lowercase now. fixes security hole. + +## 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. + +## 0.7.4 + + * server: online mode: don't log in client until username verification + +## 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. + +## 0.7.2 + + * fix objectData writer. This fixes sending an 0x17 packet. + +## 0.7.1 + + * remove socket delays to reduce latency. (thanks [Matt Bell](https://github.com/mappum)) + +## 0.7.0 + + * `createServer`: rename `encryption-enabled` option to `encryption` to stay + consistent with the examples. (thanks [Robin Lambertz](https://github.com/roblabla)) + * `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. + +## 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. + +## 0.6.6 + + * ping: fix calling callback twice when server sends kick + * 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)) + +## 0.6.5 + + * createServer: allow empty options + * server: support online mode and encryption (thanks [Robin Lambertz](https://github.com/roblabla)) + +## 0.6.4 + + * Allow minecraft username instead of mojang email. (thanks [Robin Lambertz](https://github.com/roblabla)) + +## 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 diff --git a/README.md b/README.md index 51b0ecc..f7a17b5 100644 --- a/README.md +++ b/README.md @@ -111,130 +111,8 @@ Follow the instructions from ## Documentation -### mc.ping(options, callback) +See [doc](doc/README.md) -`callback(err, pingResults)` - -`pingResults`: - -#### Old version - * `prefix` - * `protocol` - * `version` - * `motd` - * `playerCount` - * `maxPlayers` - -#### New version - * `description` - * `players` - * `max` - * `online` - * `sample` - * `id` - * `name` - * `version` - * `name` - * `protocol` - * `favicon` - * `latency` - -### 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). - -Make sure the entries in this object are all lower case. - -#### server.clients - -Javascript object mapping a `Client` from a clientId. - -### server.playerCount - -The amount of players currently present on the server. - -#### server.maxPlayers - -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(options) - -Returns a `Client` instance and perform login. - -`options` is an object containing the properties : - * username - * port : default to 25565 - * password : can be omitted (if the tokens are also omitted then it tries to connect in offline mode) - * host : default to localhost - * clientToken : generated if a password is given - * accessToken : generated if a password is given - * keepAlive : send keep alive packets : default to true - -### 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. - -### Not Immediately Obvious Data Type Formats - -Note : almost all data formats can be understood by looking at the packet -structure in lib/protocol.js - -#### entityMetadata - -Value looks like this: - -```js -[ - {type: 'slot', value: slot, key: 3}, - {type: 'int', value: value, key: 4}, - ... -] -``` - -Where the key is the numeric metadata key and the value is the value of the -correct data type. ## Testing @@ -379,7 +257,7 @@ correct data type. 123 tests complete (4 minutes) ``` -# Debugging +## Debugging You can enable some protocol debugging output using `NODE_DEBUG` environment variable: @@ -389,209 +267,4 @@ NODE_DEBUG="minecraft-protocol" node [...] ## History -### 0.14.0 - - * Huge rewrite of the internals, using transform streams, which eliminates two - classes of problems from node-minecraft-protocol : - * Uncatchable errors being triggered inside the protocol parser - * Packets ariving out of order, causing several race conditions - * All the attributes that were previously exposed via `mc.protocol` are now directly - attached to the `mc` object, e.g. `mc.protocol.states` => `mc.states`. This is - prone to further changes. - * open_window now reports the entityId correctly for horses - * Properly handle the set_compression packet - * Fix small bug in scoreboard_team and player_info packets causing crashes - * Fix the login implementation logging out people from their launchers. - -### 0.13.4 - - * Added hook to modify server ping (thanks [Brian Schlenker](https://github.com/bschlenk)) - * Exposed the Client class to the browser, after removing node-specific details - * Fixed the examples - * Silenced the "DID NOT PARSE THE WHOLE THING" debug message, and made it print more useful info - * Updated ursa-purejs dependency, which in turned fixed windows version of node-minecraft-protocol. - -### 0.13.3 - - * Fixed readPosition for negative packets (thanks [rom1504](https://github.com/rom1504)) - -### 0.13.2 - - * Fixed particle packet. - * Fixed release. 0.13.1 release was missing an entire folder. - -### 0.13.1 - - * Externalized rsa-wrap library to its own npm module, named ursa-native - * Fixed broken bed-related packets (thanks [rom1504](https://github.com/rom1504)) - -### 0.13.0 - - * Updated protocol version to support 1.8.1 (thanks [wtfaremyinitials](https://github.com/wtfaremyinitials)) - * Lots of changes in how some formats are handled. - * Crypto now defaults to a pure-js library if URSA is missing, making the lib easier to use on windows. - * Fix a bug in yggdrasil handling of sessions, making reloading a session impossible (thanks [Frase](https://github.com/mrfrase3)) - * Set noDelay on the TCP streams, making the bot a lot less laggy. - -### 0.12.3 - - * Fix for/in used over array, causing glitches with augmented Array prototypes (thanks [pelikhan](https://github.com/pelikhan)) - -### 0.12.2 - - * Updated protocol version to support 1.7.10 - * Some bug fixes in parser (thanks [Luke Young](https://github.com/innoying)) - * 'raw' event to catch all raw buffers (thanks [deathcap](https://github.com/deathcap)) - * Misc bug fixes - -### 0.12.1 - - * Updated protocol version to support 1.7.6 - -### 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. - -### 0.11.6 - - * Updated protocol version to support 1.6.4 (thanks [Matt Bell](https://github.com/mappum)) - -### 0.11.5 - - * Fix handling of some conditional fields (thanks [Florian Wesch](https://github.com/dividuum)) - -### 0.11.4 - - * Chat packet string max length fix (thanks [Robin Lambertz](https://github.com/roblabla)) - -### 0.11.3 - - * packet 0x2c: packet writing fixed, UUID format simplified, tests updated - -### 0.11.2 - - * 1.6.2 support fixes: updated 0x2c packets to include `elementList` and added 0x85 *Tile Editor Open* packets - -### 0.11.1 - - * support minecraft protocol 1.6.2 / protocol version 74 (thanks [Matt Bell](https://github.com/mappum)) - -### 0.11.0 - - * support minecraft protocol 1.6.1 / protocol version 73 (thanks [Matt Bell](https://github.com/mappum)) - * *note:* chat packets have a new format (see [the examples](https://github.com/andrewrk/node-minecraft-protocol/tree/master/examples) for how to upgrade). - -### 0.10.1 - - * support minecraft protocol 1.5.2 / protocol version 61 - -### 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 - -### 0.9.0 - - * 0xce: create changed from bool to byte (thanks [Robin Lambertz](https://github.com/roblabla)) - -### 0.8.1 - - * 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)) - -### 0.8.0 - - * 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)) - -### 0.7.9 - - * support minecraft protocol 1.5 / protocol version 60 (thanks [Matt Bell](https://github.com/mappum)) - -### 0.7.8 - - * server: ability to change `motd` and `maxPlayers` - * server: fix incorrect `playerCount` - -### 0.7.7 - - * server: fix crash when client disconnects quickly - -### 0.7.6 - - * onlineModeExceptions are all lowercase now. fixes security hole. - -### 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. - -### 0.7.4 - - * server: online mode: don't log in client until username verification - -### 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. - -### 0.7.2 - - * fix objectData writer. This fixes sending an 0x17 packet. - -### 0.7.1 - - * remove socket delays to reduce latency. (thanks [Matt Bell](https://github.com/mappum)) - -### 0.7.0 - - * `createServer`: rename `encryption-enabled` option to `encryption` to stay - consistent with the examples. (thanks [Robin Lambertz](https://github.com/roblabla)) - * `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. - -### 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. - -### 0.6.6 - - * ping: fix calling callback twice when server sends kick - * 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)) - -### 0.6.5 - - * createServer: allow empty options - * server: support online mode and encryption (thanks [Robin Lambertz](https://github.com/roblabla)) - -### 0.6.4 - - * Allow minecraft username instead of mojang email. (thanks [Robin Lambertz](https://github.com/roblabla)) - -### 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 +See [history](HISTORY.md) diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..75dce5b --- /dev/null +++ b/doc/README.md @@ -0,0 +1,126 @@ +# Documentation + +## mc.ping(options, callback) + +`callback(err, pingResults)` + +`pingResults`: + +## Old version + * `prefix` + * `protocol` + * `version` + * `motd` + * `playerCount` + * `maxPlayers` + +## New version + * `description` + * `players` + * `max` + * `online` + * `sample` + * `id` + * `name` + * `version` + * `name` + * `protocol` + * `favicon` + * `latency` + +## 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). + +Make sure the entries in this object are all lower case. + +## server.clients + +Javascript object mapping a `Client` from a clientId. + +## server.playerCount + +The amount of players currently present on the server. + +## server.maxPlayers + +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(options) + +Returns a `Client` instance and perform login. + +`options` is an object containing the properties : + * username + * port : default to 25565 + * password : can be omitted (if the tokens are also omitted then it tries to connect in offline mode) + * host : default to localhost + * clientToken : generated if a password is given + * accessToken : generated if a password is given + * keepAlive : send keep alive packets : default to true + +## 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. + +## Not Immediately Obvious Data Type Formats + +Note : almost all data formats can be understood by looking at the packet +structure in lib/protocol.js + +## entityMetadata + +Value looks like this: + +```js +[ + {type: 'slot', value: slot, key: 3}, + {type: 'int', value: value, key: 4}, + ... +] +``` + +Where the key is the numeric metadata key and the value is the value of the +correct data type.