release notes for 'modules' release

docs/release-notes.md

@@ -0,0 +1,132 @@
+
+# 2013 12 24
+
+## 'Modules' release
+
+### Modules in ScriptCraft
+
+ScriptCraft now has a simple module loading system. ScriptCraft now uses the [CommonJS module contract][cjsmod] - that is - the same module system used by Node.js. All of the javascript code which comes bundled with ScriptCraft has been modified so that it conforms to the CommonJS module system. 
+
+### What this means for plugins you've developed using ScriptCraft
+
+If you have written plugins using a previous version of ScriptCraft then you have 2 options...
+
+ 1. Continue using the previous version of ScriptCraft.
+ 2. Update your plugins to work with the ScriptCraft 'Modules' release.
+
+... Option 2 should be relatively straightforward if you follow these steps...
+
+ 1. Copy your own custom plugins from the `js-plugins` directory to the new `scriptcraft/plugins` directory.
+ 2. In your javascript code any functions, objects or variables which you want to expose for use by others should be exposed using the special `exports` variable. All other code within your .js files will now be private by default. See below for details on how CommonJS/Node.js modules work.
+
+If you have any questions or concerns or need help converting your existing javascript plugin, contact please post questions on the [ScriptCraft forum][scforum] or open an issue on the [Github project][github]
+
+[github]: http://github.com/walterhiggins/ScriptCraft
+[scforum]: https://groups.google.com/forum/?fromgroups=#!forum/scriptcraft---scripting-minecraft 
+
+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
+[cjsmod]: http://wiki.commonjs.org/wiki/Modules/1.1.1
+
+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
+
+When the ScriptCraft Java plugin is first installed, a new
+subdirectory is created in the craftbukkit directory. If your
+craftbukkit directory is called 'craftbukkit' then the new
+subdirectories will be ...
+
+ * craftbukkit/scriptcraft/
+ * craftbukkit/scriptcraft/plugins
+ * craftbukkit/scriptcraft/modules
+ * craftbukkit/scriptcraft/lib
+
+... The `plugins`, `modules` and `lib` directories each serve a different purpose.
+
+##### The plugins directory
+
+At server startup the ScriptCraft Java plugin is loaded and begins
+automatically loading and executing all of the modules (javascript
+files with the extension `.js`) it finds in the `scriptcraft/plugins`
+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.