arg/scriptcraft
Archived
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

reorg

Browse source
This commit is contained in:
walterhiggins 2013-12-24 00:15:17 +00:00
parent 7f3b17a07c
commit eb098ff176
2 changed files with 484 additions and 399 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

877
docs/API-Reference.md
View file

@ -1,332 +1,3 @@
# ScriptCraft API Reference
Walter Higgins
[walter.higgins@gmail.com][email]
[email]: mailto:walter.higgins@gmail.com?subject=ScriptCraft_API_Reference
## Module Loading
At server startup the ScriptCraft Java plugin is loaded and once
loaded the Java plugin will in turn begin loading all of the
javascript (.js) files it finds in the js-plugins directory (in the
current working directory). If this is the first time the ScriptCraft
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
The js-plugins directory is loosely organised into subdirectories -
one for each module. Each subdirectory in turn can contain one or more
javascript files. Within each directory, a javascript file with the
same filename as the directory will always be loaded before all other
files in the same directory. So for example, drone/drone.js will
always load before any other files in the drone/ directory. Similarly
utils/utils.js will always load before any other files in the utils/
directory.
### Directories
As of February 10 2013, the js-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
* chat - The chat plugin/module
* alias - The alias plugin/module
## Core Module
This module defines commonly used functions by all plugins...
* load (filename,warnOnFileNotFound) - loads and evaluates a javascript file, returning the evaluated object.
* save (object, filename) - saves an object to a file.
* plugin (name, interface, isPersistent) - defines a new plugin. If
isPersistent is true then the plugin doesn't have to worry about
loading and saving state - that will be done by the framework. Just
make sure that anything you want to save (and restore) is in the plugin's
'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.
### load() function
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
* filename - The name of the file to load.
* warnOnFileNotFound (optional - default: false) - warn if the file was not found.
#### Return
load() will return the result of the last statement evaluated in the file.
#### Example
load(__folder + "myFile.js"); // loads a javascript file and evaluates it.
var myData = load("myData.json"); // loads a javascript file and evaluates it - eval'd contents are returned.
myData.json contents...
__data = {
players: {
walterh: {
h: ["jsp home {1}"],
sunny:["time set 0",
"weather clear"]
}
}
}
### 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.
* server - The Minecraft Server object.
* self - the current player. (Note - this value should not be used in multi-threaded scripts - it's not thread-safe)
## Miscellaneous Core Functions
### setTimeout() function
This function mimics the setTimeout() function used in browser-based javascript.
However, the function will only accept a function reference, not a string of javascript code.
Where setTimeout() in the browser returns a numeric value which can be subsequently passed to
clearTimeout(), This implementation returns a [BukkitTask][btdoc] object which can be subsequently passed to ScriptCraft's own clearTimeout() implementation.
If Node.js supports setTimeout() then it's probably good for ScriptCraft to support it too.
[btdoc]: http://jd.bukkit.org/beta/apidocs/org/bukkit/scheduler/BukkitTask.html
#### Example
//
// start a storm in 5 seconds
//
setTimeout( function() {
var world = server.worlds.get(0);
world.setStorm(true);
}, 5000);
### clearTimeout() function
A scriptcraft implementation of clearTimeout().
### setInterval() function
This function mimics the setInterval() function used in browser-based javascript.
However, the function will only accept a function reference, not a string of javascript code.
Where setInterval() in the browser returns a numeric value which can be subsequently passed to
clearInterval(), This implementation returns a [BukkitTask][btdoc] object which can be subsequently passed to ScriptCraft's own clearInterval() implementation.
If Node.js supports setInterval() then it's probably good for ScriptCraft to support it too.
[btdoc]: http://jd.bukkit.org/beta/apidocs/org/bukkit/scheduler/BukkitTask.html
### clearInterval() function
A scriptcraft implementation of clearInterval().
### refresh() function
The refresh() function will ...
1. Disable the ScriptCraft plugin.
2. Unload all event listeners associated with the ScriptCraft plugin.
3. Enable the ScriptCraft plugin.
... refresh() can be used during development to reload only scriptcraft javascript files.
See [issue #69][issue69] for more information.
[issue69]: https://github.com/walterhiggins/ScriptCraft/issues/69
## Require - Node.js-style module loading in ScriptCraft
#### (Experimental as of 2013-12-21)
Node.js is a server-side javascript environment with an excellent
module loading system based on CommonJS. Modules in Node.js are really
simple. Each module is in its own javascript file and all variables
and functions within the file are private to that file/module only.
There is a very concise explanation of CommonJS modules at...
[http://wiki.commonjs.org/wiki/Modules/1.1.1.][cjsmodules]
If you want to export a variable or function you use the module.export
property.
For example imagine you have 3 files program.js, inc.js and math.js ...
### math.js
exports.add = function(a,b){
return a + b;
}
### inc.js
var math = require('./math');
exports.increment = function(n){
return math.add(n, 1);
}
### program.js
var inc = require('./inc').increment;
var a = 7;
a = inc(a);
print(a);
You can see from the above sample code that programs can use modules
and modules themeselves can use other modules. Modules have full
control over what functions and properties they want to provide to
others.
## 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.
Right now, the base directory is for relative modules is 'js-plugins'.
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.
Drone Module Drone Module
============ ============
The Drone is a convenience class for building. It can be used for... The Drone is a convenience class for building. It can be used for...
@ -693,6 +364,7 @@ To draw a 1/4 circle (top right quadrant only) with a radius of 10 and stroke wi
[bres]: http://en.wikipedia.org/wiki/Midpoint_circle_algorithm [bres]: http://en.wikipedia.org/wiki/Midpoint_circle_algorithm
[dv]: http://www.minecraftwiki.net/wiki/Data_values [dv]: http://www.minecraftwiki.net/wiki/Data_values
Drone.door() method Drone.door() method
=================== ===================
create a door - if a parameter is supplied an Iron door is created otherwise a wooden door is created. create a door - if a parameter is supplied an Iron door is created otherwise a wooden door is created.
@ -778,6 +450,7 @@ the `up()` method is called first).
None of the tree methods require parameters. Tree methods will only be successful None of the tree methods require parameters. Tree methods will only be successful
if the tree is placed on grass in a setting where trees can grow. if the tree is placed on grass in a setting where trees can grow.
Drone.garden() method Drone.garden() method
===================== =====================
places random flowers and long grass (similar to the effect of placing bonemeal on grass) places random flowers and long grass (similar to the effect of placing bonemeal on grass)
@ -1182,46 +855,369 @@ To construct a spiral staircase 5 floors high made of oak...
spiral_stairs('oak', 5); spiral_stairs('oak', 5);
Classroom Module ## Require - Node.js-style module loading in ScriptCraft
================
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
classroom environment. Although granting ScriptCraft access to
students on a shared server is potentially risky (Students can
potentially abuse it), it is slighlty less risky than granting
operator privileges to each student. (Enterprising students will
quickly realise how to grant themselves and others operator privileges
once they have access to ScriptCraft).
The goal of this module is not so much to enforce restrictions #### (Experimental as of 2013-12-21)
(security or otherwise) but to make it easier for tutors to setup a shared server
so students can learn Javascript.
classroom.allowScripting() function Node.js is a server-side javascript environment with an excellent
=================================== module loading system based on CommonJS. Modules in Node.js are really
Allow or disallow anyone who connects to the server (or is already simple. Each module is in its own javascript file and all variables
connected) to use ScriptCraft. This function is preferable to granting 'ops' privileges and functions within the file are private to that file/module only.
to every student in a Minecraft classroom environment. There is a very concise explanation of CommonJS modules at...
Parameters [http://wiki.commonjs.org/wiki/Modules/1.1.1.][cjsmodules]
----------
* canScript : true or false If you want to export a variable or function you use the module.export
property.
Example For example imagine you have 3 files program.js, inc.js and math.js ...
-------
To allow all players (and any players who connect to the server) to
use the `js` and `jsp` commands...
/js classroom.allowScripting(true) ### math.js
To disallow scripting (and prevent players who join the server from using the commands)... exports.add = function(a,b){
return a + b;
}
/js classroom.allowScripting(false) ### inc.js
Only ops users can run the classroom.allowScripting() function - this is so that students var math = require('./math');
don't try to bar themselves and each other from scripting. exports.increment = function(n){
return math.add(n, 1);
}
### program.js
var inc = require('./inc').increment;
var a = 7;
a = inc(a);
print(a);
You can see from the above sample code that programs can use modules
and modules themeselves can use other modules. Modules have full
control over what functions and properties they want to provide to
others.
## 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.
Right now, the base directory is for relative modules is 'js-plugins'.
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...
1. if the module does not begin with './' or '/' then ...
1.1 Look in the 'scriptcraft/lib' directory. If it's not there then...
1.2 Look in the 'scriptcraft/modules' directory. If it's not there then
Throw an Error.
2. If the module begins with './' or '/' then ...
2.1 if the module begins with './' then it's treated as a file path. File paths are
always relative to the module from which the require() call is being made.
2.2 If the module begins with '/' then it's treated as an absolute path.
If the module does not have a '.js' suffix, and a file with the same name and a .js sufix exists,
then the file will be loaded.
3. If the module name resolves to a directory then...
3.1 look for a package.json file in the directory and load the `main` property e.g.
// package.json located in './some-library/'
{
"main": './some-lib.js',
"name": 'some-library'
}
3.2 if no package.json file exists then look for an index.js file in the directory
# ScriptCraft API Reference
Walter Higgins
[walter.higgins@gmail.com][email]
[email]: mailto:walter.higgins@gmail.com?subject=ScriptCraft_API_Reference
## Module Loading
At server startup the ScriptCraft Java plugin is loaded and once
loaded the Java plugin will in turn begin loading all of the
javascript (.js) files it finds in the js-plugins directory (in the
current working directory). If this is the first time the ScriptCraft
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
The js-plugins directory is loosely organised into subdirectories -
one for each module. Each subdirectory in turn can contain one or more
javascript files. Within each directory, a javascript file with the
same filename as the directory will always be loaded before all other
files in the same directory. So for example, drone/drone.js will
always load before any other files in the drone/ directory. Similarly
utils/utils.js will always load before any other files in the utils/
directory.
### Directories
As of February 10 2013, the js-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
* chat - The chat plugin/module
* alias - The alias plugin/module
## Core Module
This module defines commonly used functions by all plugins...
* 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.
* save (object, filename) - saves an object to a file.
* plugin (name, interface, isPersistent) - defines a new plugin. If
isPersistent is true then the plugin doesn't have to worry about
loading and saving state - that will be done by the framework. Just
make sure that anything you want to save (and restore) is in the plugin's
'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.
### load() function
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
* filename - The name of the file to load.
* warnOnFileNotFound (optional - default: false) - warn if the file was not found.
#### Return
load() will return the result of the last statement evaluated in the file.
#### Example
load(__folder + "myFile.js"); // loads a javascript file and evaluates it.
var myData = load("myData.json"); // loads a javascript file and evaluates it - eval'd contents are returned.
myData.json contents...
__data = {
players: {
walterh: {
h: ["jsp home {1}"],
sunny:["time set 0",
"weather clear"]
}
}
}
### 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 `store` - 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.
* server - The Minecraft Server object.
* self - the current player. (Note - this value should not be used in multi-threaded scripts - it's not thread-safe)
## Miscellaneous Core Functions
### setTimeout() function
This function mimics the setTimeout() function used in browser-based javascript.
However, the function will only accept a function reference, not a string of javascript code.
Where setTimeout() in the browser returns a numeric value which can be subsequently passed to
clearTimeout(), This implementation returns a [BukkitTask][btdoc] object which can be subsequently passed to ScriptCraft's own clearTimeout() implementation.
If Node.js supports setTimeout() then it's probably good for ScriptCraft to support it too.
[btdoc]: http://jd.bukkit.org/beta/apidocs/org/bukkit/scheduler/BukkitTask.html
#### Example
//
// start a storm in 5 seconds
//
setTimeout( function() {
var world = server.worlds.get(0);
world.setStorm(true);
}, 5000);
### clearTimeout() function
A scriptcraft implementation of clearTimeout().
### setInterval() function
This function mimics the setInterval() function used in browser-based javascript.
However, the function will only accept a function reference, not a string of javascript code.
Where setInterval() in the browser returns a numeric value which can be subsequently passed to
clearInterval(), This implementation returns a [BukkitTask][btdoc] object which can be subsequently passed to ScriptCraft's own clearInterval() implementation.
If Node.js supports setInterval() then it's probably good for ScriptCraft to support it too.
[btdoc]: http://jd.bukkit.org/beta/apidocs/org/bukkit/scheduler/BukkitTask.html
### clearInterval() function
A scriptcraft implementation of clearInterval().
### refresh() function
The refresh() function will ...
1. Disable the ScriptCraft plugin.
2. Unload all event listeners associated with the ScriptCraft plugin.
3. Enable the ScriptCraft plugin.
... refresh() can be used during development to reload only scriptcraft javascript files.
See [issue #69][issue69] for more information.
[issue69]: https://github.com/walterhiggins/ScriptCraft/issues/69
events Module events Module
============= =============
@ -1269,12 +1265,16 @@ Example:
------ ------
The following code will print a message on screen every time a block is broken in the game 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){ events.on("block.BlockBreakEvent", function(listener, evt){
echo (evt.player.name + " broke a block!"); echo (evt.player.name + " broke a block!");
}); });
To handle an event only once and unregister from further events... To handle an event only once and unregister from further events...
var events = require('./events/events');
events.on("block.BlockBreakEvent", function(listener, evt){ events.on("block.BlockBreakEvent", function(listener, evt){
print (evt.player.name + " broke a block!"); print (evt.player.name + " broke a block!");
evt.handlers.unregister(listener); evt.handlers.unregister(listener);
@ -1282,6 +1282,8 @@ To handle an event only once and unregister from further events...
To unregister a listener *outside* of the listener function... 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(); var handlers = org.bukkit.event.block.BlockBreakEvent.getHandlerList();
@ -1306,7 +1308,7 @@ Example....
... creates a single firework, while .... ... creates a single firework, while ....
/js firework.fwd(3).times(5) /js firework().fwd(3).times(5)
... creates 5 fireworks in a row. Fireworks have also been added as a ... creates 5 fireworks in a row. Fireworks have also been added as a
possible option for the `arrow` module. To have a firework launch possible option for the `arrow` module. To have a firework launch
@ -1317,6 +1319,7 @@ where an arrow strikes...
To call the fireworks.firework() function directly, you must provide a To call the fireworks.firework() function directly, you must provide a
location. For example... location. For example...
/js var fireworks = require('fireworks');
/js fireworks.firework(self.location); /js fireworks.firework(self.location);
![firework example](img/firework.png) ![firework example](img/firework.png)
@ -1347,12 +1350,14 @@ Example
The following example illustrates how to use http.request to make a request to a JSON web service and evaluate its response... The following example illustrates how to use http.request to make a request to a JSON web service and evaluate its response...
var jsResponse; var jsResponse;
var http = require('./http/request');
http.request("http://scriptcraftjs.org/sample.json",function(responseCode, responseBody){ http.request("http://scriptcraftjs.org/sample.json",function(responseCode, responseBody){
jsResponse = eval("(" + responseBody + ")"); jsResponse = eval("(" + responseBody + ")");
}); });
... The following example illustrates a more complex use-case POSTing parameters to a CGI process on a server... ... The following example illustrates a more complex use-case POSTing parameters to a CGI process on a server...
var http = require('./http/request');
http.request({ url: "http://pixenate.com/pixenate/pxn8.pl", http.request({ url: "http://pixenate.com/pixenate/pxn8.pl",
method: "POST", method: "POST",
params: {script: "[]"} params: {script: "[]"}
@ -1360,6 +1365,47 @@ The following example illustrates how to use http.request to make a request to a
var jsObj = eval("(" + responseBody + ")"); var jsObj = eval("(" + responseBody + ")");
}); });
String class extensions
-----------------------
The following chat-formatting methods are added to the javascript String class..
* aqua()
* black()
* blue()
* bold()
* brightgreen()
* darkaqua()
* darkblue()
* darkgray()
* darkgreen()
* purple()
* darkpurple()
* darkred()
* gold()
* gray()
* green()
* italic()
* lightpurple()
* indigo()
* green()
* red()
* pink()
* yellow()
* white()
* strike()
* random()
* magic()
* underline()
* reset()
Example
-------
var boldGoldText = "Hello World".bold().gold();
self.sendMessage(boldGoldText);
<p style="color:gold;font-weight:bold">Hello World</p>
Utilities Module Utilities Module
================ ================
Miscellaneous utility functions and classes to help with programming. Miscellaneous utility functions and classes to help with programming.
@ -1369,7 +1415,13 @@ Miscellaneous utility functions and classes to help with programming.
* getPlayerObject(playerName) - returns the Player object for a named * getPlayerObject(playerName) - returns the Player object for a named
player or `self` if no name is provided. player or `self` if no name is provided.
utils.foreach() function * getPlayerPos(playerName) - returns the player's x,y,z and yaw (direction) for a named player
or player or `self` if no parameter is provided.
* 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
======================== ========================
The utils.foreach() function is a utility function for iterating over 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 an array of objects (or a java.util.Collection of objects) and processing each object in turn. Where
@ -1417,6 +1469,7 @@ Example
------- -------
The following example illustrates how to use foreach for immediate processing of an array... The following example illustrates how to use foreach for immediate processing of an array...
var utils = require('./utils/_utils');
var players = ["moe", "larry", "curly"]; var players = ["moe", "larry", "curly"];
utils.foreach (players, function(item){ utils.foreach (players, function(item){
server.getPlayer(item).sendMessage("Hi " + item); server.getPlayer(item).sendMessage("Hi " + item);
@ -1436,6 +1489,7 @@ without hogging CPU usage...
// build a structure 200 wide x 200 tall x 200 long // build a structure 200 wide x 200 tall x 200 long
// (That's 8 Million Blocks - enough to tax any machine!) // (That's 8 Million Blocks - enough to tax any machine!)
var utils = require('./utils/_utils');
var a = []; var a = [];
a.length = 200; a.length = 200;
@ -1494,6 +1548,8 @@ Example
To warn players when night is approaching... To warn players when night is approaching...
var utils = require('./utils/_utils');
utils.at( "19:00", function() { utils.at( "19:00", function() {
utils.foreach( server.onlinePlayers, function(player){ utils.foreach( server.onlinePlayers, function(player){
@ -1502,44 +1558,73 @@ To warn players when night is approaching...
}, self.world); }, self.world);
String class extensions
----------------------- ## The arrows mod adds fancy arrows to the game.
The following chat-formatting methods are added to the javascript String class..
### Usage:
* aqua() /js var arrows = require('./arrows/arrows')
* black()
* blue() * `/js arrows.sign()` turns a targeted sign into a Arrows menu
* bold() * `/js arrows.normal()` sets arrow type to normal.
* brightgreen() * `/js arrows.explosive()` - makes arrows explode.
* darkaqua() * `/js arrows.teleport()` - makes player teleport to where arrow has landed.
* darkblue() * `/js arrows.flourish()` - makes a tree grow where the arrow lands.
* darkgray() * `/js arrows.lightning()` - lightning strikes where the arrow lands.
* darkgreen() * `/js arrows.firework()` - A firework launches where the the arrow lands.
* purple()
* darkpurple() All of the above functions can take an optional player object or name as
* darkred() a parameter. E.g.
* gold()
* gray() `/js arrows.explosive('player23')` makes player23's arrows explosive.
* green()
* italic() Classroom Module
* lightpurple() ================
* indigo() The `classroom` object contains a couple of utility functions for use
* green() in a classroom setting. The goal of these functions is to make it
* red() easier for tutors to facilitate ScriptCraft for use by students in a
* pink() classroom environment. Although granting ScriptCraft access to
* yellow() students on a shared server is potentially risky (Students can
* white() potentially abuse it), it is slighlty less risky than granting
* strike() operator privileges to each student. (Enterprising students will
* random() quickly realise how to grant themselves and others operator privileges
* magic() once they have access to ScriptCraft).
* underline()
* reset() 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
===================================
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
----------
* 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...
var boldGoldText = "Hello World".bold().gold(); /js classroom.allowScripting(true)
self.sendMessage(boldGoldText);
<p style="color:gold;font-weight:bold">Hello World</p> To disallow scripting (and prevent players who join the server from using the commands)...
/js classroom.allowScripting(false)
Only ops users can run the classroom.allowScripting() function - this is so that students
don't try to bar themselves and each other from scripting.
## Minigame: Guess the number
### Example
/js Game_NumberGuess.start()
... Begins a number-guessing game where you must guess the number (between 1 and 10) chosen by the computer.
A basic number-guessing game that uses the Bukkit Conversation API.

6
src/main/java/net/walterhiggins/scriptcraft/ScriptCraftPlugin.java
View file

@ -23,7 +23,7 @@ public class ScriptCraftPlugin extends JavaPlugin implements Listener
// need to look at possibly having context/scope per operator // need to look at possibly having context/scope per operator
//protected Map<CommandSender,ScriptCraftEvaluator> playerContexts = new HashMap<CommandSender,ScriptCraftEvaluator>(); //protected Map<CommandSender,ScriptCraftEvaluator> playerContexts = new HashMap<CommandSender,ScriptCraftEvaluator>();
protected ScriptEngine engine = null; protected ScriptEngine engine = null;
private static final String JS_PLUGINS_DIR = "js-plugins"; private static final String JS_PLUGINS_DIR = "scriptcraft";
/** /**
* Unzips bundled javascript code. * Unzips bundled javascript code.
@ -92,7 +92,7 @@ public class ScriptCraftPlugin extends JavaPlugin implements Listener
FileReader reader = null; FileReader reader = null;
try{ try{
ScriptEngineManager factory = new ScriptEngineManager(); ScriptEngineManager factory = new ScriptEngineManager();
File boot = new File(JS_PLUGINS_DIR + "/core/_scriptcraft.js"); File boot = new File(JS_PLUGINS_DIR + "/lib/scriptcraft.js");
this.engine = factory.getEngineByName("JavaScript"); this.engine = factory.getEngineByName("JavaScript");
this.engine.put("__engine",engine); this.engine.put("__engine",engine);
this.engine.put("__plugin",this); this.engine.put("__plugin",this);
@ -103,7 +103,7 @@ public class ScriptCraftPlugin extends JavaPlugin implements Listener
wph 20130811 Need to disable coffeescript support until issues loading and evaluating it are resolved. wph 20130811 Need to disable coffeescript support until issues loading and evaluating it are resolved.
See issue #92 See issue #92
// Load the CoffeeScript compiler // Load the CoffeeScript compiler
File coffeescript = new File(JS_PLUGINS_DIR + "/core/_coffeescript.js"); File coffeescript = new File(JS_PLUGINS_DIR + "/lib/coffeescript.js");
this.engine.eval(new FileReader(coffeescript)); this.engine.eval(new FileReader(coffeescript));
*/ */