diff --git a/docs/api.md b/docs/api.md index 56af35e..1393752 100644 --- a/docs/api.md +++ b/docs/api.md @@ -241,6 +241,36 @@ Parameters Drone.cylinder0() method ======================== A version of cylinder that hollows out the middle. +Drone.arc() method +================== +The arc() method can be used to create 1 or more 90 degree arcs in the horizontal or vertical planes. +This method is called by cylinder() and cylinder0() and the sphere() and sphere0() methods. + +Parameters +---------- +arc() takes a single parameter - an object with the following named properties... + + * radius - The radius of the arc. + * blockType - The type of block to use - this is the block Id only (no meta). See [Data Values][dv]. + * meta - The metadata value. See [Data Values][dv]. + * orientation (default: 'horizontal') - the orientation of the arc - can be 'vertical' or 'horizontal'. + * stack (default: 1) - the height or length of the arc (depending on + the orientation - if orientation is horizontal then this parameter + refers to the height, if vertical then it refers to the length). + * strokeWidth (default: 1) - the width of the stroke (how many + blocks) - if drawing nested arcs it's usually a good idea to set + strokeWidth to at least 2 so that there are no gaps between each + arc. The arc method uses a [bresenham algorithm][bres] to plot + points along the circumference. + * fill - If true (or present) then the arc will be filled in. + * quadrants (default: + `{topleft:true,topright:true,bottomleft:true,bottomright:true}` - An + object with 4 properties indicating which of the 4 quadrants of a + circle to draw. If the quadrants property is absent then all 4 + quadrants are drawn. + +[bres]: http://en.wikipedia.org/wiki/Midpoint_circle_algorithm +[dv]: http://www.minecraftwiki.net/wiki/Data_values Drone.door() method =================== create a door - if a parameter is supplied an Iron door is created otherwise a wooden door is created. @@ -257,8 +287,8 @@ Parameters ---------- * doorType (optional - default wood) - If a parameter is provided then the door is Iron. -Drone.sign method -================= +Drone.sign() method +=================== Signs must use block 63 (stand-alone signs) or 68 (signs on walls) Parameters @@ -389,3 +419,61 @@ Drone Properties * z - The Drone's position along the north-south axis (z increases as you move south) * dir - The Drone's direction 0 is east, 1 is south , 2 is west and 3 is north. +Extending Drone +=============== +The Drone object can be easily extended - new buidling recipes/blue-prints can be added and can +become part of a Drone's chain using the *static* method `Drone.extend`. + +Drone.extend() static method +============================ +Use this method to add new methods (which also become chainable global functions) to the Drone object. + +Parameters +---------- + * name - The name of the new method e.g. 'pyramid' + * function - The method body. + +Example +------- + + // submitted by [edonaldson][edonaldson] + Drone.extend('pyramid', function(block,height){ + this.chkpt('pyramid'); + for (var i = height; i > 0; i -= 2) { + this.box(block, i, 1, i).up().right().fwd(); + } + return this.move('pyramid'); + }); + +Once the method is defined (it can be defined in a new pyramid.js file) it can be used like so... + + var d = new Drone(); + d.pyramid(blocks.brick.stone, 12); + +... or simply ... + + pyramid(blocks.brick.stone, 12); + +[edonaldson]: https://github.com/edonaldson + +Drone.blocktype() method +======================== +Creates the text out of blocks. Useful for large-scale in-game signs. + +Parameters +---------- + + * message - The message to create - (use `\n` for newlines) + * foregroundBlock (default: black wool) - The block to use for the foreground + * backgroundBlock (default: none) - The block to use for the background + +Example +------- +To create a 2-line high message using glowstone... + + blocktype("Hello\nWorld",blocks.glowstone); + +![blocktype example][imgbt1] + +[imgbt1]: img/blocktype1.png + diff --git a/docs/img/blocktype1.png b/docs/img/blocktype1.png new file mode 100644 index 0000000..f1c89ae Binary files /dev/null and b/docs/img/blocktype1.png differ diff --git a/src/main/javascript/drone/blocktype.js b/src/main/javascript/drone/blocktype.js index f931c4d..e0abd21 100644 --- a/src/main/javascript/drone/blocktype.js +++ b/src/main/javascript/drone/blocktype.js @@ -296,8 +296,31 @@ load(__folder + "drone.js"); } } } - // - // Creates the text out of blocks +/************************************************************************ +Drone.blocktype() method +======================== +Creates the text out of blocks. Useful for large-scale in-game signs. + +Parameters +---------- + + * message - The message to create - (use `\n` for newlines) + * foregroundBlock (default: black wool) - The block to use for the foreground + * backgroundBlock (default: none) - The block to use for the background + +Example +------- +To create a 2-line high message using glowstone... + + blocktype("Hello\nWorld",blocks.glowstone); + +![blocktype example][imgbt1] + +[imgbt1]: img/blocktype1.png + +***/ + + // // message // string with text to be displayed @@ -310,6 +333,9 @@ load(__folder + "drone.js"); this.chkpt('blocktext'); + if (typeof fg == "undefined") + fg = blocks.black; + var bmfg = this._getBlockIdAndMeta(fg); var bmbg = null; if (typeof bg != "undefined") diff --git a/src/main/javascript/drone/drone.js b/src/main/javascript/drone/drone.js index 977d8c6..1df85b6 100644 --- a/src/main/javascript/drone/drone.js +++ b/src/main/javascript/drone/drone.js @@ -277,6 +277,40 @@ A version of cylinder that hollows out the middle. ***/ Drone.prototype.cylinder = function(block,radius,height){}; Drone.prototype.cylinder0 = function(block,radius,height){}; +/************************************************************************ +Drone.arc() method +================== +The arc() method can be used to create 1 or more 90 degree arcs in the horizontal or vertical planes. +This method is called by cylinder() and cylinder0() and the sphere() and sphere0() methods. + +Parameters +---------- +arc() takes a single parameter - an object with the following named properties... + + * radius - The radius of the arc. + * blockType - The type of block to use - this is the block Id only (no meta). See [Data Values][dv]. + * meta - The metadata value. See [Data Values][dv]. + * orientation (default: 'horizontal') - the orientation of the arc - can be 'vertical' or 'horizontal'. + * stack (default: 1) - the height or length of the arc (depending on + the orientation - if orientation is horizontal then this parameter + refers to the height, if vertical then it refers to the length). + * strokeWidth (default: 1) - the width of the stroke (how many + blocks) - if drawing nested arcs it's usually a good idea to set + strokeWidth to at least 2 so that there are no gaps between each + arc. The arc method uses a [bresenham algorithm][bres] to plot + points along the circumference. + * fill - If true (or present) then the arc will be filled in. + * quadrants (default: + `{topleft:true,topright:true,bottomleft:true,bottomright:true}` - An + object with 4 properties indicating which of the 4 quadrants of a + circle to draw. If the quadrants property is absent then all 4 + quadrants are drawn. + +[bres]: http://en.wikipedia.org/wiki/Midpoint_circle_algorithm +[dv]: http://www.minecraftwiki.net/wiki/Data_values +***/ +Drone.prototype.arc = function(params) {}; + /************************************************************************ Drone.door() method =================== @@ -298,8 +332,8 @@ Parameters Drone.prototype.door = function(b){}; Drone.prototype.door2 = function(b){}; /************************************************************************ -Drone.sign method -================= +Drone.sign() method +=================== Signs must use block 63 (stand-alone signs) or 68 (signs on walls) Parameters @@ -449,6 +483,43 @@ Drone Properties * z - The Drone's position along the north-south axis (z increases as you move south) * dir - The Drone's direction 0 is east, 1 is south , 2 is west and 3 is north. +Extending Drone +=============== +The Drone object can be easily extended - new buidling recipes/blue-prints can be added and can +become part of a Drone's chain using the *static* method `Drone.extend`. + +Drone.extend() static method +============================ +Use this method to add new methods (which also become chainable global functions) to the Drone object. + +Parameters +---------- + * name - The name of the new method e.g. 'pyramid' + * function - The method body. + +Example +------- + + // submitted by [edonaldson][edonaldson] + Drone.extend('pyramid', function(block,height){ + this.chkpt('pyramid'); + for (var i = height; i > 0; i -= 2) { + this.box(block, i, 1, i).up().right().fwd(); + } + return this.move('pyramid'); + }); + +Once the method is defined (it can be defined in a new pyramid.js file) it can be used like so... + + var d = new Drone(); + d.pyramid(blocks.brick.stone, 12); + +... or simply ... + + pyramid(blocks.brick.stone, 12); + +[edonaldson]: https://github.com/edonaldson + ***/ // @@ -1365,11 +1436,12 @@ Drone Properties // var ops = ['up','down','left','right','fwd','back','turn', 'chkpt','move', - 'box','box0','boxa','prism','prism0','cylinder','cylinder0', + 'box','box0','boxa','prism','prism0','cylinder','cylinder0','arc', 'door','door2','sign','oak','spruce','birch','jungle', 'rand','garden', 'copy','paste' ]; + for (var i = 0;i < ops.length; i++){ global[ops[i]] = function(op){ return function(){