Added documentation for the Signs module and changed Signs examples so that a valid sign must be provided to the function returned by signs.menu().

This commit is contained in:
walterhiggins 2014-01-05 15:20:29 +00:00
parent 73fdf04bc2
commit 8c3dc92c2a
7 changed files with 259 additions and 21 deletions

View file

@ -53,6 +53,9 @@ Walter Higgins
* [http.request() function](#httprequest-function) * [http.request() function](#httprequest-function)
* [Parameters](#parameters) * [Parameters](#parameters)
* [Example](#example) * [Example](#example)
* [Signs Module](#signs-module)
* [signs.menu() function](#signsmenu-function)
* [signs.getTargetedBy() function](#signsgettargetedby-function)
* [Utilities Module](#utilities-module) * [Utilities Module](#utilities-module)
* [utils.player() function](#utilsplayer-function) * [utils.player() function](#utilsplayer-function)
* [utils.locationToJSON() function](#utilslocationtojson-function) * [utils.locationToJSON() function](#utilslocationtojson-function)
@ -821,6 +824,95 @@ The following example illustrates how to use http.request to make a request to a
var jsObj = eval("(" + responseBody + ")"); var jsObj = eval("(" + responseBody + ")");
}); });
## Signs Module
The Signs Module can be used by plugin authors to create interactive
signs - that is - signs which display a list of choices which can be
changed by interacting (right-clicking) with the sign.
### signs.menu() function
This function is used to construct a new interactive menu on top of an
existing sign in the game world.
#### Parameters
* Label : A string which will be displayed in the topmost line of the
sign. This label is not interactive.
* options : An array of strings which can be selected on the sign by
right-clicking/interacting.
* callback : A function which will be called whenever a player
interacts (changes selection) on a sign. This callback in turn
takes as its parameter, an object with the following properties...
* player : The player who interacted with the sign.
* sign : The [org.bukkit.block.Sign][buksign] which the player interacted with.
* text : The text for the currently selected option on the sign.
* number : The index of the currently selected option on the sign.
* selectedIndex : optional: A number (starting at 0) indicating which
of the options should be selected by default. 0 is the default.
#### Returns
This function does not itself do much. It does however return a
function which when invoked with a given
[org.bukkit.block.Sign][buksign] object, will convert that sign into
an interactive sign.
#### Example: Create a sign which changes the time of day.
##### plugins/signs/time-of-day.js
var utils = require('utils'),
signs = require('signs');
var onTimeChoice = function(event){
var selectedIndex = event.number;
// convert to Minecraft time 0 = Dawn, 6000 = midday, 12000 = dusk, 18000 = midnight
var time = selectedIndex * 6000;
event.player.location.world.setTime(time);
};
// signs.menu returns a function which can be called for one or more signs in the game.
var convertToTimeMenu = signs.menu('Time of Day',
['Dawn', 'Midday', 'Dusk', 'Midnight'],
onTimeChoice);
exports.time_sign = function( player ){
var sign = signs.getTargetedBy(player);
if (!sign){
throw new Error('You must look at a sign');
}
convertToTimeMenu(sign);
};
To use the above function at the in-game prompt, look at an existing
sign and type...
/js time_sign(self);
... and the sign you're looking at will become an interactive sign
which changes the time each time you interact (right-click) with it.
### signs.getTargetedBy() function
This function takes a [org.bukkit.entity.LivingEntity][bukle] as a
parameter and returns a [org.bukkit.block.Sign][buksign] object which
the entity has targeted. It is a utility function for use by plugin authors.
#### Example
var signs = require('signs'),
utils = require('utils');
var player = utils.player('tom1234');
var sign = signs.getTargetedBy( player );
if (!sign){
player.sendMessage('Not looking at a sign');
}
[buksign]: http://jd.bukkit.org/dev/apidocs/org/bukkit/block/Sign.html
String class extensions String class extensions
----------------------- -----------------------
The following chat-formatting methods are added to the javascript String class.. The following chat-formatting methods are added to the javascript String class..

View file

@ -1,5 +1,10 @@
/************************************************************************* /*************************************************************************
## http.request() function ## Http Module
For handling http requests. Not to be confused with the more robust
and functional 'http' module bundled with Node.js.
### http.request() function
The http.request() function will fetch a web address asynchronously (on a The http.request() function will fetch a web address asynchronously (on a
separate thread)and pass the URL's response to a callback function separate thread)and pass the URL's response to a callback function
@ -7,7 +12,7 @@ which will be executed synchronously (on the main thread). In this
way, http.request() can be used to fetch web content without blocking the way, http.request() can be used to fetch web content without blocking the
main thread of execution. main thread of execution.
### Parameters #### Parameters
* request: The request details either a plain URL e.g. "http://scriptcraft.js/sample.json" or an object with the following properties... * request: The request details either a plain URL e.g. "http://scriptcraft.js/sample.json" or an object with the following properties...
@ -19,7 +24,7 @@ main thread of execution.
- responseCode: The numeric response code from the server. If the server did not respond with 200 OK then the response parameter will be undefined. - responseCode: The numeric response code from the server. If the server did not respond with 200 OK then the response parameter will be undefined.
- response: A string (if the response is of type text) or object containing the HTTP response body. - response: A string (if the response is of type text) or object containing the HTTP response body.
### Example #### 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...

View file

@ -48,12 +48,12 @@ signs.menu = function(
/* String */ label, /* String */ label,
/* Array */ options, /* Array */ options,
/* Function */ callback, /* Function */ callback,
/* Number */ selectedIndex) /* Number */ selectedIndex
)
{ {
if (typeof selectedIndex == "undefined") if (typeof selectedIndex == "undefined")
selectedIndex = 0; selectedIndex = 0;
// //
// variables common to all instances of this menu can go here // variables common to all instances of this menu can go here
// //
@ -76,15 +76,24 @@ signs.menu = function(
{ {
if (typeof save == "undefined") if (typeof save == "undefined")
save = true; save = true;
/*
@deprecated start
all calls should explicitly provide a [org.bukkit.block.Sign][buksign] parameter.
*/
if (typeof sign == "undefined"){ if (typeof sign == "undefined"){
var mouseLoc = utils.getMousePos(); var mouseLoc = utils.getMousePos();
if (mouseLoc){ if (mouseLoc){
sign = mouseLoc.block.state; sign = mouseLoc.block.state;
if (!(sign && sign.setLine)){
throw new Error("You must first provide a sign!");
}
}else{ }else{
throw new Exception("You must provide a sign!"); throw new Error("You must first provide a sign!");
} }
} }
/*
@deprecated end
*/
// //
// per-sign variables go here // per-sign variables go here
// //

View file

@ -1,4 +1,4 @@
{ {
name: 'signs', name: 'signs',
main: './menu.js' main: './signs.js'
} }

View file

@ -0,0 +1,107 @@
/************************************************************************
## Signs Module
The Signs Module can be used by plugin authors to create interactive
signs - that is - signs which display a list of choices which can be
changed by interacting (right-clicking) with the sign.
### signs.menu() function
This function is used to construct a new interactive menu on top of an
existing sign in the game world.
#### Parameters
* Label : A string which will be displayed in the topmost line of the
sign. This label is not interactive.
* options : An array of strings which can be selected on the sign by
right-clicking/interacting.
* callback : A function which will be called whenever a player
interacts (changes selection) on a sign. This callback in turn
takes as its parameter, an object with the following properties...
* player : The player who interacted with the sign.
* sign : The [org.bukkit.block.Sign][buksign] which the player interacted with.
* text : The text for the currently selected option on the sign.
* number : The index of the currently selected option on the sign.
* selectedIndex : optional: A number (starting at 0) indicating which
of the options should be selected by default. 0 is the default.
#### Returns
This function does not itself do much. It does however return a
function which when invoked with a given
[org.bukkit.block.Sign][buksign] object, will convert that sign into
an interactive sign.
#### Example: Create a sign which changes the time of day.
##### plugins/signs/time-of-day.js
var utils = require('utils'),
signs = require('signs');
var onTimeChoice = function(event){
var selectedIndex = event.number;
// convert to Minecraft time 0 = Dawn, 6000 = midday, 12000 = dusk, 18000 = midnight
var time = selectedIndex * 6000;
event.player.location.world.setTime(time);
};
// signs.menu returns a function which can be called for one or more signs in the game.
var convertToTimeMenu = signs.menu('Time of Day',
['Dawn', 'Midday', 'Dusk', 'Midnight'],
onTimeChoice);
exports.time_sign = function( player ){
var sign = signs.getTargetedBy(player);
if (!sign){
throw new Error('You must look at a sign');
}
convertToTimeMenu(sign);
};
To use the above function at the in-game prompt, look at an existing
sign and type...
/js time_sign(self);
... and the sign you're looking at will become an interactive sign
which changes the time each time you interact (right-click) with it.
### signs.getTargetedBy() function
This function takes a [org.bukkit.entity.LivingEntity][bukle] as a
parameter and returns a [org.bukkit.block.Sign][buksign] object which
the entity has targeted. It is a utility function for use by plugin authors.
#### Example
var signs = require('signs'),
utils = require('utils');
var player = utils.player('tom1234');
var sign = signs.getTargetedBy( player );
if (!sign){
player.sendMessage('Not looking at a sign');
}
[buksign]: http://jd.bukkit.org/dev/apidocs/org/bukkit/block/Sign.html
***/
var utils = require('utils');
var menu = require('./menu');
// include all menu exports
for (var i in menu){
exports[i] = menu[i];
}
exports.getTargetedBy = function( livingEntity ){
var location = utils.getMousePos( livingEntity );
if (!location)
return null;
var state = location.block.state;
if (!(state || state.setLine))
return null;
return state;
};

View file

@ -91,9 +91,19 @@ for (var type in _types)
var _onMenuChoice = function(event){ var _onMenuChoice = function(event){
arrows.store.players[event.player.name] = event.number; arrows.store.players[event.player.name] = event.number;
}; };
arrows.sign = signs.menu("Arrow", var convertToArrowSign = signs.menu(
"Arrow",
["Normal","Explosive","Teleport","Flourish","Lightning","Firework"], ["Normal","Explosive","Teleport","Flourish","Lightning","Firework"],
_onMenuChoice ); _onMenuChoice);
arrows.sign = function(cmdSender)
{
var sign = signs.getTargetedBy(cmdSender);
if (!sign){
throw new Error('You must first look at a sign!');
}
return convertToArrowSign(sign,true);
};
/* /*
event handler called when a projectile hits something event handler called when a projectile hits something

View file

@ -10,12 +10,25 @@ var signs = require('signs');
// //
// /js signs.menu_time() // /js signs.menu_time()
// //
exports.signs = {
menu_food: signs.menu("Dinner", var onDinnerChoice = function(event){
["Lamb","Pork","Chicken","Duck","Beef"],
function(event){
event.player.sendMessage("You chose " + event.text); event.player.sendMessage("You chose " + event.text);
}), };
var convertToDinnerMenu = signs.menu("Dinner", ["Lamb","Pork","Chicken","Duck","Beef"], onDinnerChoice);
var onTimeChoice = function(event){
event.player.location.world.setTime( event.number * 6000 );
};
var convertToTimeMenu = signs.menu("Time", ["Dawn","Midday","Dusk","Midnight"], onTimeChoice);
exports.signs = {
menu_food: function(cmdSender){
var sign = signs.getTargetedBy(cmdSender);
if (!sign){
throw new Error('You must look at an existing sign');
}
convertToDinnerMenu(sign);
},
// //
// This is an example sign that displays a menu of times of day // This is an example sign that displays a menu of times of day
// interacting with the sign will change the time of day accordingly. // interacting with the sign will change the time of day accordingly.
@ -25,10 +38,12 @@ exports.signs = {
// /js var signExamples = require('./signs/examples'); // /js var signExamples = require('./signs/examples');
// /js signExamples.timeOfDay() // /js signExamples.timeOfDay()
// //
menu_time: signs.menu("Time", menu_time: function(cmdSender){
["Dawn","Midday","Dusk","Midnight"], var sign = signs.getTargetedBy(cmdSender);
function(event){ if (!sign){
event.player.location.world.setTime( event.number * 6000 ); throw new Error('You must look at an existing sign');
}) }
convertToTimeMenu(sign);
}
} }