updated docs for module loading

This commit is contained in:
walterhiggins 2013-12-24 10:02:34 +00:00
parent 5953a55fb1
commit 7f9736223e

View file

@ -7,55 +7,139 @@ Walter Higgins
[email]: mailto:walter.higgins@gmail.com?subject=ScriptCraft_API_Reference [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 ## 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 ### 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. * 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 * mini-games - Contains mini-games
* arrows - The arrows module * arrows - The arrows module
* signs - The signs module * signs - The signs module (includes example signs)
* chat - The chat plugin/module * chat - The chat plugin/module
* alias - The alias 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. * 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 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. 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')`
* 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. * 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 'store' property - this will be created automatically if not
already defined. (its type is object {} ) . More on plugins below. 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 * command (name, function) - defines a command that can be used by
non-operators. The `command` function provides a way for plugin non-operators. The `command` function provides a way for plugin
developers to provide new commands for use by players. 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 ### 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 #### Parameters