diff --git a/docs/API-Reference.md b/docs/API-Reference.md index ec7de2e..b815b92 100644 --- a/docs/API-Reference.md +++ b/docs/API-Reference.md @@ -115,26 +115,35 @@ provided. The `lib` directory is for internal use by ScriptCraft. Modules in this directory are not automatically loaded nor are they globally exported. -### Directories +### plugins sub-directories As of December 24 2013, the `scriptcraft/plugins` directory has the following sub-directories... * drone - Contains the drone module and drone extensions. Drone was the first scriptcraft module. * mini-games - Contains mini-games - * arrows - The arrows module - * signs - The signs module (includes example signs) - * chat - The chat plugin/module - * alias - The alias plugin/module + * arrows - The arrows module - Changes the behaviour of Arrows: Explosive, Fireworks, Teleportation etc. + * signs - The signs module (includes example signs) - create interactive signs. + * chat - The chat plugin/module + * alias - The alias plugin/module - for creating custom aliases for commonly used commands. * home - The home module - for setting homes and visiting other homes. -## Core Module: functions +## Global functions -ScripCraft provides some functions which can be used by all plugins/modules... +ScripCraft provides some global functions which can be used by all plugins/modules... - * echo (message) - Displays a message on the screen. +### echo function + +The `echo()` function displays a message on the in-game screen. The message is displayed to the `self` player (this is usually the player who issued the `/js` or `/jsp` command). + +### Example + + /js echo('Hello World') + + +* echo (message) - Displays a message on the screen. For example: `/js echo('Hello World')` will print Hello World on the in-game chat window. For programmers familiar with Javascript web programming, an `alert` function is also provided. - `alert` works exactly the same as `echo` e.g. `alert('Hello World')` + `alert` works exactly the same as `echo` e.g. `alert('Hello World')`. * require (modulename) - Will load modules. See [Node.js modules][njsmod] @@ -183,7 +192,7 @@ load() should only be used to load .json data. * filename - The name of the file to load. * warnOnFileNotFound (optional - default: false) - warn if the file was not found. -#### Return +#### Returns load() will return the result of the last statement evaluated in the file. @@ -283,34 +292,8 @@ plugin author) safely expose javascript functions for use by players. See chat/colors.js or alias/alias.js or homes/homes.js for examples of how to use the `command()` function. -### ready() function +## global variables -The `ready()` function provides a way for plugins to do additional -setup once all of the other plugins/modules have loaded. For example, -event listener registration can only be done after the -events/events.js module has loaded. A plugin author could load the -file explicilty like this... - - load(__folder + "../events/events.js"); - - // event listener registration goes here - -... or better still, just do event regristration using the `ready()` -handler knowing that by the time the `ready()` callback is invoked, -all of the scriptcraft modules have been loaded... - - ready(function(){ - // event listener registration goes here - // code that depends on other plugins/modules also goes here - }); - -The execution of the function object passed to the `ready()` function -is *deferred* until all of the plugins/modules have loaded. That way -you are guaranteed that when the function is invoked, all of the -plugins/modules have been loaded and evaluated and are ready to use. - -Core Module - Special Variables -=============================== There are a couple of special javascript variables available in ScriptCraft... * __folder - The current working directory - this variable is only to be used within the main body of a .js file. @@ -373,7 +356,7 @@ See [issue #69][issue69] for more information. [issue69]: https://github.com/walterhiggins/ScriptCraft/issues/69 -## Require - Node.js-style module loading in ScriptCraft +## require - Node.js-style module loading in ScriptCraft Node.js is a server-side javascript environment with an excellent module loading system based on CommonJS. Modules in Node.js are really @@ -415,19 +398,21 @@ and modules themeselves can use other modules. Modules have full control over what functions and properties they want to provide to others. -## Important +### Important Although ScriptCraft now supports Node.js style modules, it does not support node modules. Node.js and Rhino are two very different Javascript environments. ScriptCraft uses Rhino Javascript, not -Node.js. +Node.js. Standard Node.js modules such as `'fs'` are not available in ScriptCraft. Modules can be loaded using relative or absolute paths. Per the CommonJS module specification, the '.js' suffix is optional. [cjsmodules]: http://wiki.commonjs.org/wiki/Modules/1.1.1. -## When resolving module names to file paths, ScriptCraft uses the following rules... +### module name resolution + +When resolving module names to file paths, ScriptCraft uses the following rules... 1. if the module does not begin with './' or '/' then ... @@ -457,19 +442,19 @@ module specification, the '.js' suffix is optional. 3.2 if no package.json file exists then look for an index.js file in the directory -events Module -============= +## events Module + The Events module provides a thin wrapper around Bukkit's Event-handling API. Bukkit's Events API makes use of Java Annotations which are not available in Javascript, so this module provides a simple way to listen to minecraft events in javascript. -events.on() static method -========================= +### events.on() static method + This method is used to register event listeners. -Parameters ----------- +#### Parameters + * eventName - A string or java class. If a string is supplied it must be part of the Bukkit event class name. See [Bukkit API][buk] for @@ -493,40 +478,40 @@ Parameters "NORMAL", "MONITOR". For an explanation of what the different priorities mean refer to bukkit's [Event API Reference][buk2]. -Returns -------- +#### Returns + An org.bukkit.plugin.RegisteredListener object which can be used to unregister the listener. This same object is passed to the callback function each time the event is fired. -Example: ------- +#### Example: + The following code will print a message on screen every time a block is broken in the game - var events = require('./events/events'); - - events.on("block.BlockBreakEvent", function(listener, evt){ - echo (evt.player.name + " broke a block!"); + events.on('block.BlockBreakEvent', function(listener, evt){ + evt.player.sendMessage( evt.player.name + ' broke a block!'); }); To handle an event only once and unregister from further events... - var events = require('./events/events'); - - events.on("block.BlockBreakEvent", function(listener, evt){ - print (evt.player.name + " broke a block!"); + events.on('block.BlockBreakEvent', function(listener, evt){ + evt.player.sendMessage( evt.player.name + ' broke a block!'); evt.handlers.unregister(listener); }); To unregister a listener *outside* of the listener function... - var events = require('./events/events'); - - var myBlockBreakListener = events.on("block.BlockBreakEvent",function(l,e){ ... }); + var myBlockBreakListener = events.on('block.BlockBreakEvent',function(l,e){ ... }); ... var handlers = org.bukkit.event.block.BlockBreakEvent.getHandlerList(); handlers.unregister(myBlockBreakListener); +To listen for events using a full class name as the `eventName` parameter... + + events.on(org.bukkit.event.block.BlockBreakEvent, function(listener, evt){ + evt.player.sendMessage( evt.player.name + ' broke a block!'); + }); + [buk2]: http://wiki.bukkit.org/Event_API_Reference [buk]: http://jd.bukkit.org/dev/apidocs/index.html?org/bukkit/event/Event.html @@ -554,16 +539,15 @@ in-game). [lgr]: http://jd.bukkit.org/beta/apidocs/org/bukkit/plugin/PluginLogger.html [strfmt]: http://docs.oracle.com/javase/6/docs/api/java/lang/String.html#format(java.lang.String, java.lang.Object...) -http.request() function -==================== +## http.request() function + The http.request() function will fetch a web address asynchronously (on a separate thread)and pass the URL's response to a callback function which will be executed synchronously (on the main thread). In this way, http.request() can be used to fetch web content without blocking the main thread of execution. -Parameters ----------- +### Parameters * request: The request details either a plain URL e.g. "http://scriptcraft.js/sample.json" or an object with the following properties... @@ -575,8 +559,8 @@ Parameters - responseCode: The numeric response code from the server. If the server did not respond with 200 OK then the response parameter will be undefined. - response: A string (if the response is of type text) or object containing the HTTP response body. -Example -------- +### Example + The following example illustrates how to use http.request to make a request to a JSON web service and evaluate its response... var jsResponse; @@ -595,8 +579,8 @@ The following example illustrates how to use http.request to make a request to a var jsObj = eval("(" + responseBody + ")"); }); -Utilities Module -================ +## Utilities Module + Miscellaneous utility functions and classes to help with programming. * locationToString(Location) - returns a bukkit Location object in string form. @@ -610,8 +594,8 @@ Miscellaneous utility functions and classes to help with programming. * getMousePos(playerName) - returns the x,y,z of the current block being targeted by the named player or player or `self` if no paramter is provided. -foreach() function -======================== +### foreach() function + The utils.foreach() function is a utility function for iterating over an array of objects (or a java.util.Collection of objects) and processing each object in turn. Where utils.foreach() differs from other similar functions found in @@ -624,8 +608,7 @@ package for scheduling processing of arrays. [sched]: http://jd.bukkit.org/beta/apidocs/org/bukkit/scheduler/package-summary.html -Parameters ----------- +#### Parameters * array : The array to be processed - It can be a javascript array, a java array or java.util.Collection * callback : The function to be called to process each item in the @@ -654,11 +637,11 @@ subsequent items are processed later). If your code relies on the completion of the array processing, then provide an `onDone` parameter and put the code there. -Example -------- +#### Example + The following example illustrates how to use foreach for immediate processing of an array... - var utils = require('./utils/_utils'); + var utils = require('utils'); var players = ["moe", "larry", "curly"]; utils.foreach (players, function(item){ server.getPlayer(item).sendMessage("Hi " + item); @@ -678,7 +661,7 @@ without hogging CPU usage... // build a structure 200 wide x 200 tall x 200 long // (That's 8 Million Blocks - enough to tax any machine!) - var utils = require('./utils/_utils'); + var utils = require('utils'); var a = []; a.length = 200; @@ -695,8 +678,8 @@ without hogging CPU usage... }; utils.foreach (a, processItem, null, 10, onDone); -utils.nicely() function -======================= +### utils.nicely() function + The utils.nicely() function is for performing processing using the [org.bukkit.scheduler][sched] package/API. utils.nicely() lets you process with a specified delay between the completion of each `next()` @@ -704,8 +687,7 @@ function and the start of the next `next()` function. `utils.nicely()` is a recursive function - that is - it calls itself (schedules itself actually) repeatedly until `hasNext` returns false. -Parameters ----------- +#### Parameters * next : A function which will be called if processing is to be done. * hasNext : A function which is called to determine if the `next` @@ -715,29 +697,27 @@ Parameters * onDone : A function which is to be called when all processing is complete (hasNext returned false). * delay : The delay (in server ticks - 20 per second) between each call. -Example -------- +#### Example + See the source code to utils.foreach for an example of how utils.nicely is used. -utils.at() function -=================== +### utils.at() function + The utils.at() function will perform a given task at a given time every (minecraft) day. -Parameters ----------- +#### Parameters * time24hr : The time in 24hr form - e.g. 9:30 in the morning is "09:30" while 9:30 pm is "21:30", midnight is "00:00" and midday is "12:00" * callback : A javascript function which will be invoked at the given time. * world : (optional) Each world has its own clock. If no world is specified, the server's first world is used. -Example -------- +#### Example To warn players when night is approaching... - var utils = require('./utils/_utils'); + var utils = require('utils'); utils.at( "19:00", function() { @@ -747,6 +727,25 @@ To warn players when night is approaching... }, self.world); +### utils.find() function + +The utils.find() function will return a list of all files starting at +a given directory and recursiving trawling all sub-directories. + +#### Parameters + + * dir : The starting path. Must be a string. + * filter : (optional) A [FilenameFilter][fnfltr] object to return only files matching a given pattern. + +[fnfltr]: http://docs.oracle.com/javase/6/docs/api/java/io/FilenameFilter.html + +#### Example + + var utils = require('utils'); + var jsFiles = utils.find('./', function(dir,name){ + return name.match(/\.js$/); + }); + String class extensions ----------------------- The following chat-formatting methods are added to the javascript String class.. @@ -788,28 +787,34 @@ Example

