Fix issue #196

docs/API-Reference.md

@@ -371,8 +371,20 @@ Walter Higgins
    * [Drone.hemisphere0() method](#dronehemisphere0-method)
    * [Drone.stairs() function](#dronestairs-function)
    * [Drone Trees methods](#drone-trees-methods)
+   * [Drone.castle() method](#dronecastle-method)
+   * [Drone.chessboard() method](#dronechessboard-method)
+   * [Drone.cottage() method](#dronecottage-method)
+   * [Drone.cottage_road() method](#dronecottage_road-method)
+   * [Drone.dancefloor() method](#dronedancefloor-method)
+   * [Parameters](#parameters)
+   * [Drone.fort() method](#dronefort-method)
+   * [Drone.hangtorch() method](#dronehangtorch-method)
+   * [Drone.lcdclock() method.](#dronelcdclock-method)
+   * [Drone.logojs() method](#dronelogojs-method)
+   * [Drone.maze() method](#dronemaze-method)
    * [Drone.rainbow() method](#dronerainbow-method)
    * [Drone.spiral_stairs() method](#dronespiral_stairs-method)
+   * [Drone.temple() method](#dronetemple-method)
  * [Blocks Module](#blocks-module)
    * [Examples](#examples)
  * [Fireworks Module](#fireworks-module)
@@ -3637,7 +3649,7 @@ Creates the text out of blocks. Useful for large-scale in-game signs.
 
 To create a 2-line high message using glowstone...
 
-    blocktype("Hello\nWorld",blocks.glowstone);
+    blocktype('Hello\nWorld', blocks.glowstone);
 
 ![blocktype example][imgbt1]
 
@@ -4099,6 +4111,243 @@ None of the tree methods require parameters. Tree methods will only be
 successful if the tree is placed on grass in a setting where trees can
 grow.
 
+### Drone.castle() method
+
+Creates a Castle. A castle is just a big wide fort with 4 taller forts at each corner. 
+See also Drone.fort() method.
+
+#### Parameters
+ 
+ * side - How many blocks wide and long the castle will be (default: 24. Must be greater than 19)
+ * height - How tall the castle will be (default: 10. Must be geater than 7)
+
+#### Example
+
+At the in-game prompt you can create a castle by looking at a block and typing:
+
+```javascript
+/js castle()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the castle() method.
+
+```javascript
+var d = new Drone(player);
+d.castle();
+```
+![castle example](img/castleex1.png)
+
+### Drone.chessboard() method
+
+Creates a tile pattern of given block types and size
+
+#### Parameters
+
+ * whiteBlock - (optional: default blocks.wool.white)
+ * blackBlock - (optional: default blocks.wool.black)
+ * width - width of the chessboard
+ * length - length of the chessboard
+
+#### Example
+
+At the in-game prompt you can create a chessboard by looking at a block and typing:
+
+```javascript
+/js chessboard()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the chessboard() method.
+
+```javascript
+var d = new Drone(player);
+d.chessboard();
+```
+![chessboard example](img/chessboardex1.png)
+
+### Drone.cottage() method
+
+Creates a simple but cosy dwelling.
+
+#### Example
+
+At the in-game prompt you can create a cottage by looking at a block and typing:
+
+```javascript
+/js cottage()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the cottage() method.
+
+```javascript
+var d = new Drone(player);
+d.cottage();
+```
+![cottage example](img/cottageex1.png)
+
+### Drone.cottage_road() method
+
+Creates a tree-lined avenue with cottages on both sides.
+
+#### Parameters
+ 
+ * numberOfCottages: The number of cottages to build in total (optional: default 6)
+
+#### Example
+
+At the in-game prompt you can create a cottage road by looking at a block and typing:
+
+```javascript
+/js cottage_road()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the cottage_road() method.
+
+```javascript
+var d = new Drone(player);
+d.cottage_road();
+```
+![cottage_road example](img/cottageroadex1.png)
+
+### Drone.dancefloor() method
+Create an animated dance floor of colored tiles some of which emit light.
+The tiles change color every second creating a strobe-lit dance-floor effect.
+See it in action here [http://www.youtube.com/watch?v=UEooBt6NTFo][ytdance]
+
+### Parameters 
+
+ * width - how wide the dancefloor should be (optional: default 5)
+ * length - how long the dancefloor should be (optional: default 5)
+ * duration - the time duration for which the lights should change (optional: default 30 seconds)
+
+#### Example
+
+At the in-game prompt you can create a dancefloor by looking at a block and typing:
+
+```javascript
+/js dancefloor()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the dancefloor() method.
+
+```javascript
+var d = new Drone(player);
+d.dancefloor();
+```
+
+[ytdance]: http://www.youtube.com/watch?v=UEooBt6NTFo
+![dancefloor example](img/dancefloorex1.png)
+### Drone.fort() method
+
+Constructs a medieval fort.
+
+#### Parameters
+ 
+ * side - How many blocks whide and long the fort will be (default: 18 . Must be greater than 9)
+ * height - How tall the fort will be (default: 6 . Must be greater than 3)
+
+#### Example
+
+At the in-game prompt you can create a fort by looking at a block and typing:
+
+```javascript
+/js fort()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the fort() method.
+
+```javascript
+var d = new Drone(player);
+d.fort();
+```
+![fort example](img/fortex1.png)
+
+### Drone.hangtorch() method
+
+Adds a hanging torch to a wall. This method will try to hang a torch
+against a wall. It will traverse backwards until it finds a block
+adjacent to air and hang the torch. If it can't find a block next to
+air it will log a message in the server.
+
+#### Example
+
+At the in-game prompt you can create a hanging torch by looking at a
+block and typing:
+
+```javascript
+/js hangtorch()
+```
+
+Alternatively you can create a new Drone object from a Player or
+Location object and call the hangtorch() method.
+
+```javascript
+var d = new Drone(player);
+d.hangtorch();
+```
+
+### Drone.lcdclock() method.
+
+Constructs a large LCD Clock. The clock will display the current time of day.
+The clock can be stopped by calling the stopLCD() method of the Drone which created the clock.
+
+#### Parameters
+
+ * foregroundBlock (Optional - default is blocks.glowstone)
+ * backgroundBlock (Optional - default is blocks.wool.black)
+ * borderBlock (Optional - a border around the LCD display - default none)
+
+#### Example
+
+At the in-game prompt you can create a LCD clock by looking at a block and typing:
+
+```javascript
+/js var clock = lcdclock()
+/js clock.stopLCD()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the lcdclock() method.
+
+```javascript
+var d = new Drone(player);
+d.lcdclock();
+d.stopLCD();
+```
+![lcdclock example](img/lcdclockex1.png)
+### Drone.logojs() method
+
+Constructs a large Javascript Logo (black JS on Yellow background)
+See: https://raw.github.com/voodootikigod/logo.js/master/js.png
+
+#### Parameters
+
+ * foregroundBlock (Optional - default is blocks.wool.gray)
+ * backgroundBlock (Optional - default is blocks.gold)
+
+### Drone.maze() method
+
+Maze generation based on http://rosettacode.org/wiki/Maze_generation#JavaScript
+
+#### Parameters
+
+ * width (optional - default 10)
+ * length (optional - default 10)
+
+#### Example
+
+At the in-game prompt you can create a maze by looking at a block and typing:
+
+```javascript
+/js maze()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the maze() method.
+
+```javascript
+var d = new Drone(player);
+d.maze();
+```
+![maze example](img/mazeex1.png)
+
 ### Drone.rainbow() method
 
 Creates a Rainbow.
@@ -4108,9 +4357,18 @@ Creates a Rainbow.
  * radius (optional - default:18) - The radius of the rainbow
 
 #### Example
-    
-    var d = new Drone();
-    d.rainbow(30);
+
+At the in-game prompt you can create a rainbow by looking at a block and typing:
+```javascript
+/js rainbow()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the rainbow() method.
+
+```javascript    
+var d = new Drone(player);
+d.rainbow(30);
+```
 
 ![rainbow example](img/rainbowex1.png)
 
@@ -4141,6 +4399,30 @@ To construct a spiral staircase 5 floors high made of oak...
 
     spiral_stairs('oak', 5);
 
+### Drone.temple() method
+
+Constructs a mayan temple.
+
+#### Parameters
+ 
+ * side - How many blocks wide and long the temple will be (default: 20)
+
+#### Example
+
+At the in-game prompt you can create a temple by looking at a block and typing:
+
+```javascript
+/js temple()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the temple() method.
+
+```javascript
+var d = new Drone(player);
+d.temple();
+```
+![temple example](img/templeex1.png)
+
 ## Blocks Module
 
 You hate having to lookup [Data Values][dv] when you use ScriptCraft's

src/main/js/modules/drone/blocktype.js

@@ -15,7 +15,7 @@ Creates the text out of blocks. Useful for large-scale in-game signs.
 
 To create a 2-line high message using glowstone...
 
-    blocktype("Hello\nWorld",blocks.glowstone);
+    blocktype('Hello\nWorld', blocks.glowstone);
 
 ![blocktype example][imgbt1]
 

src/main/js/plugins/drone/contrib/castle.js

@@ -1,22 +1,46 @@
-var Drone = require('drone');
-//
-// a castle is just a big wide fort with 4 taller forts at each corner
-//
+'use strict';
+/*global require */
+var Drone = require('drone'),
+    blocks = require('blocks');
+/************************************************************************
+### Drone.castle() method
+
+Creates a Castle. A castle is just a big wide fort with 4 taller forts at each corner. 
+See also Drone.fort() method.
+
+#### Parameters
+ 
+ * side - How many blocks wide and long the castle will be (default: 24. Must be greater than 19)
+ * height - How tall the castle will be (default: 10. Must be geater than 7)
+
+#### Example
+
+At the in-game prompt you can create a castle by looking at a block and typing:
+
+```javascript
+/js castle()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the castle() method.
+
+```javascript
+var d = new Drone(player);
+d.castle();
+```
+![castle example](img/castleex1.png)
+
+***/
 function castle( side, height ) {
   // 
   // use sensible default parameter values
   // if no parameters are supplied
   //
-  if ( typeof side == "undefined" )
+  if ( typeof side == 'undefined' )
     side = 24;
-  if ( typeof height == "undefined" )
+  if ( typeof height == 'undefined' )
     height = 10;
   if ( height < 8 || side < 20 )
-    throw new java.lang.RuntimeException("Castles must be at least 20 wide X 8 tall");
-  //
-  // remember where the drone is so it can return 'home'
-  //
-  this.chkpt('castle');
+    throw new java.lang.RuntimeException('Castles must be at least 20 wide X 8 tall');
   // 
   // how big the towers at each corner will be...
   //
@@ -26,32 +50,31 @@ function castle( side, height ) {
   //
   // the main castle building will be front and right of the first tower
   //
-  this.fwd(towerSide/2).right(towerSide/2);
-  //
-  // the castle is really just a big fort with 4 smaller 'tower' forts at each corner
-  //
-  this.fort(side,height);
-  //
-  // move back to start position
-  //
-  this.move('castle');
+  this
+    .chkpt('castle')
+    .fwd( towerSide / 2 )
+    .right( towerSide / 2 )
+    .fort( side, height )
+    .move( 'castle' );
   //
   // now place 4 towers at each corner (each tower is another fort)
   //
   for ( var corner = 0; corner < 4; corner++ ) {
     // construct a 'tower' fort
-    this.fort(towerSide,towerHeight); 
-    this.chkpt('tower-' + corner);
-    // create 2 doorways from main castle rampart into each tower
-    this.fwd(towerSide-1).right(towerSide-3).up(towerHeight-5);
-    this.box(blocks.air, 1,2,1);
-    this.back(2).right(2);
-    this.box(blocks.air, 1,2,1);
-
-    this.move('tower-' + corner);
-    // move forward the length of the castle then turn right
-    this.fwd(side+towerSide-1).turn(); 
+    this
+      .fort( towerSide, towerHeight )
+      .chkpt('tower-' + corner)
+      .fwd( towerSide - 1 )
+      .right( towerSide - 3 )
+      .up( towerHeight - 5 ) // create 2 doorways from main castle rampart into each tower
+      .box( blocks.air, 1, 2, 1 )
+      .back( 2 )
+      .right( 2 )
+      .box( blocks.air, 1, 2, 1 )
+      .move( 'tower-' + corner)
+      .fwd( side + towerSide - 1) // move forward the length of the castle then turn right
+      .turn(); 
   }
-  return this.move('castle');
+  this.move('castle');
 }
 Drone.extend(castle);

src/main/js/plugins/drone/contrib/chessboard.js

@@ -1,21 +1,41 @@
-var Drone = require('drone');
-var blocks = require('blocks');
+'use strict';
+/*global require */
+var Drone = require('drone'),
+    blocks = require('blocks');
+/************************************************************************
+### Drone.chessboard() method
 
-/**
-* Creates a tile pattern of given block types and size
-*
-* Paramters:
-*  whiteBlock - blockId used for the traditional white portion of the chessboard
-*  blackBlock - blockId used for the traditional black portion of the chessboard
-*  width - width of the chessboard
-*  height - height of the chessboard
-*/
+Creates a tile pattern of given block types and size
+
+#### Parameters
+
+ * whiteBlock - (optional: default blocks.wool.white)
+ * blackBlock - (optional: default blocks.wool.black)
+ * width - width of the chessboard
+ * length - length of the chessboard
+
+#### Example
+
+At the in-game prompt you can create a chessboard by looking at a block and typing:
+
+```javascript
+/js chessboard()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the chessboard() method.
+
+```javascript
+var d = new Drone(player);
+d.chessboard();
+```
+![chessboard example](img/chessboardex1.png)
+
+***/
 Drone.extend('chessboard', function( whiteBlock, blackBlock, width, depth ) {
   var i, 
-    j,
-    block;
+      j,
+      block;
 
-  this.chkpt('chessboard-start');
 
   if ( typeof whiteBlock == 'undefined' ) {
     whiteBlock = blocks.wool.white;
@@ -29,10 +49,12 @@ Drone.extend('chessboard', function( whiteBlock, blackBlock, width, depth ) {
   if ( typeof depth == 'undefined' ) {
     depth = width;
   }
-  var wb = [ blackBlock, whiteBlock ];
+  var squares = [ blackBlock, whiteBlock ];
+
+  this.chkpt('chessboard-start');
   for ( i = 0; i < depth; i++ ) { 
-    this.boxa( wb, width, 1, 1).fwd();
-    wb = wb.reverse();
+    this.boxa( squares, width, 1, 1).fwd();
+    squares = squares.reverse();
   }
-  return this.move('chessboard-start');
+  this.move('chessboard-start');
 });

src/main/js/plugins/drone/contrib/cottage.js

@@ -1,15 +1,29 @@
-var Drone = require('drone');
-var blocks = require('blocks');
-//
-// usage: 
-// [1] to build a cottage at the player's current location or the cross-hairs location...
-//
-// /js cottage();
-// 
-// [2] to build a cottage using an existing drone...
-// 
-// /js drone.cottage();
-//
+'use strict';
+/*global require */
+var Drone = require('drone'),
+    blocks = require('blocks');
+/************************************************************************
+### Drone.cottage() method
+
+Creates a simple but cosy dwelling.
+
+#### Example
+
+At the in-game prompt you can create a cottage by looking at a block and typing:
+
+```javascript
+/js cottage()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the cottage() method.
+
+```javascript
+var d = new Drone(player);
+d.cottage();
+```
+![cottage example](img/cottageex1.png)
+
+***/
 function cottage( ) {
   this
     .chkpt('cottage')
@@ -48,6 +62,33 @@ function cottage( ) {
     .move('cottage')
   ;
 }
+/************************************************************************
+### Drone.cottage_road() method
+
+Creates a tree-lined avenue with cottages on both sides.
+
+#### Parameters
+ 
+ * numberOfCottages: The number of cottages to build in total (optional: default 6)
+
+#### Example
+
+At the in-game prompt you can create a cottage road by looking at a block and typing:
+
+```javascript
+/js cottage_road()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the cottage_road() method.
+
+```javascript
+var d = new Drone(player);
+d.cottage_road();
+```
+![cottage_road example](img/cottageroadex1.png)
+
+***/
+
 //
 // a more complex script that builds an tree-lined avenue with
 // cottages on both sides.
@@ -62,11 +103,15 @@ function cottage_road( numberCottages ) {
   //
   var cottagesPerSide = Math.floor(numberCottages/2);
   this
-    .chkpt('cottage_road') // make sure the drone's state is saved.
-    .box( blocks.double_slab.stone, 3, 1, cottagesPerSide * ( distanceBetweenTrees + 1 ) ) // build the road
+    // make sure the drone's state is saved.
+    .chkpt('cottage_road') 
+    // build the road
+    .box( blocks.double_slab.stone, 3, 1, cottagesPerSide * ( distanceBetweenTrees + 1 ) ) 
     .up()
-    .right() // now centered in middle of road
-    .chkpt('cr'); // will be returning to this position later
+    // now centered in middle of road
+    .right() 
+    // will be returning to this position later
+    .chkpt('cottage_road_cr'); 
 
   //
   // step 2 line the road with trees
@@ -81,7 +126,7 @@ function cottage_road( numberCottages ) {
       .fwd( distanceBetweenTrees + 1 ); // move forward.
   }
   this
-    .move('cr')
+    .move('cottage_road_cr')
     .back(6); // move back 1/2 the distance between trees
 
   // this function builds a path leading to a cottage.

src/main/js/plugins/drone/contrib/dancefloor.js

@@ -1,40 +1,74 @@
-var Drone = require('drone');
-var blocks = require('blocks');
+'use strict';
+/*global require, clearInterval, setInterval*/
+var Drone = require('drone'),
+    blocks = require('blocks'),
+    SECOND = 1000;
+/************************************************************************
+### Drone.dancefloor() method
+Create an animated dance floor of colored tiles some of which emit light.
+The tiles change color every second creating a strobe-lit dance-floor effect.
+See it in action here [http://www.youtube.com/watch?v=UEooBt6NTFo][ytdance]
+
+### Parameters 
+
+ * width - how wide the dancefloor should be (optional: default 5)
+ * length - how long the dancefloor should be (optional: default 5)
+ * duration - the time duration for which the lights should change (optional: default 30 seconds)
+
+#### Example
+
+At the in-game prompt you can create a dancefloor by looking at a block and typing:
+
+```javascript
+/js dancefloor()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the dancefloor() method.
+
+```javascript
+var d = new Drone(player);
+d.dancefloor();
+```
+
+[ytdance]: http://www.youtube.com/watch?v=UEooBt6NTFo
+![dancefloor example](img/dancefloorex1.png)
+***/
+ 
+
 //
-// Create a floor of colored tiles some of which emit light.
-// The tiles change color every second creating a strobe-lit dance-floor.
-// 
-// See it in action here => http://www.youtube.com/watch?v=UEooBt6NTFo
-//
-function dancefloor(width,length)
+function dancefloor(width, length, duration)
 {
-    if (typeof width == "undefined")
-        width = 5;
-    if (typeof length == "undefined")
-        length = width;
-    //
-    // create a separate Drone object to lay down disco tiles
-    //
-    var disco = new Drone(this.x, this.y, this.z, this.dir, this.world);
-    //
-    // under-floor lighting
-    //
-    disco.down().box(89,width,1,length).up();
-    var floorTiles = [35,35,'35:1','35:2','35:3','35:4','35:4','35:4','35:6',20,20];
-    //
-    // strobe gets called in a java thread - disco only lasts 30 seconds.
-    //
-    var discoTicks = 30;
-    var task = null;
-    var strobe = function() {
-        disco.rand(blocks.rainbow ,width,1,length);
-        if (!discoTicks--)
-            clearInterval(task);
-    };
-    var now = 0;
-    var everySecond = 20;
-    task = setInterval( strobe, 1000);
-    
-    return this;
+  if (typeof width == 'undefined')
+    width = 5;
+  if (typeof length == 'undefined')
+    length = width;
+  if (typeof duration === 'undefined'){
+    duration = 30;
+  }
+  //
+  // create a separate Drone object to lay down disco tiles
+  //
+  var disco = new Drone(this.x, this.y, this.z, this.dir, this.world);
+  //
+  // under-floor lighting
+  //
+  disco
+    .down()
+    .box( blocks.glowstone, width, 1, length)
+    .up();
+
+  //
+  // strobe gets called in a java thread - disco only lasts 30 seconds.
+  //
+  var task = null;
+  var strobe = function() {
+    disco.rand(blocks.rainbow, width, 1, length);
+    duration--;
+    if ( duration == 0 ){
+      // turn off the lights
+      clearInterval(task);
+    }
+  };
+  task = setInterval( strobe, 1 * SECOND);
 }
-Drone.extend(dancefloor);
+Drone.extend( dancefloor );

src/main/js/plugins/drone/contrib/fort.js

@@ -1,9 +1,34 @@
 'use strict';
-var Drone = require('drone');
-var blocks = require('blocks');
-//
-// constructs a medieval fort
-// 
+/*global require */
+var Drone = require('drone'),
+    blocks = require('blocks');
+/************************************************************************
+### Drone.fort() method
+
+Constructs a medieval fort.
+
+#### Parameters
+ 
+ * side - How many blocks whide and long the fort will be (default: 18 . Must be greater than 9)
+ * height - How tall the fort will be (default: 6 . Must be greater than 3)
+
+#### Example
+
+At the in-game prompt you can create a fort by looking at a block and typing:
+
+```javascript
+/js fort()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the fort() method.
+
+```javascript
+var d = new Drone(player);
+d.fort();
+```
+![fort example](img/fortex1.png)
+
+***/ 
 function fort( side, height ) {
   var turret,
     i,
@@ -65,9 +90,9 @@ function fort( side, height ) {
     .right();
 
   for ( i = 0; i < battlementWidth; i++ ) { 
-
+    var bside = side - ( 2 + (i * 2) );
     this
-      .box0(blocks.slab.oak, side - ( 2 + (i * 2) ), 1, side - ( 2 + ( i * 2) ))
+      .box0( blocks.slab.oak, bside, 1, bside)
       .fwd()
       .right();
   }
@@ -77,25 +102,25 @@ function fort( side, height ) {
   torch = blocks.torch + ':' + Drone.PLAYER_TORCH_FACING[this.dir];
   this
     .move('fort')
-    .right((side/2)-1)
+    .right( ( side / 2 ) - 1 )
     .door2() // double doors
     .back()
     .left()
     .up()
-    .box(torch) // left torch
-    .right(3)
-    .box(torch); // right torch
+    .box( torch ) // left torch
+    .right( 3 )
+    .box( torch ); // right torch
   //
   // add ladder up to battlements
   //
   this
     .move('fort')
-    .right((side/2)-3)
-    .fwd(1) // move inside fort
-    .turn(2)
-    .box(blocks.air, 1, height-1, 1)
-    .ladder(height-1)
-    .move('fort');
+    .right( ( side / 2 ) - 3 )
+    .fwd() // move inside fort
+    .turn( 2 )
+    .box( blocks.air, 1, height - 1, 1)
+    .ladder( height - 1 )
+    .move( 'fort' );
 }
 Drone.extend(fort);
 

src/main/js/plugins/drone/contrib/hangtorch.js

@@ -1,12 +1,37 @@
 'use strict';
 /*global require, __plugin, org*/
 var Drone = require('drone'),
-    bkMaterial = org.bukkit.Material,
     blocks = require('blocks');
+/************************************************************************
+### Drone.hangtorch() method
 
+Adds a hanging torch to a wall. This method will try to hang a torch
+against a wall. It will traverse backwards until it finds a block
+adjacent to air and hang the torch. If it can't find a block next to
+air it will log a message in the server.
+
+#### Example
+
+At the in-game prompt you can create a hanging torch by looking at a
+block and typing:
+
+```javascript
+/js hangtorch()
+```
+
+Alternatively you can create a new Drone object from a Player or
+Location object and call the hangtorch() method.
+
+```javascript
+var d = new Drone(player);
+d.hangtorch();
+```
+
+***/
 function canHang( block ) {
 
   if (__plugin.bukkit){
+    var bkMaterial = org.bukkit.Material;
     if ( block.type.equals(bkMaterial.AIR) ||
 	 block.type.equals(bkMaterial.VINE) ) {
       return true;

src/main/js/plugins/drone/contrib/lcd-clock.js

@@ -1,20 +1,39 @@
 'use strict';
 /*global require, setInterval, clearInterval, __plugin, exports*/
-/*
- Point at a block and issue the following ...
- /js var d = new Drone();
- /js var clock = new LCDClock(d);
- /js clock.start24(); 
- ... start the clock...
- /js clock.stop24();
- ... stops the clock...
- */
+/*************************************************************************
+### Drone.lcdclock() method.
+
+Constructs a large LCD Clock. The clock will display the current time of day.
+The clock can be stopped by calling the stopLCD() method of the Drone which created the clock.
+
+#### Parameters
+
+ * foregroundBlock (Optional - default is blocks.glowstone)
+ * backgroundBlock (Optional - default is blocks.wool.black)
+ * borderBlock (Optional - a border around the LCD display - default none)
+
+#### Example
+
+At the in-game prompt you can create a LCD clock by looking at a block and typing:
+
+```javascript
+/js var clock = lcdclock()
+/js clock.stopLCD()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the lcdclock() method.
+
+```javascript
+var d = new Drone(player);
+d.lcdclock();
+d.stopLCD();
+```
+![lcdclock example](img/lcdclockex1.png)
+***/
 var blocks = require('blocks'),
     utils = require('utils'),
     Drone = require('drone');
 
-Drone.extend(lcdclock);
-
 function lcdclock(fgColor, bgColor, border){
   var drone = this;
   var lastSecs = [0,0,0,0],
@@ -78,6 +97,9 @@ function lcdclock(fgColor, bgColor, border){
     update( timeOfDayInMins );
   }
   intervalId = setInterval(tick, 800);
-  console.log('lcdclock started background task:' + intervalId);
+  this.stopLCD = function(){
+    clearInterval(intervalId);
+  };
 }
 
+Drone.extend(lcdclock);

src/main/js/plugins/drone/contrib/logo.js

@@ -2,16 +2,18 @@
 /*global require*/
 var Drone = require('drone'),
     blocks = require('blocks');
+/************************************************************************
+### Drone.logojs() method
 
-//
-// Constructs the JS logo
-// https://raw.github.com/voodootikigod/logo.js/master/js.png
-//
-// fg
-//   the material that the letters JS will be made of
-// bg
-//   the material that the square will be made of
-//
+Constructs a large Javascript Logo (black JS on Yellow background)
+See: https://raw.github.com/voodootikigod/logo.js/master/js.png
+
+#### Parameters
+
+ * foregroundBlock (Optional - default is blocks.wool.gray)
+ * backgroundBlock (Optional - default is blocks.gold)
+
+***/
 function logojs(fg, bg) {
 
     // foreground defaults to gray wool

src/main/js/plugins/drone/contrib/mazegen.js

@@ -1,10 +1,45 @@
-// Maze generation based on http://rosettacode.org/wiki/Maze_generation#JavaScript
+'use strict';
+/*global require*/
+/************************************************************************
+### Drone.maze() method
+
+Maze generation based on http://rosettacode.org/wiki/Maze_generation#JavaScript
+
+#### Parameters
+
+ * width (optional - default 10)
+ * length (optional - default 10)
+
+#### Example
+
+At the in-game prompt you can create a maze by looking at a block and typing:
+
+```javascript
+/js maze()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the maze() method.
+
+```javascript
+var d = new Drone(player);
+d.maze();
+```
+![maze example](img/mazeex1.png)
+
+***/
+var Drone = require('drone'),
+    blocks = require('blocks');
 
-var Drone = require('drone');
 // User-facing code starts here
 // Example: Try /js maze(5,7)
-Drone.extend( function maze( size_x, size_y ) {
-  m = maze_make(size_x, size_y);
+Drone.extend( function maze( width, length ) {
+  if (typeof width === 'undefined'){
+    width = 10;
+  }
+  if (typeof length === 'undefined'){
+    length = 10;
+  }
+  var m = maze_make(width, length);
   if (m.x > 0 && m.y > 0) {
     maze_draw(maze_display(m), this);
   }
@@ -15,15 +50,18 @@ Drone.extend( function maze( size_x, size_y ) {
 function maze_make(x,y) {
   var n=x*y-1;
   if (n<0) {
-    echo("illegal maze dimensions");
+    console.log ("illegal maze dimensions");
     return ({x: 0, y: 0});
   }
-  var horiz=[]; for (var j= 0; j<x+1; j++) horiz[j]= [];
-  var verti=[]; for (var j= 0; j<y+1; j++) verti[j]= [];
+  var horiz=[]; 
+  var j;
+  for ( j = 0; j<x+1; j++) horiz[j]= [];
+  var verti=[]; 
+  for ( j = 0; j<y+1; j++) verti[j]= [];
   var here= [Math.floor(Math.random()*x), Math.floor(Math.random()*y)];
   var path= [here];
   var unvisited= [];
-  for (var j= 0; j<x+2; j++) {
+  for (j = 0; j<x+2; j++) {
     unvisited[j]= [];
     for (var k= 0; k<y+1; k++)
       unvisited[j].push(j>0 && j<x+1 && k>0 && (j != here[0]+1 || k != here[1]+1));
@@ -32,12 +70,12 @@ function maze_make(x,y) {
     var potential= [[here[0]+1, here[1]], [here[0],here[1]+1],
         [here[0]-1, here[1]], [here[0],here[1]-1]];
     var neighbors= [];
-    for (var j= 0; j < 4; j++)
+    for (j= 0; j < 4; j++)
       if (unvisited[potential[j][0]+1][potential[j][1]+1])
         neighbors.push(potential[j]);
     if (neighbors.length) {
       n= n-1;
-      next= neighbors[Math.floor(Math.random()*neighbors.length)];
+      var next= neighbors[Math.floor(Math.random()*neighbors.length)];
       unvisited[next[0]+1][next[1]+1]= false;
       if (next[0] == here[0])
         horiz[next[0]][(next[1]+here[1]-1)/2]= true;

src/main/js/plugins/drone/contrib/rainbow.js

@@ -13,9 +13,18 @@ Creates a Rainbow.
  * radius (optional - default:18) - The radius of the rainbow
 
 #### Example
-    
-    var d = new Drone();
-    d.rainbow(30);
+
+At the in-game prompt you can create a rainbow by looking at a block and typing:
+```javascript
+/js rainbow()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the rainbow() method.
+
+```javascript    
+var d = new Drone(player);
+d.rainbow(30);
+```
 
 ![rainbow example](img/rainbowex1.png)
 

src/main/js/plugins/drone/contrib/temple.js

@@ -1,8 +1,33 @@
+'use strict';
+/*global require*/
 var Drone = require('drone'),
     blocks = require('blocks');
-//
-// constructs a mayan temple
-// 
+/************************************************************************
+### Drone.temple() method
+
+Constructs a mayan temple.
+
+#### Parameters
+ 
+ * side - How many blocks wide and long the temple will be (default: 20)
+
+#### Example
+
+At the in-game prompt you can create a temple by looking at a block and typing:
+
+```javascript
+/js temple()
+```
+
+Alternatively you can create a new Drone object from a Player or Location object and call the temple() method.
+
+```javascript
+var d = new Drone(player);
+d.temple();
+```
+![temple example](img/templeex1.png)
+
+***/
 function temple( side ) {
   if ( !side ) {
     side = 20;