updated docs/comments

This commit is contained in:
walterhiggins 2013-06-07 19:50:12 +01:00
parent a8ad3e0444
commit 335b8b1bdc
3 changed files with 275 additions and 217 deletions

View file

@ -1,4 +1,4 @@
ScriptCraft API Reference
/************************************************************************
=========================
Walter Higgins
@ -219,7 +219,7 @@ There are a couple of special javascript variables available in ScriptCraft...
* 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)
refresh() function
/*************************************************************************
------------------
The refresh() function will ...
@ -232,83 +232,7 @@ See [issue #69][issue69] for more information.
[issue69]: https://github.com/walterhiggins/ScriptCraft/issues/69
classroom Module
================
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.
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
-------
To allow all players (and any players who connect to the server) to
use the `js` and `jsp` commands...
/js classroom.allowScripting(true)
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.
Drone.spiral_stairs() method
============================
Constructs a spiral staircase with slabs at each corner.
Parameters
----------
* stairBlock - The block to use for stairs, should be one of the following...
- 'oak'
- 'spruce'
- 'birch'
- 'jungle'
- 'cobblestone'
- 'brick'
- 'stone'
- 'nether'
- 'sandstone'
- 'quartz'
* flights - The number of flights of stairs to build.
![Spiral Staircase](img/spiralstair1.png)
Example
-------
To construct a spiral staircase 5 floors high made of oak...
spiral_stairs('oak', 5);
Drone.rainbow() method
======================
Creates a Rainbow.
Parameters
----------
* radius (optional - default:18) - The radius of the rainbow
Example
-------
var d = new Drone();
d.rainbow(30);
![rainbow example](img/rainbowex1.png)
Drone Module
/*********************************************************************
============
The Drone is a convenience class for building. It can be used for...
@ -407,7 +331,7 @@ Parameters
facing. Possible values are 0 (east), 1 (south), 2 (west) or 3 (north)
* world (optional) : The world in which the drone is created.
Drone.box() method
/************************************************************************
==================
the box() method is a convenience method for building things. (For the more performance-oriented method - see cuboid)
@ -478,7 +402,7 @@ Construct a rainbow-colored road 100 blocks long...
![boxa example](img/boxaex1.png)
Drone Movement
/************************************************************************
==============
Drones can move freely in minecraft's 3-D world. You control the
Drone's movement using any of the following methods..
@ -502,12 +426,12 @@ drone.turn() will make the turn face east. If the drone is facing east
then drone.turn(2) will make the drone turn twice so that it is facing
west.
Drone Positional Info
/************************************************************************
=====================
* getLocation() - Returns a Bukkit Location object for the drone
Drone Markers
/************************************************************************
=============
Markers are useful when your Drone has to do a lot of work. You can
set a check-point and return to the check-point using the move()
@ -543,7 +467,7 @@ Example
//
drone.move('town-square');
Drone.prism() method
/************************************************************************
====================
Creates a prism. This is useful for roofs on houses.
@ -566,7 +490,7 @@ Drone.prism0() method
=====================
A variation on `prism` which hollows out the inside of the prism. It uses the same parameters as `prism`.
Drone.cylinder() method
/************************************************************************
=======================
A convenience method for building cylinders. Building begins radius blocks to the right and forward.
@ -598,7 +522,7 @@ To create a hollow cylinder of Iron 7 blocks in radius and 1 block high...
![cylinder0 example](img/cylinder0ex1.png)
Drone.arc() method
/************************************************************************
==================
The arc() method can be used to create 1 or more 90 degree arcs in the horizontal or vertical planes.
This method is called by cylinder() and cylinder0() and the sphere() and sphere0() methods.
@ -644,7 +568,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
[dv]: http://www.minecraftwiki.net/wiki/Data_values
Drone.door() method
/************************************************************************
===================
create a door - if a parameter is supplied an Iron door is created otherwise a wooden door is created.
@ -681,7 +605,7 @@ To create double-doors at the cross-hairs/drone's location...
![double doors](img/door2ex1.png)
Drone.sign() method
/************************************************************************
===================
Signs must use block 63 (stand-alone signs) or 68 (signs on walls)
@ -704,7 +628,7 @@ To create a free-standing sign...
![wall sign](img/signex2.png)
Drone Trees methods
/************************************************************************
===================
* oak()
@ -729,7 +653,7 @@ the `up()` method is called first).
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.
Drone.garden() method
/************************************************************************
=====================
places random flowers and long grass (similar to the effect of placing bonemeal on grass)
@ -747,7 +671,7 @@ To create a garden 10 blocks wide by 5 blocks long...
![garden example](img/gardenex1.png)
Drone.rand() method
/************************************************************************
===================
rand takes either an array (if each blockid has the same chance of occurring)
or an object where each property is a blockid and the value is it's weight (an integer)
@ -764,7 +688,7 @@ to place random blocks stone has a 50% chance of being picked,
regular stone has a 50% chance, mossy stone has a 30% chance and cracked stone has just a 20% chance of being picked.
Copy & Paste using Drone
/************************************************************************
========================
A drone can be used to copy and paste areas of the game world.
@ -800,7 +724,7 @@ point) into memory. the copied area can be referenced using the name
.right(12)
.paste('somethingCool');
Chaining
/************************************************************************
========
All of the Drone methods return a Drone object, which means methods
@ -910,7 +834,7 @@ Used when placing torches so that they face towards the drone.
drone.box( blocks.torch + ':' + Drone.PLAYER_TORCH_FACING[drone.dir]);
Drone.times() Method
/**************************************************************************
====================
The times() method makes building multiple copies of buildings easy. It's possible to create rows or grids of buildings without resorting to `for` or `while` loops.
@ -975,100 +899,7 @@ Another example: This statement creates a row of trees 2 by 3 ...
![times example 1](img/times-trees.png)
Drone.sphere() method
=====================
Creates a sphere.
Parameters
----------
* block - The block the sphere will be made of.
* radius - The radius of the sphere.
Example
-------
To create a sphere of Iron with a radius of 10 blocks...
sphere( blocks.iron, 10);
![sphere example](img/sphereex1.png)
Spheres are time-consuming to make. You *can* make large spheres (250 radius) but expect the
server to be very busy for a couple of minutes while doing so.
Drone.sphere0() method
======================
Creates an empty sphere.
Parameters
----------
* block - The block the sphere will be made of.
* radius - The radius of the sphere.
Example
-------
To create a sphere of Iron with a radius of 10 blocks...
sphere0( blocks.iron, 10);
Spheres are time-consuming to make. You *can* make large spheres (250 radius) but expect the
server to be very busy for a couple of minutes while doing so.
Drone.hemisphere() method
=========================
Creates a hemisphere. Hemispheres can be either north or south.
Parameters
----------
* block - the block the hemisphere will be made of.
* radius - the radius of the hemisphere
* northSouth - whether the hemisphere is 'north' or 'south'
Example
-------
To create a wood 'north' hemisphere with a radius of 7 blocks...
hemisphere(blocks.oak, 7, 'north');
![hemisphere example](img/hemisphereex1.png)
Drone.hemisphere0() method
=========================
Creates a hollow hemisphere. Hemispheres can be either north or south.
Parameters
----------
* block - the block the hemisphere will be made of.
* radius - the radius of the hemisphere
* northSouth - whether the hemisphere is 'north' or 'south'
Example
-------
To create a glass 'north' hemisphere with a radius of 20 blocks...
hemisphere0(blocks.glass, 20, 'north');
![hemisphere example](img/hemisphereex2.png)
Blocks Module
=============
You hate having to lookup [Data Values][dv] when you use ScriptCraft's Drone() functions. So do I.
So I created this blocks object which is a helper object for use in construction.
Examples
--------
box( blocks.oak ); // creates a single oak wood block
box( blocks.sand, 3, 2, 1 ); // creates a block of sand 3 wide x 2 high x 1 long
box( blocks.wool.green, 2 ); // creates a block of green wool 2 blocks wide
In addition, each of the wool colors is also available as a block property so you can use either
`blocks.wool.green` or the more concise `blocks.green`. There's also a convenience array `blocks.rainbow` which is an array of the 7 colors of the rainbow (or closest approximations).
Drone.blocktype() method
/************************************************************************
========================
Creates the text out of blocks. Useful for large-scale in-game signs.
@ -1089,7 +920,186 @@ To create a 2-line high message using glowstone...
[imgbt1]: img/blocktype1.png
events Module
/************************************************************************
=============
You hate having to lookup [Data Values][dv] when you use ScriptCraft's Drone() functions. So do I.
So I created this blocks object which is a helper object for use in construction.
Examples
--------
box( blocks.oak ); // creates a single oak wood block
box( blocks.sand, 3, 2, 1 ); // creates a block of sand 3 wide x 2 high x 1 long
box( blocks.wool.green, 2 ); // creates a block of green wool 2 blocks wide
In addition, each of the wool colors is also available as a block property so you can use either
`blocks.wool.green` or the more concise `blocks.green`. There's also a convenience array `blocks.rainbow` which is an array of the 7 colors of the rainbow (or closest approximations).
/************************************************************************
=====================
Creates a sphere.
Parameters
----------
* block - The block the sphere will be made of.
* radius - The radius of the sphere.
Example
-------
To create a sphere of Iron with a radius of 10 blocks...
sphere( blocks.iron, 10);
![sphere example](img/sphereex1.png)
Spheres are time-consuming to make. You *can* make large spheres (250 radius) but expect the
server to be very busy for a couple of minutes while doing so.
/************************************************************************
======================
Creates an empty sphere.
Parameters
----------
* block - The block the sphere will be made of.
* radius - The radius of the sphere.
Example
-------
To create a sphere of Iron with a radius of 10 blocks...
sphere0( blocks.iron, 10);
Spheres are time-consuming to make. You *can* make large spheres (250 radius) but expect the
server to be very busy for a couple of minutes while doing so.
/************************************************************************
=========================
Creates a hemisphere. Hemispheres can be either north or south.
Parameters
----------
* block - the block the hemisphere will be made of.
* radius - the radius of the hemisphere
* northSouth - whether the hemisphere is 'north' or 'south'
Example
-------
To create a wood 'north' hemisphere with a radius of 7 blocks...
hemisphere(blocks.oak, 7, 'north');
![hemisphere example](img/hemisphereex1.png)
/************************************************************************
=========================
Creates a hollow hemisphere. Hemispheres can be either north or south.
Parameters
----------
* block - the block the hemisphere will be made of.
* radius - the radius of the hemisphere
* northSouth - whether the hemisphere is 'north' or 'south'
Example
-------
To create a glass 'north' hemisphere with a radius of 20 blocks...
hemisphere0(blocks.glass, 20, 'north');
![hemisphere example](img/hemisphereex2.png)
/************************************************************************
======================
Creates a Rainbow.
Parameters
----------
* radius (optional - default:18) - The radius of the rainbow
Example
-------
var d = new Drone();
d.rainbow(30);
![rainbow example](img/rainbowex1.png)
/************************************************************************
============================
Constructs a spiral staircase with slabs at each corner.
Parameters
----------
* stairBlock - The block to use for stairs, should be one of the following...
- 'oak'
- 'spruce'
- 'birch'
- 'jungle'
- 'cobblestone'
- 'brick'
- 'stone'
- 'nether'
- 'sandstone'
- 'quartz'
* flights - The number of flights of stairs to build.
![Spiral Staircase](img/spiralstair1.png)
Example
-------
To construct a spiral staircase 5 floors high made of oak...
spiral_stairs('oak', 5);
/************************************************************************
================
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
(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
-------
To allow all players (and any players who connect to the server) to
use the `js` and `jsp` commands...
/js classroom.allowScripting(true)
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.
/************************************************************************
=============
The Events module provides a thin wrapper around Bukkit's
Event-handling API. Bukkit's Events API makes use of Java Annotations
@ -1156,7 +1166,7 @@ To unregister a listener *outside* of the listener function...
[buk2]: http://wiki.bukkit.org/Event_API_Reference
[buk]: http://jd.bukkit.org/dev/apidocs/index.html?org/bukkit/event/Event.html
http.request() function
/*************************************************************************
====================
The http.request() function will fetch a web address asynchronously (on a
separate thread)and pass the URL's response to a callback function
@ -1195,7 +1205,7 @@ The following example illustrates how to use http.request to make a request to a
var jsObj = eval("(" + responseBody + ")");
});
Utilities Module
/************************************************************************
================
Miscellaneous utility functions and classes to help with programming.
@ -1204,7 +1214,7 @@ Miscellaneous utility functions and classes to help with programming.
* getPlayerObject(playerName) - returns the Player object for a named
player or `self` if no name is provided.
utils.foreach() function
/************************************************************************
========================
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
@ -1278,7 +1288,7 @@ without hogging CPU usage...
};
foreach (a, processItem, null, 10, onDone);
utils.nicely() function
/************************************************************************
=======================
The utils.nicely() function is for performing processing using the
[org.bukkit.scheduler][sched] package/API. utils.nicely() lets you
@ -1302,7 +1312,7 @@ Example
-------
See the source code to utils.foreach for an example of how utils.nicely is used.
String class extensions
/************************************************************************
-----------------------
The following chat-formatting methods are added to the javascript String class..

View file

@ -3,6 +3,12 @@
*/
args = args.slice(1);
var dir = args[0];
var foreach = function(array, func){
for (var i =0; i < array.length; i++){
func(array[i],i,array);
}
};
importPackage(java.io);
/*
find - a (very) basic implementation of the unix command line tool.
@ -10,23 +16,53 @@ importPackage(java.io);
var find = function(dir,store,re)
{
var files = dir.listFiles();
for (var i = 0;i < files.length; i++){
var file = new File(files[i]);
foreach (files, function(filename){
filename = "" + filename;
var file = new File(filename);
if (file.isDirectory()) {
find(file,store,re);
} else {
if (typeof re == "undefined")
store.push(files[i]);
else if ((""+files[i]).match(re))
store.push(files[i]);
}
store.push(filename);
else if (filename.match(re))
store.push(filename);
}
});
};
/*
the main module file for a given directory
(assuming the main module is in a file with the same name as the parent
directory) - e.g. drone/drone.js
*/
var sorter = function( precedence ){
return function(a,b)
{
// convert from Java string to JS string
a = "" + a;
b = "" + b;
var aparts = a.split(/\//);
var bparts = b.split(/\//);
var adir = aparts.slice(3,aparts.length-1).join("/");
var afile = aparts[aparts.length-1];
var bdir = bparts.slice(3,bparts.length-1).join("/");
var bfile = bparts[bparts.length-1];
for (var i = 0;i < precedence.length; i++){
var re = precedence[i];
if (a.match(re))
return -1;
if (b.match(re))
return 1;
}
if(adir<bdir) return -1;
if(adir>bdir) return 1;
afile = afile.replace(/\.js$/,"");
if (afile == adir)
return -1;
else
return 1;
};
};
var sortByModule = function(a,b)
{
var aparts = (""+a).split(/\//);
@ -49,25 +85,29 @@ var sortByModule = function(a,b)
var store = [];
find(new File(dir),store,/\/[a-zA-Z0-9_\-]+\.js$/);
store.sort(sortByModule);
store.sort(sorter([
/_scriptcraft\.js$/,
/core/,
/drone\.js/,
/drone/
]));
var contents = [];
for (var i =0; i < store.length; i++)
{
var br = new BufferedReader(new FileReader(store[i]));
foreach(store, function(filename){
var br = new BufferedReader(new FileReader(filename));
var line ;
while ( (line = br.readLine()) != null){
contents.push(line);
}
br.close();
}
});
var len = contents.length;
var writeComment = false;
var startComment = /^\/\*{10}/;
var endComment = /^\*{3}\//;
for (var i = 0; i < len; i++)
{
for (var i = 0;i < contents.length; i++){
var line = contents[i];
if (line.match(startComment)){
writeComment = true;
@ -77,6 +117,7 @@ for (var i = 0; i < len; i++)
writeComment = false;
}
if (writeComment){
println(contents[i]);
println(line);
}
}

View file

@ -1,13 +1,20 @@
/************************************************************************
classroom Module
Classroom Module
================
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.
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
(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
@ -46,7 +53,6 @@ ready(function(){
*/
if (!self.isOp())
return;
if (canScript){
utils.foreach( server.onlinePlayers, function (player) {
player.addAttachment(__plugin, "scriptcraft.*", true);
@ -65,7 +71,8 @@ ready(function(){
};
events.on("player.PlayerLoginEvent", function(listener, event) {
var player = event.player;
if (classroom.canScript)
if (classroom.canScript){
player.addAttachment(__plugin, "scriptcraft.*", true);
}
}, "HIGHEST");
});