Hello World

-Blocks Module -============= -You hate having to lookup [Data Values][dv] when you use ScriptCraft's Drone() functions. So do I. -So I created this blocks object which is a helper object for use in construction. +## Blocks Module -Examples --------- +You hate having to lookup [Data Values][dv] when you use ScriptCraft's +Drone() functions. So do I. So I created this blocks object which is +a helper object for use in construction. + +### Examples box( blocks.oak ); // creates a single oak wood block box( blocks.sand, 3, 2, 1 ); // creates a block of sand 3 wide x 2 high x 1 long box( blocks.wool.green, 2 ); // creates a block of green wool 2 blocks wide -Color aliased properties that were a direct descendant of the blocks object are no longer used to avoid confusion with carpet and stained clay blocks. In addition, there's a convenience array `blocks.rainbow` which is an array of the 7 colors of the rainbow (or closest approximations). +Color aliased properties that were a direct descendant of the blocks +object are no longer used to avoid confusion with carpet and stained +clay blocks. In addition, there's a convenience array `blocks.rainbow` +which is an array of the 7 colors of the rainbow (or closest +approximations). + +The blocks module is globally exported by the Drone module. + +## Fireworks Module -Fireworks Module -================ The fireworks module makes it easy to create fireworks using ScriptCraft. The module has a single function `firework` which takes a `org.bukkit.Location` as its 1 and only parameter. -Examples --------- +### Examples + The module also extends the `Drone` object adding a `firework` method so that fireworks can be created as a part of a Drone chain. For Example.... @@ -1533,19 +1538,18 @@ Another example: This statement creates a row of trees 2 by 3 ... ![times example 1](img/times-trees.png) -Drone.blocktype() method -======================== +## Drone.blocktype() method + Creates the text out of blocks. Useful for large-scale in-game signs. -Parameters ----------- +### 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 -------- +### Example + To create a 2-line high message using glowstone... blocktype("Hello\nWorld",blocks.glowstone); @@ -1554,18 +1558,17 @@ To create a 2-line high message using glowstone... [imgbt1]: img/blocktype1.png -Drone.sphere() method -===================== +## Drone.sphere() method + Creates a sphere. -Parameters ----------- +### Parameters * block - The block the sphere will be made of. * radius - The radius of the sphere. -Example -------- +### Example + To create a sphere of Iron with a radius of 10 blocks... sphere( blocks.iron, 10); @@ -1575,18 +1578,17 @@ To create a sphere of Iron with a radius of 10 blocks... Spheres are time-consuming to make. You *can* make large spheres (250 radius) but expect the server to be very busy for a couple of minutes while doing so. -Drone.sphere0() method -====================== +## Drone.sphere0() method + Creates an empty sphere. -Parameters ----------- +### Parameters * block - The block the sphere will be made of. * radius - The radius of the sphere. -Example -------- +### Example + To create a sphere of Iron with a radius of 10 blocks... sphere0( blocks.iron, 10); @@ -1594,67 +1596,62 @@ To create a sphere of Iron with a radius of 10 blocks... Spheres are time-consuming to make. You *can* make large spheres (250 radius) but expect the server to be very busy for a couple of minutes while doing so. -Drone.hemisphere() method -========================= +## Drone.hemisphere() method + Creates a hemisphere. Hemispheres can be either north or south. -Parameters ----------- +### Parameters * block - the block the hemisphere will be made of. * radius - the radius of the hemisphere * northSouth - whether the hemisphere is 'north' or 'south' -Example -------- +### Example + To create a wood 'north' hemisphere with a radius of 7 blocks... hemisphere(blocks.oak, 7, 'north'); ![hemisphere example](img/hemisphereex1.png) -Drone.hemisphere0() method -========================= +## Drone.hemisphere0() method + Creates a hollow hemisphere. Hemispheres can be either north or south. -Parameters ----------- +### Parameters * block - the block the hemisphere will be made of. * radius - the radius of the hemisphere * northSouth - whether the hemisphere is 'north' or 'south' -Example -------- +### Example + To create a glass 'north' hemisphere with a radius of 20 blocks... hemisphere0(blocks.glass, 20, 'north'); ![hemisphere example](img/hemisphereex2.png) -Drone.rainbow() method -====================== +## Drone.rainbow() method + Creates a Rainbow. -Parameters ----------- +### Parameters * radius (optional - default:18) - The radius of the rainbow -Example -------- +### Example var d = new Drone(); d.rainbow(30); ![rainbow example](img/rainbowex1.png) -Drone.spiral_stairs() method -============================ +## Drone.spiral_stairs() method + Constructs a spiral staircase with slabs at each corner. -Parameters ----------- +### Parameters * stairBlock - The block to use for stairs, should be one of the following... - 'oak' @@ -1671,8 +1668,8 @@ Parameters ![Spiral Staircase](img/spiralstair1.png) -Example -------- +### Example + To construct a spiral staircase 5 floors high made of oak... spiral_stairs('oak', 5); @@ -1751,8 +1748,8 @@ Aliases can be used at the in-game prompt by players or in the server console. Aliases will not be able to avail of command autocompletion (pressing the TAB key will have no effect). -Classroom Module -================ +## Classroom Module + The `classroom` object contains a couple of utility functions for use in a classroom setting. The goal of these functions is to make it easier for tutors to facilitate ScriptCraft for use by students in a @@ -1767,19 +1764,18 @@ The goal of this module is not so much to enforce restrictions (security or otherwise) but to make it easier for tutors to setup a shared server so students can learn Javascript. -classroom.allowScripting() function -=================================== +### classroom.allowScripting() function + Allow or disallow anyone who connects to the server (or is already connected) to use ScriptCraft. This function is preferable to granting 'ops' privileges to every student in a Minecraft classroom environment. -Parameters ----------- +#### Parameters * canScript : true or false -Example -------- +#### Example + To allow all players (and any players who connect to the server) to use the `js` and `jsp` commands... diff --git a/src/main/javascript/lib/events.js b/src/main/javascript/lib/events.js index ea292e3..fdb4357 100644 --- a/src/main/javascript/lib/events.js +++ b/src/main/javascript/lib/events.js @@ -1,17 +1,17 @@ /************************************************************************ -events Module -============= +## events Module + The Events module provides a thin wrapper around Bukkit's Event-handling API. Bukkit's Events API makes use of Java Annotations which are not available in Javascript, so this module provides a simple way to listen to minecraft events in javascript. -events.on() static method -========================= +### events.on() static method + This method is used to register event listeners. -Parameters ----------- +#### Parameters + * eventName - A string or java class. If a string is supplied it must be part of the Bukkit event class name. See [Bukkit API][buk] for @@ -35,54 +35,45 @@ Parameters "NORMAL", "MONITOR". For an explanation of what the different priorities mean refer to bukkit's [Event API Reference][buk2]. -Returns -------- +#### Returns + An org.bukkit.plugin.RegisteredListener object which can be used to unregister the listener. This same object is passed to the callback function each time the event is fired. -Example: ------- +#### Example: + The following code will print a message on screen every time a block is broken in the game - var events = require('./events/events'); - - events.on("block.BlockBreakEvent", function(listener, evt){ - echo (evt.player.name + " broke a block!"); + events.on('block.BlockBreakEvent', function(listener, evt){ + evt.player.sendMessage( evt.player.name + ' broke a block!'); }); To handle an event only once and unregister from further events... - var events = require('./events/events'); - - events.on("block.BlockBreakEvent", function(listener, evt){ - print (evt.player.name + " broke a block!"); + events.on('block.BlockBreakEvent', function(listener, evt){ + evt.player.sendMessage( evt.player.name + ' broke a block!'); evt.handlers.unregister(listener); }); To unregister a listener *outside* of the listener function... - var events = require('./events/events'); - - var myBlockBreakListener = events.on("block.BlockBreakEvent",function(l,e){ ... }); + var myBlockBreakListener = events.on('block.BlockBreakEvent',function(l,e){ ... }); ... var handlers = org.bukkit.event.block.BlockBreakEvent.getHandlerList(); handlers.unregister(myBlockBreakListener); +To listen for events using a full class name as the `eventName` parameter... + + events.on(org.bukkit.event.block.BlockBreakEvent, function(listener, evt){ + evt.player.sendMessage( evt.player.name + ' broke a block!'); + }); + [buk2]: http://wiki.bukkit.org/Event_API_Reference [buk]: http://jd.bukkit.org/dev/apidocs/index.html?org/bukkit/event/Event.html ***/ -// -// handle events in Minecraft -// -------------------------- -// eventType can be a string (assumed to be a sub package of org.bukkit.event - e.g. -// if the string "block.BlockBreakEvent" is supplied then it's converted to the -// org.bukkit.event.block.BlockBreakEvent class . For custom event classes, just -// supply the custom event class e.g. -// events.on(net.yourdomain.events.YourCustomEvent,function(l,e){ ... }); -// var bkEvent = org.bukkit.event; var bkEvtExecutor = org.bukkit.plugin.EventExecutor; var bkRegListener = org.bukkit.plugin.RegisteredListener; diff --git a/src/main/javascript/lib/plugin.js b/src/main/javascript/lib/plugin.js index 331b88a..77e4086 100644 --- a/src/main/javascript/lib/plugin.js +++ b/src/main/javascript/lib/plugin.js @@ -139,32 +139,6 @@ exports.autoload = function(dir) { } } }; - /* - sort so that .js files with same name as parent directory appear before - other files in the same directory - */ - var sortByModule = function(a,b){ - a = _canonize(a); - b = _canonize(b); - var aparts = (""+a).split(/\//); - var bparts = (""+b).split(/\//); - //var adir = aparts[aparts.length-2]; - var adir = aparts.slice(0,aparts.length-1).join("/"); - var afile = aparts[aparts.length-1]; - //var bdir = bparts[bparts.length-2]; - var bdir = bparts.slice(0,bparts.length-1).join("/"); - var bfile = bparts[bparts.length-1]; - - if(adirbdir) return 1; - - afile = afile.match(/[a-zA-Z0-9\-_]+/)[0]; - - if (adir.match(new RegExp(afile + "$"))) - return -1; - else - return 1; - }; /* Reload all of the .js files in the given directory */ @@ -174,18 +148,6 @@ exports.autoload = function(dir) { var sourceFiles = []; _listSourceFiles(sourceFiles,pluginDir); - //sourceFiles.sort(sortByModule); - - // - // script files whose name begins with _ (underscore) - // will not be loaded automatically at startup. - // These files are assumed to be dependencies/private to plugins - // - // E.g. If you have a plugin called myMiniGame.js in the myMiniGame directory - // and which in addition to myMiniGame.js also includes _myMiniGame_currency.js _myMiniGame_events.js etc. - // then it's assumed that _myMiniGame_currency.js and _myMiniGame_events.js will be loaded - // as dependencies by myMiniGame.js and do not need to be loaded via js reload - // var len = sourceFiles.length; if (config.verbose) logger.info(len + " scriptcraft plugins found."); diff --git a/src/main/javascript/lib/require.js b/src/main/javascript/lib/require.js index 74648b4..e6e5847 100644 --- a/src/main/javascript/lib/require.js +++ b/src/main/javascript/lib/require.js @@ -1,5 +1,5 @@ /************************************************************************* -## Require - Node.js-style module loading in ScriptCraft +## require - Node.js-style module loading in ScriptCraft Node.js is a server-side javascript environment with an excellent module loading system based on CommonJS. Modules in Node.js are really @@ -41,12 +41,12 @@ and modules themeselves can use other modules. Modules have full control over what functions and properties they want to provide to others. -## Important +### Important Although ScriptCraft now supports Node.js style modules, it does not support node modules. Node.js and Rhino are two very different Javascript environments. ScriptCraft uses Rhino Javascript, not -Node.js. +Node.js. Standard Node.js modules such as `'fs'` are not available in ScriptCraft. Modules can be loaded using relative or absolute paths. Per the CommonJS module specification, the '.js' suffix is optional. @@ -100,7 +100,9 @@ module specification, the '.js' suffix is optional. var resolveModuleToFile = function(moduleName, parentDir) { /********************************************************************** -## When resolving module names to file paths, ScriptCraft uses the following rules... +### module name resolution + +When resolving module names to file paths, ScriptCraft uses the following rules... 1. if the module does not begin with './' or '/' then ... diff --git a/src/main/javascript/lib/scriptcraft.js b/src/main/javascript/lib/scriptcraft.js index 4b1ee83..7a08ef5 100644 --- a/src/main/javascript/lib/scriptcraft.js +++ b/src/main/javascript/lib/scriptcraft.js @@ -1,3 +1,4 @@ +var global = this; /************************************************************************ # ScriptCraft API Reference @@ -116,26 +117,35 @@ provided. The `lib` directory is for internal use by ScriptCraft. Modules in this directory are not automatically loaded nor are they globally exported. -### Directories +### plugins sub-directories As of December 24 2013, the `scriptcraft/plugins` directory has the following sub-directories... * drone - Contains the drone module and drone extensions. Drone was the first scriptcraft module. * mini-games - Contains mini-games - * arrows - The arrows module - * signs - The signs module (includes example signs) - * chat - The chat plugin/module - * alias - The alias plugin/module + * arrows - The arrows module - Changes the behaviour of Arrows: Explosive, Fireworks, Teleportation etc. + * signs - The signs module (includes example signs) - create interactive signs. + * chat - The chat plugin/module + * alias - The alias plugin/module - for creating custom aliases for commonly used commands. * home - The home module - for setting homes and visiting other homes. -## Core Module: functions +## Global functions -ScripCraft provides some functions which can be used by all plugins/modules... +ScripCraft provides some global functions which can be used by all plugins/modules... - * echo (message) - Displays a message on the screen. +### echo function + +The `echo()` function displays a message on the in-game screen. The message is displayed to the `self` player (this is usually the player who issued the `/js` or `/jsp` command). + +### Example + + /js echo('Hello World') + + +* echo (message) - Displays a message on the screen. For example: `/js echo('Hello World')` will print Hello World on the in-game chat window. For programmers familiar with Javascript web programming, an `alert` function is also provided. - `alert` works exactly the same as `echo` e.g. `alert('Hello World')` + `alert` works exactly the same as `echo` e.g. `alert('Hello World')`. * require (modulename) - Will load modules. See [Node.js modules][njsmod] @@ -184,7 +194,7 @@ load() should only be used to load .json data. * filename - The name of the file to load. * warnOnFileNotFound (optional - default: false) - warn if the file was not found. -#### Return +#### Returns load() will return the result of the last statement evaluated in the file. @@ -284,40 +294,13 @@ plugin author) safely expose javascript functions for use by players. See chat/colors.js or alias/alias.js or homes/homes.js for examples of how to use the `command()` function. -### ready() function - -The `ready()` function provides a way for plugins to do additional -setup once all of the other plugins/modules have loaded. For example, -event listener registration can only be done after the -events/events.js module has loaded. A plugin author could load the -file explicilty like this... - - load(__folder + "../events/events.js"); - - // event listener registration goes here - -... or better still, just do event regristration using the `ready()` -handler knowing that by the time the `ready()` callback is invoked, -all of the scriptcraft modules have been loaded... - - ready(function(){ - // event listener registration goes here - // code that depends on other plugins/modules also goes here - }); - -The execution of the function object passed to the `ready()` function -is *deferred* until all of the plugins/modules have loaded. That way -you are guaranteed that when the function is invoked, all of the -plugins/modules have been loaded and evaluated and are ready to use. - ***/ -var global = this; /************************************************************************* -Core Module - Special Variables -=============================== +## global variables + There are a couple of special javascript variables available in ScriptCraft... * __folder - The current working directory - this variable is only to be used within the main body of a .js file. @@ -545,13 +528,7 @@ See [issue #69][issue69] for more information. */ var modulePaths = [jsPluginsRootDirName + '/lib/', jsPluginsRootDirName + '/modules/']; - global.require = fnRequire(__plugin.logger, - __engine, - config.verbose, - jsPluginsRootDirName, - modulePaths); - - + global.require = fnRequire(__plugin.logger, __engine, config.verbose, jsPluginsRootDirName, modulePaths); var plugins = require('plugin'); global._onTabComplete = require('tabcomplete'); @@ -573,8 +550,6 @@ See [issue #69][issue69] for more information. global.events = events; plugins.autoload(jsPluginsRootDir); - - }()); diff --git a/src/main/javascript/modules/blocks.js b/src/main/javascript/modules/blocks.js index 19e0c0c..019a6bf 100644 --- a/src/main/javascript/modules/blocks.js +++ b/src/main/javascript/modules/blocks.js @@ -1,17 +1,23 @@ /************************************************************************ -Blocks Module -============= -You hate having to lookup [Data Values][dv] when you use ScriptCraft's Drone() functions. So do I. -So I created this blocks object which is a helper object for use in construction. +## Blocks Module -Examples --------- +You hate having to lookup [Data Values][dv] when you use ScriptCraft's +Drone() functions. So do I. So I created this blocks object which is +a helper object for use in construction. + +### Examples box( blocks.oak ); // creates a single oak wood block box( blocks.sand, 3, 2, 1 ); // creates a block of sand 3 wide x 2 high x 1 long box( blocks.wool.green, 2 ); // creates a block of green wool 2 blocks wide -Color aliased properties that were a direct descendant of the blocks object are no longer used to avoid confusion with carpet and stained clay blocks. In addition, there's a convenience array `blocks.rainbow` which is an array of the 7 colors of the rainbow (or closest approximations). +Color aliased properties that were a direct descendant of the blocks +object are no longer used to avoid confusion with carpet and stained +clay blocks. In addition, there's a convenience array `blocks.rainbow` +which is an array of the 7 colors of the rainbow (or closest +approximations). + +The blocks module is globally exported by the Drone module. ***/ var blocks = { diff --git a/src/main/javascript/modules/fireworks/fireworks.js b/src/main/javascript/modules/fireworks/fireworks.js index 3703649..e3e160a 100644 --- a/src/main/javascript/modules/fireworks/fireworks.js +++ b/src/main/javascript/modules/fireworks/fireworks.js @@ -1,12 +1,12 @@ /************************************************************************ -Fireworks Module -================ +## Fireworks Module + The fireworks module makes it easy to create fireworks using ScriptCraft. The module has a single function `firework` which takes a `org.bukkit.Location` as its 1 and only parameter. -Examples --------- +### Examples + The module also extends the `Drone` object adding a `firework` method so that fireworks can be created as a part of a Drone chain. For Example.... diff --git a/src/main/javascript/modules/http/request.js b/src/main/javascript/modules/http/request.js index eb47677..9be0b36 100644 --- a/src/main/javascript/modules/http/request.js +++ b/src/main/javascript/modules/http/request.js @@ -1,14 +1,13 @@ /************************************************************************* -http.request() function -==================== +## http.request() function + The http.request() function will fetch a web address asynchronously (on a separate thread)and pass the URL's response to a callback function which will be executed synchronously (on the main thread). In this way, http.request() can be used to fetch web content without blocking the main thread of execution. -Parameters ----------- +### Parameters * request: The request details either a plain URL e.g. "http://scriptcraft.js/sample.json" or an object with the following properties... @@ -20,8 +19,8 @@ Parameters - responseCode: The numeric response code from the server. If the server did not respond with 200 OK then the response parameter will be undefined. - response: A string (if the response is of type text) or object containing the HTTP response body. -Example -------- +### Example + The following example illustrates how to use http.request to make a request to a JSON web service and evaluate its response... var jsResponse; diff --git a/src/main/javascript/modules/utils/utils.js b/src/main/javascript/modules/utils/utils.js index 8ef848c..bc8362b 100644 --- a/src/main/javascript/modules/utils/utils.js +++ b/src/main/javascript/modules/utils/utils.js @@ -1,6 +1,6 @@ /************************************************************************ -Utilities Module -================ +## Utilities Module + Miscellaneous utility functions and classes to help with programming. * locationToString(Location) - returns a bukkit Location object in string form. @@ -56,8 +56,8 @@ exports.getMousePos = function (player) { return targetedBlock.location; }; /************************************************************************ -foreach() function -======================== +### foreach() function + The utils.foreach() function is a utility function for iterating over an array of objects (or a java.util.Collection of objects) and processing each object in turn. Where utils.foreach() differs from other similar functions found in @@ -70,8 +70,7 @@ package for scheduling processing of arrays. [sched]: http://jd.bukkit.org/beta/apidocs/org/bukkit/scheduler/package-summary.html -Parameters ----------- +#### Parameters * array : The array to be processed - It can be a javascript array, a java array or java.util.Collection * callback : The function to be called to process each item in the @@ -100,11 +99,11 @@ subsequent items are processed later). If your code relies on the completion of the array processing, then provide an `onDone` parameter and put the code there. -Example -------- +#### Example + The following example illustrates how to use foreach for immediate processing of an array... - var utils = require('./utils/_utils'); + var utils = require('utils'); var players = ["moe", "larry", "curly"]; utils.foreach (players, function(item){ server.getPlayer(item).sendMessage("Hi " + item); @@ -124,7 +123,7 @@ without hogging CPU usage... // build a structure 200 wide x 200 tall x 200 long // (That's 8 Million Blocks - enough to tax any machine!) - var utils = require('./utils/_utils'); + var utils = require('utils'); var a = []; a.length = 200; @@ -159,8 +158,8 @@ var _foreach = function(array, callback, object, delay, onCompletion) { }; exports.foreach = _foreach; /************************************************************************ -utils.nicely() function -======================= +### utils.nicely() function + The utils.nicely() function is for performing processing using the [org.bukkit.scheduler][sched] package/API. utils.nicely() lets you process with a specified delay between the completion of each `next()` @@ -168,8 +167,7 @@ function and the start of the next `next()` function. `utils.nicely()` is a recursive function - that is - it calls itself (schedules itself actually) repeatedly until `hasNext` returns false. -Parameters ----------- +#### Parameters * next : A function which will be called if processing is to be done. * hasNext : A function which is called to determine if the `next` @@ -179,8 +177,8 @@ Parameters * onDone : A function which is to be called when all processing is complete (hasNext returned false). * delay : The delay (in server ticks - 20 per second) between each call. -Example -------- +#### Example + See the source code to utils.foreach for an example of how utils.nicely is used. ***/ @@ -196,25 +194,23 @@ exports.nicely = function(next, hasNext, onDone, delay){ } }; /************************************************************************ -utils.at() function -=================== +### utils.at() function + The utils.at() function will perform a given task at a given time every (minecraft) day. -Parameters ----------- +#### Parameters * time24hr : The time in 24hr form - e.g. 9:30 in the morning is "09:30" while 9:30 pm is "21:30", midnight is "00:00" and midday is "12:00" * callback : A javascript function which will be invoked at the given time. * world : (optional) Each world has its own clock. If no world is specified, the server's first world is used. -Example -------- +#### Example To warn players when night is approaching... - var utils = require('./utils/_utils'); + var utils = require('utils'); utils.at( "19:00", function() { @@ -246,6 +242,27 @@ exports.at = function(time24hr, callback, world) { },forever, null, 100); }; +/************************************************************************ +### utils.find() function + +The utils.find() function will return a list of all files starting at +a given directory and recursiving trawling all sub-directories. + +#### Parameters + + * dir : The starting path. Must be a string. + * filter : (optional) A [FilenameFilter][fnfltr] object to return only files matching a given pattern. + +[fnfltr]: http://docs.oracle.com/javase/6/docs/api/java/io/FilenameFilter.html + +#### Example + + var utils = require('utils'); + var jsFiles = utils.find('./', function(dir,name){ + return name.match(/\.js$/); + }); + +***/ exports.find = function( dir , filter){ var result = []; var recurse = function(dir, store){ diff --git a/src/main/javascript/plugins/classroom/classroom.js b/src/main/javascript/plugins/classroom/classroom.js index 13f6d1e..a1f07fe 100644 --- a/src/main/javascript/plugins/classroom/classroom.js +++ b/src/main/javascript/plugins/classroom/classroom.js @@ -1,8 +1,8 @@ var utils = require('utils'); /************************************************************************ -Classroom Module -================ +## Classroom Module + The `classroom` object contains a couple of utility functions for use in a classroom setting. The goal of these functions is to make it easier for tutors to facilitate ScriptCraft for use by students in a @@ -17,19 +17,18 @@ The goal of this module is not so much to enforce restrictions (security or otherwise) but to make it easier for tutors to setup a shared server so students can learn Javascript. -classroom.allowScripting() function -=================================== +### classroom.allowScripting() function + Allow or disallow anyone who connects to the server (or is already connected) to use ScriptCraft. This function is preferable to granting 'ops' privileges to every student in a Minecraft classroom environment. -Parameters ----------- +#### Parameters * canScript : true or false -Example -------- +#### Example + To allow all players (and any players who connect to the server) to use the `js` and `jsp` commands... @@ -77,5 +76,5 @@ events.on('player.PlayerLoginEvent', function(listener, event) { if (_store.enableScripting){ player.addAttachment(__plugin, "scriptcraft.*", true); } -}, "HIGHEST"); +}, 'HIGHEST'); diff --git a/src/main/javascript/plugins/drone/blocktype.js b/src/main/javascript/plugins/drone/blocktype.js index 7deced8..f142e34 100644 --- a/src/main/javascript/plugins/drone/blocktype.js +++ b/src/main/javascript/plugins/drone/blocktype.js @@ -2,19 +2,18 @@ var Drone = require('./drone').Drone; var blocks = require('blocks'); /************************************************************************ -Drone.blocktype() method -======================== +## Drone.blocktype() method + Creates the text out of blocks. Useful for large-scale in-game signs. -Parameters ----------- +### 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 -------- +### Example + To create a 2-line high message using glowstone... blocktype("Hello\nWorld",blocks.glowstone); diff --git a/src/main/javascript/plugins/drone/contrib/rainbow.js b/src/main/javascript/plugins/drone/contrib/rainbow.js index f675b5f..cf8cad3 100644 --- a/src/main/javascript/plugins/drone/contrib/rainbow.js +++ b/src/main/javascript/plugins/drone/contrib/rainbow.js @@ -2,17 +2,15 @@ var Drone = require('../drone').Drone; var blocks = require('blocks'); /************************************************************************ -Drone.rainbow() method -====================== +## Drone.rainbow() method + Creates a Rainbow. -Parameters ----------- +### Parameters * radius (optional - default:18) - The radius of the rainbow -Example -------- +### Example var d = new Drone(); d.rainbow(30); diff --git a/src/main/javascript/plugins/drone/contrib/spiral_stairs.js b/src/main/javascript/plugins/drone/contrib/spiral_stairs.js index 7385ffc..5f6bf35 100644 --- a/src/main/javascript/plugins/drone/contrib/spiral_stairs.js +++ b/src/main/javascript/plugins/drone/contrib/spiral_stairs.js @@ -2,12 +2,11 @@ var Drone = require('../drone').Drone; var blocks = require('blocks'); /************************************************************************ -Drone.spiral_stairs() method -============================ +## Drone.spiral_stairs() method + Constructs a spiral staircase with slabs at each corner. -Parameters ----------- +### Parameters * stairBlock - The block to use for stairs, should be one of the following... - 'oak' @@ -24,8 +23,8 @@ Parameters ![Spiral Staircase](img/spiralstair1.png) -Example -------- +### Example + To construct a spiral staircase 5 floors high made of oak... spiral_stairs('oak', 5); diff --git a/src/main/javascript/plugins/drone/sphere.js b/src/main/javascript/plugins/drone/sphere.js index ab0234c..2dbdf5c 100644 --- a/src/main/javascript/plugins/drone/sphere.js +++ b/src/main/javascript/plugins/drone/sphere.js @@ -1,18 +1,17 @@ var Drone = require('./drone').Drone; /************************************************************************ -Drone.sphere() method -===================== +## Drone.sphere() method + Creates a sphere. -Parameters ----------- +### Parameters * block - The block the sphere will be made of. * radius - The radius of the sphere. -Example -------- +### Example + To create a sphere of Iron with a radius of 10 blocks... sphere( blocks.iron, 10); @@ -68,18 +67,17 @@ Drone.extend('sphere', function(block,radius) return this.move('sphere'); }); /************************************************************************ -Drone.sphere0() method -====================== +## Drone.sphere0() method + Creates an empty sphere. -Parameters ----------- +### Parameters * block - The block the sphere will be made of. * radius - The radius of the sphere. -Example -------- +### Example + To create a sphere of Iron with a radius of 10 blocks... sphere0( blocks.iron, 10); @@ -168,19 +166,18 @@ Drone.extend('sphere0', function(block,radius) }); /************************************************************************ -Drone.hemisphere() method -========================= +## Drone.hemisphere() method + Creates a hemisphere. Hemispheres can be either north or south. -Parameters ----------- +### Parameters * block - the block the hemisphere will be made of. * radius - the radius of the hemisphere * northSouth - whether the hemisphere is 'north' or 'south' -Example -------- +### Example + To create a wood 'north' hemisphere with a radius of 7 blocks... hemisphere(blocks.oak, 7, 'north'); @@ -239,19 +236,18 @@ Drone.extend('hemisphere', function(block,radius, northSouth){ }); /************************************************************************ -Drone.hemisphere0() method -========================= +## Drone.hemisphere0() method + Creates a hollow hemisphere. Hemispheres can be either north or south. -Parameters ----------- +### Parameters * block - the block the hemisphere will be made of. * radius - the radius of the hemisphere * northSouth - whether the hemisphere is 'north' or 'south' -Example -------- +### Example + To create a glass 'north' hemisphere with a radius of 20 blocks... hemisphere0(blocks.glass, 20, 'north'); diff --git a/src/main/javascript/plugins/homes/homes.js b/src/main/javascript/plugins/homes/homes.js index 913720d..01a079c 100644 --- a/src/main/javascript/plugins/homes/homes.js +++ b/src/main/javascript/plugins/homes/homes.js @@ -1,4 +1,7 @@ var utils = require('utils'); +/* + TODO: Document this plugin! +*/ var _store = { houses: {}, openHouses: {},