updated docs for module loading

src/main/javascript/lib/scriptcraft.js

@@ -7,55 +7,139 @@ Walter Higgins
 
 [email]: mailto:walter.higgins@gmail.com?subject=ScriptCraft_API_Reference
 
+## Modules in Scriptcraft
+
+ScriptCraft has a simple module loading system. In ScriptCraft, files
+and modules are in one-to-one correspondence. As an example, foo.js
+loads the module circle.js in the same directory. 
+*ScriptCraft now uses the same module system as Node.js - see [Node.js Modules][njsmod] for more details.*
+
+[njsmod]: http://nodejs.org/api/modules.html
+
+The contents of foo.js:
+
+    var circle = require('./circle.js');
+    echo( 'The area of a circle of radius 4 is '
+               + circle.area(4));
+
+The contents of circle.js:
+
+    var PI = Math.PI;
+    
+    exports.area = function (r) {
+      return PI * r * r;
+    };
+
+    exports.circumference = function (r) {
+      return 2 * PI * r;
+    };
+
+The module circle.js has exported the functions area() and
+circumference(). To add functions and objects to the root of your
+module, you can add them to the special exports object.
+
+Variables local to the module will be private, as though the module
+was wrapped in a function. In this example the variable PI is private
+to circle.js.
+
+If you want the root of your module's export to be a function (such as
+a constructor) or if you want to export a complete object in one
+assignment instead of building it one property at a time, assign it to
+module.exports instead of exports.
+
 ## Module Loading
 
-At server startup the ScriptCraft Java plugin is loaded and once
+When the ScriptCraft Java plugin is first installed, a new
-loaded the Java plugin will in turn begin loading all of the
+subdirectory is created in the craftbukkit directory. If your
-javascript (.js) files it finds in the js-plugins directory (in the
+craftbukkit directory is called 'craftbukkit' then the new
-current working directory).  If this is the first time the ScriptCraft
+subdirectories will be ...
-plugin is loaded, then the js-plugins directory will not yet exist, it
-will be created and all of the bundled javascript files will be
-unzipped into it from a bundled resource within the Java plugin.  The
-very first javascript file to load will always be
-js-plugins/core/_scriptcraft.js. Then all other javascript files are
-loaded except for filenames which begin with `_` (underscore), such files
-are considered to be private modules and will not be automatically
-loaded at startup.
 
-### Directory structure
+ * craftbukkit/scriptcraft/
+ * craftbukkit/scriptcraft/plugins
+ * craftbukkit/scriptcraft/modules
+ * craftbukkit/scriptcraft/lib
 
-The js-plugins directory is loosely organised into subdirectories -
+... The `plugins`, `modules` and `lib` directories each serve a different purpose.
-one for each module. Each subdirectory in turn can contain one or more
+
-javascript files. Within each directory, a javascript file with the
+### The `plugins` directory
-same filename as the directory will always be loaded before all other
+
-files in the same directory. So for example, drone/drone.js will
+At server startup the ScriptCraft Java plugin is loaded and begins
-always load before any other files in the drone/ directory. Similarly
+automatically loading and executing all of the modules (javascript
-utils/utils.js will always load before any other files in the utils/
+files with the extension `.js`) it finds in the `scriptcraft/plugins`
-directory.
+directory. All modules in the plugins directory are automatically
+loaded into the `global` namespace. What this means is that anything a
+module in the `plugins` directory exports becomes a global
+variable. For example, if you have a module greeting.js in the plugins
+directory....
+
+    exports.greet = function() {
+        echo('Hello ' + self.name);
+    };
+
+... then `greet` becomes a global function and can be used at the
+in-game (or server) command prompt like so...
+
+    /js greet()
+
+... This differs from how modules (in NodeJS and commonJS
+environments) normally work. If you want your module to be exported
+globally, put it in the `plugins` directory. If you don't want your
+module to be exported globally but only want it to be used by other
+modules, then put it in the `modules` directory instead. If you've
+used previous versions of ScriptCraft and have put your custom
+javascript modules in the `js-plugins` directory, then put them in the
+`scriptcraft/plugins` directory. To summarise, modules in this directory are ...
+
+ * Automatically loaded and run at server startup.
+ * Anything exported by modules becomes a global variable.
+
+### The `modules` directory
+
+The module directory is where you should place your modules if you
+don't want to export globally. In javascript, it's considered best
+practice not to have too many global variables, so if you want to
+develop modules for others to use, or want to develop more complex
+mods then your modules should be placed in the `modules` directory.
+*Modules in the `modules` directory are not automatically loaded at
+startup*, instead, they are loaded and used by other modules/plugins
+using the standard `require()` function.  This is the key difference
+between modules in the `plugins` directory and modules in the
+`modules` directory. Modules in the `plugins` directory are
+automatically loaded and exported in to the global namespace at server
+startup, modules in the `modules` directory are not.
+
+### The `lib` directory
+
+Modules in the `lib` directory are for use by ScriptCraft and some
+core functions for use by module and plugin developers are also
+provided. The `lib` directory is for internal use by ScriptCraft.
+Modules in this directory are not automatically loaded nor are they
+globally exported.
 
 ### Directories 
 
