Permalink
Browse files

v0.2.0 -- Add missing commands, add docco compatibility, and various …

…tweaks.
  • Loading branch information...
remixz committed Feb 17, 2013
1 parent 1c00468 commit 508aab3b30fc201a5eb4bb2b82afe60ffc59a708
Showing with 110 additions and 60 deletions.
  1. +1 −0 .gitignore
  2. +8 −6 README.md
  3. +1 −0 lib/blocks.json
  4. +18 −0 lib/colors.json
  5. +81 −53 lib/minecraft.js
  6. +1 −1 package.json
View
@@ -1,2 +1,3 @@
+/docs
/node_modules
.DS_Store
View
@@ -1,13 +1,7 @@
## ![minecraft-pi](https://raw.github.com/remixz/minecraft-pi/master/minecraft-pi.png)
-*Work in progress.*
-
minecraft-pi allows you to control a [Minecraft: Pi Edition](http://pi.minecraft.net/) server from Node.js. This is intended as a lower-level module, and is meant to be extended on for bigger projects. However, the commands are simple enough to play with as-is.
-*TODO:*
-
-* Better documentation
-
### Usage
```js
@@ -17,4 +11,12 @@ var client = new Minecraft('localhost', 4711, function() {
client.chat('Yo dawg, I heard you like Node.js, so I put some Node.js in your Pi so you can Node.js while you Pi.');
client.setBlock(3, 14, 15, client.blocks['DIAMOND_BLOCK']);
});
+```
+
+### Documentation
+
+```bash
+[sudo] npm install -g docco
+docco lib/minecraft.js
+open docs/minecraft.html
```
View
@@ -25,6 +25,7 @@
"BED": 26,
"COBWEB": 30,
"GRASS_TALL": 31,
+ "WOOL": 35,
"FLOWER_YELLOW": 37,
"FLOWER_CYAN": 38,
"MUSHROOM_BROWN": 39,
View
@@ -0,0 +1,18 @@
+{
+ "WHITE": 0,
+ "ORANGE": 1,
+ "MAGENTA": 2,
+ "LIGHT_BLUE": 3,
+ "YELLOW": 4,
+ "LIME": 5,
+ "PINK": 6,
+ "GRAY": 7,
+ "LIGHT_GRAY": 8,
+ "CYAN": 9,
+ "PURPLE": 10,
+ "BLUE": 11,
+ "BROWN": 12,
+ "GREEN": 13,
+ "RED": 14,
+ "BLACK": 15
+}
View
@@ -1,24 +1,19 @@
-/**
- * minecraft-pi - A Node.js API for Minecraft: Pi Edition.
- *
- * @package minecraft-pi
- * @author Zachary Bruggeman <talkto@zachbruggeman.me>
- */
-
-/**
- * Dependencies
- */
+ // minecraft-pi 0.2.0
+ // (c) 2013 Zachary Bruggeman <talkto@zachbruggeman.me>
+ // minecraft-pi is licensed under the MIT license.
+
+// ## Dependencies
var net = require('net');
var os = require('os');
var Blocks = require('./blocks.json');
+var Colors = require('./colors.json');
-/**
- * Constructor
- */
+// ## Constructor
function Minecraft (host, port, callback) {
var self = this;
this.connection = net.connect({port: port, host: host}, function () {
+ // When a new `Minecraft` is created, it connects to the port and host given, and preforms the callback, if it exists, once connected.
console.log('Connected to server!');
self.chat('Hello from Node.js! Commanding from ' + os.hostname());
if (callback) {
@@ -31,12 +26,18 @@ function Minecraft (host, port, callback) {
});
};
+// `Blocks` holds names of each block, tied to an item ID. This allows for an easier way to reference blocks.
Minecraft.prototype.blocks = Blocks;
+// `Colors` holds color data codes, which are used to create colored wool.
+Minecraft.prototype.colors = Colors;
+
+// If you're wanting to write your own API, make sure that your commands written end with a new line! Without it, the commands will not work.
Minecraft.prototype.send = function (command) {
this.connection.write(command + '\n');
};
+// When writing a custom callback, make sure to end the connection with `client.end()`.
Minecraft.prototype.sendReceive = function (command, callback) {
var self = this;
var defaultCallback = function (data) {
@@ -45,103 +46,130 @@ Minecraft.prototype.sendReceive = function (command, callback) {
};
var callback = callback ? callback : defaultCallback;
- this.connection.write(command + '\n');
+ this.send(command);
this.connection.on('data', callback);
};
Minecraft.prototype.end = function () {
this.connection.destroy();
-}
+};
-/**
- * Commands
- */
+// ## Commands
-/**
- * World commands
- */
+// ### World Commands
+// `client.getBlock(x, y, z, callback)` -- Returns the block ID at the selected coordinates.
Minecraft.prototype.getBlock = function (x, y, z, callback) {
- this.sendReceive('world.getBlock(' + x + ',' + y + ',' + z + ')', callback);
+ return this.sendReceive('world.getBlock(' + x + ',' + y + ',' + z + ')', callback);
+};
+
+// `client.setBlock(x, y, z, id, [data])` -- Places a block with the ID of `id` at the selected coordinates, plus data if it is appended. You can use `client.blocks['BLOCK_NAME']` instead of the actual ID.
+Minecraft.prototype.setBlock = function (x, y, z, id, data) {
+ var command = data ? this.send('world.setBlock(' + x + ',' + y + ',' + z + ',' + id + ',' + data + ')') : this.send('world.setBlock(' + x + ',' + y + ',' + z + ',' + id + ')');
+ return command;
};
-Minecraft.prototype.setBlock = function (x, y, z, id) {
- this.send('world.setBlock(' + x + ',' + y + ',' + z + ',' + id + ')');
+// `client.setBlocks(x1, y1, z1, x2, y2, z2, id, [data])` -- Places a cuboid of blocks with the coordinate set using the specified id and data. You can use `client.blocks['BLOCK_NAME']` instead of the actual ID.
+Minecraft.prototype.setBlocks = function (x1, y1, z1, x2, y2, z2, id, data) {
+ var command = data ? this.send('world.setBlocks(' + x1 + ',' + y1 + ',' + z1 + ',' + x2 + ',' + y2 + ',' + z2 + ',' + id + ',' + data + ')') : this.send('world.setBlocks(' + x1 + ',' + y1 + ',' + z1 + ',' + x2 + ',' + y2 + ',' + z2 + ',' + id + ')');
+ return command;
};
+// `client.getHeight(x, z, callback)` -- Returns the Y coordinate of the last block that isn't solid from the top-down in the coordinate pair.
Minecraft.prototype.getHeight = function (x, z, callback) {
- this.sendReceive('world.getHeight(' + x + ',' + z + ')', callback);
+ return this.sendReceive('world.getHeight(' + x + ',' + z + ')', callback);
};
+// `client.saveCheckpoint()` -- Saves a checkpoint that can be used to restore the world.
Minecraft.prototype.saveCheckpoint = function () {
- this.send('world.checkpoint.save()');
+ return this.send('world.checkpoint.save()');
};
+// `client.restoreCheckpoint()` -- Restores to the last checkpoint.
Minecraft.prototype.restoreCheckpoint = function () {
- this.send('world.checkpoint.restore()');
+ return this.send('world.checkpoint.restore()');
+};
+
+// `client.worldSetting(key, value)` -- Sets a world property.
+//
+// Values are boolean, 0 or 1. The current two keys are:
+//
+// * `world_immutable`
+// * `nametags_visible`
+Minecraft.prototype.worldSetting = function (key, value) {
+ return this.send('world.setting(' + key + ',' + value + ')');
};
-Minecraft.prototype.setting = function (key, value) {
- this.send('world.setting(' + key + ',' + value + ')');
+// `client.getPlayerIds(callback)` -- Returns the entity IDs of the players online.
+Minecraft.prototype.getPlayerIds = function (callback) {
+ return this.sendReceive('world.getPlayerIds()');
};
+// `client.chat(message)` -- Displays a message in the chat.
Minecraft.prototype.chat = function (message) {
- this.send('chat.post(' + message + ')');
+ return this.send('chat.post(' + message + ')');
};
-/**
- * Camera commands
- */
+// ### Camera Commands
+// `client.setCameraMode(mode)` -- Sets the player's camera mode. Accepts `normal`, `thirdPerson` and `fixed`.
Minecraft.prototype.setCameraMode = function (mode) {
var self = this;
- // I've consolidated three commands into one for ease of use.
switch (mode) {
case 'normal':
- self.send('camera.mode.setNormal()');
+ return self.send('camera.mode.setNormal()');
break;
case 'thirdPerson':
- self.send('camera.mode.setThirdPerson()');
+ return self.send('camera.mode.setThirdPerson()');
break;
case 'fixed':
- self.send('camera.mode.setFixed()');
+ return self.send('camera.mode.setFixed()');
break;
};
};
+// `client.setCameraPosition(x, y, z)` -- Sets the camera's position at the selected coordinates.
Minecraft.prototype.setCameraPosition = function (x, y, z) {
- this.send('camera.mode.setPos(' + x + ',' + y + ',' + z + ')');
+ return this.send('camera.mode.setPos(' + x + ',' + y + ',' + z + ')');
};
-/**
- * Player commands
- */
+// ### Player commands
+// `client.getTile()` -- Gets the player's coordinates to the nearest block.
Minecraft.prototype.getTile = function (callback) {
- this.sendReceive('player.getTile()', callback);
+ return this.sendReceive('player.getTile()', callback);
};
+// `client.setTile(x, y, z)`-- Sets the player's coordinates to the specified block.
Minecraft.prototype.setTile = function (x, y, z) {
- this.send('player.setTile(' + x + ',' + y + ',' + z + ')');
+ return this.send('player.setTile(' + x + ',' + y + ',' + z + ')');
};
+// `client.getPos()` -- Gets the precise position of the player.
Minecraft.prototype.getPos = function (callback) {
- this.sendReceive('player.getPos()', callback);
+ return this.sendReceive('player.getPos()', callback);
};
+// `client.setPos(x, y, z)` -- Sets the position of the player precisely.
Minecraft.prototype.setPos = function (x, y, z) {
- this.send('player.setPos(' + x + ',' + y + ',' + z + ')');
+ return this.send('player.setPos(' + x + ',' + y + ',' + z + ')');
+};
+
+// `client.playerSetting(key, value)` -- Sets a player property.
+//
+// Values are boolean, 0 or 1. The current key available is:
+//
+// * `autojump`
+Minecraft.prototype.playerSetting = function (key, value) {
+ return this.send('player.setting(' + key + ',' + value + ')');
};
-/**
- * Event commands
- */
+// ### Event commands
+// These are in need of proper documentation. If you know about these, please send a pull request! :-)
Minecraft.prototype.eventsBlockHits = function(callback) {
- this.sendReceive('events.block.hits()', callback);
+ return this.sendReceive('events.block.hits()', callback);
};
Minecraft.prototype.eventsClear = function() {
- this.send('events.clear()');
+ return this.send('events.clear()');
};
-/**
- * Exports
- */
+// ## Exports
module.exports = Minecraft;
View
@@ -3,7 +3,7 @@
"name": "minecraft-pi",
"description": "A Node.js API for Minecraft: Pi Edition.",
"license": "MIT",
- "version": "0.1.1",
+ "version": "0.2.0",
"homepage": "https://github.com/remixz/minecraft-pi",
"repository": {
"type": "git",

0 comments on commit 508aab3

Please sign in to comment.