diff --git a/docs/api.md b/docs/api.md index 7a9777f..64a8cda 100644 --- a/docs/api.md +++ b/docs/api.md @@ -65,7 +65,14 @@ This module defines commonly used functions by all plugins... load() function --------------- -The load() function is used by ScriptCraft at startup to load all of the javascript modules and data. +The load() function is used by ScriptCraft at startup to load all of +the javascript modules and data. You normally wouldn't need to call +this function directly. If you put a javascript file anywhere in the +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 ---------- @@ -95,14 +102,122 @@ myData.json contents... } } +save() function +--------------- +The save() function saves an in-memory javascript object to a +specified file. Under the hood, save() uses JSON (specifically +json2.js) to save the object. Again, there will usually be no need to +call this function directly as all javascript plugins' state are saved +automatically if they are declared using the `plugin()` function. Any +in-memory object saved using the `save()` function can later be +restored using the `load()` function. + +Parameters +---------- + + * objectToSave : The object you want to save. + * filename : The name of the file you want to save it to. + +Example +------- + + var myObject = { name: 'John Doe', + aliases: ['John Ray', 'John Mee'], + date_of_birth: '1982/01/31' }; + save(myObject, 'johndoe.json'); + +johndoe.json contents... + + var __data = { "name": "John Doe", + "aliases": ["John Ray", "John Mee"], + "date_of_birth": "1982/01/31" }; + +plugin() function +----------------- +The `plugin()` function should be used to declare a javascript module +whose state you want to have managed by ScriptCraft - that is - a +Module whose state will be loaded at start up and saved at shut down. +A plugin is just a regular javascript object whose state is managed by +ScriptCraft. The only member of the plugin which whose persistence is +managed by Scriptcraft is `state` - this special member will be +automatically saved at shutdown and loaded at startup by +ScriptCraft. This makes it easier to write plugins which need to +persist data. + +Parameters +---------- + + * pluginName (String) : The name of the plugin - this becomes a global variable. + * pluginDefinition (Object) : The various functions and members of the plugin object. + * isPersistent (boolean - optional) : Specifies whether or not the plugin/object state should be loaded and saved by ScriptCraft. + +Example +------- +See chat/color.js for an example of a simple plugin - one which lets +players choose a default chat color. See also [Anatomy of a +ScriptCraft Plugin][anatomy]. + +[anatomy]: http://walterhiggins.net/blog/ScriptCraft-1-Month-later + +command() function +------------------ +The `command()` function is used to expose javascript functions for +use by non-operators (regular players). Only operators should be +allowed use raw javascript using the `/js ` command because it is too +powerful for use by regular players and can be easily abused. However, +the `/jsp ` command lets you (the operator / server administrator / +plugin author) safely expose javascript functions for use by players. + +Parameters +---------- + + * commandName : The name to give your command - the command will be invoked like this by players `/jsp commandName` + * commandFunction: The javascript function which will be invoked when the command is invoked by a player. + * options (Array - optional) : An array of command options/parameters + which the player can supply (It's useful to supply an array so that + Tab-Completion works for the `/jsp ` commands. + * intercepts (boolean - optional) : Indicates whether this command + can intercept Tab-Completion of the `/jsp ` command - advanced + usage - see alias/alias.js for example. + +Example +------- +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. + 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. - * _plugin - The ScriptCraft JavaPlugin object. + * __plugin - The ScriptCraft JavaPlugin object. * server - The Minecraft Server object. - * self - the current player. + * self - the current player. (Note - this value should not be used in multi-threaded scripts - it's not thread-safe) Drone Module ============ diff --git a/src/main/javascript/core/_scriptcraft.js b/src/main/javascript/core/_scriptcraft.js index 657e6e0..4ab4c8c 100644 --- a/src/main/javascript/core/_scriptcraft.js +++ b/src/main/javascript/core/_scriptcraft.js @@ -66,7 +66,14 @@ This module defines commonly used functions by all plugins... load() function --------------- -The load() function is used by ScriptCraft at startup to load all of the javascript modules and data. +The load() function is used by ScriptCraft at startup to load all of +the javascript modules and data. You normally wouldn't need to call +this function directly. If you put a javascript file anywhere in the +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 ---------- @@ -96,14 +103,122 @@ myData.json contents... } } +save() function +--------------- +The save() function saves an in-memory javascript object to a +specified file. Under the hood, save() uses JSON (specifically +json2.js) to save the object. Again, there will usually be no need to +call this function directly as all javascript plugins' state are saved +automatically if they are declared using the `plugin()` function. Any +in-memory object saved using the `save()` function can later be +restored using the `load()` function. + +Parameters +---------- + + * objectToSave : The object you want to save. + * filename : The name of the file you want to save it to. + +Example +------- + + var myObject = { name: 'John Doe', + aliases: ['John Ray', 'John Mee'], + date_of_birth: '1982/01/31' }; + save(myObject, 'johndoe.json'); + +johndoe.json contents... + + var __data = { "name": "John Doe", + "aliases": ["John Ray", "John Mee"], + "date_of_birth": "1982/01/31" }; + +plugin() function +----------------- +The `plugin()` function should be used to declare a javascript module +whose state you want to have managed by ScriptCraft - that is - a +Module whose state will be loaded at start up and saved at shut down. +A plugin is just a regular javascript object whose state is managed by +ScriptCraft. The only member of the plugin which whose persistence is +managed by Scriptcraft is `state` - this special member will be +automatically saved at shutdown and loaded at startup by +ScriptCraft. This makes it easier to write plugins which need to +persist data. + +Parameters +---------- + + * pluginName (String) : The name of the plugin - this becomes a global variable. + * pluginDefinition (Object) : The various functions and members of the plugin object. + * isPersistent (boolean - optional) : Specifies whether or not the plugin/object state should be loaded and saved by ScriptCraft. + +Example +------- +See chat/color.js for an example of a simple plugin - one which lets +players choose a default chat color. See also [Anatomy of a +ScriptCraft Plugin][anatomy]. + +[anatomy]: http://walterhiggins.net/blog/ScriptCraft-1-Month-later + +command() function +------------------ +The `command()` function is used to expose javascript functions for +use by non-operators (regular players). Only operators should be +allowed use raw javascript using the `/js ` command because it is too +powerful for use by regular players and can be easily abused. However, +the `/jsp ` command lets you (the operator / server administrator / +plugin author) safely expose javascript functions for use by players. + +Parameters +---------- + + * commandName : The name to give your command - the command will be invoked like this by players `/jsp commandName` + * commandFunction: The javascript function which will be invoked when the command is invoked by a player. + * options (Array - optional) : An array of command options/parameters + which the player can supply (It's useful to supply an array so that + Tab-Completion works for the `/jsp ` commands. + * intercepts (boolean - optional) : Indicates whether this command + can intercept Tab-Completion of the `/jsp ` command - advanced + usage - see alias/alias.js for example. + +Example +------- +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. + 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. - * _plugin - The ScriptCraft JavaPlugin object. + * __plugin - The ScriptCraft JavaPlugin object. * server - The Minecraft Server object. - * self - the current player. + * self - the current player. (Note - this value should not be used in multi-threaded scripts - it's not thread-safe) ***/