-As of February 10 2013, the js-plugins directory has the following sub-directories...
+As of December 24 2013, the `scriptcraft/plugins` directory has the following sub-directories...
 
- * core - Contains javascript files containing Core functionality crucial to ScriptCraft and modules which use it.
  * drone - Contains the drone module and drone extensions. Drone was the first scriptcraft module.
- * ext - Contains external 3rd party javascript libraries (e.g. json2.js - the JSON lib)
  * mini-games - Contains mini-games 
  * arrows - The arrows module
- * signs - The signs module
+ * signs - The signs module (includes example signs)
  * chat - The chat plugin/module
  * alias - The alias plugin/module
+ * home - The home module - for setting homes and visiting other homes.
 
-## Core Module
+## Free Variables
 
-This module defines commonly used functions by all plugins...
+ScripCraft provides some functions which can be used by all plugins/modules...
 
  * 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')` 
 
- * load (filename,warnOnFileNotFound) - loads and evaluates a javascript file, returning the evaluated object.
+ * require (modulename) - Will load modules. See [Node.js modules][njsmod]
+
+ * load (filename,warnOnFileNotFound) - loads and evaluates a javascript file, returning the evaluated object. (Note: Prefer `require()` to `load()`)
   
  * save (object, filename) - saves an object to a file.
 
@@ -66,22 +150,34 @@ This module defines commonly used functions by all plugins...
    'store' property - this will be created automatically if not
    already defined.  (its type is object {} ) . More on plugins below.
     
- * ready (function) - specifies code to be executed only when all the plugins have loaded.
-
  * command (name, function) - defines a command that can be used by
    non-operators. The `command` function provides a way for plugin
    developers to provide new commands for use by players.
 
+### require() function
+
+ScriptCraft's `require()` function is used to load modules. The `require()` function takes a 
+module name as a parameter and will try to load the named module.
+
+#### Parameters
+
+ * modulename - The name of the module to be loaded. Can be one of the following...
+
+   - A relative file path (with or without `.js` suffix)
+   - An absolute file path (with or without `.js` suffix)
+   - A relative directory path (uses node.js rules for directories)
+   - An absolute directory path (uses node.js rules for directories)
+   - A name of the form `'events'` - in which case the `lib` directory and `modules` directories are searched for the module.
+
+#### Return
+
+require() will return the loaded module's exports.
+
 ### load() function 
 
-The load() function is used by ScriptCraft at startup to load all of
+#### No longer recommended for use by Plugin/Module developers (deprecated)
-the javascript modules and data.  You normally wouldn't need to call
+
-this function directly. If you put a javascript file anywhere in the
+load() should only be used to load .json data.
-craftbukkit/js-plugins directory tree it will be loaded automatically
-when craftbukkit starts up. The exception is files whose name begins
-with an underscore `_` character. These files will not be
-automatically loaded at startup as they are assumed to be files
-managed / loaded by plugins.
 
 #### Parameters