From bb9433a6d342d533642f2ffcc95c1351823acddc Mon Sep 17 00:00:00 2001 From: walterhiggins Date: Tue, 31 Dec 2013 20:12:57 +0000 Subject: [PATCH] Improved documentation of the utils module and fixed bug in signs module due to changes to serialization/deserialization of locations. --- docs/API-Reference.md | 119 +++++++++++++++--- src/main/javascript/modules/signs/menu.js | 8 +- src/main/javascript/modules/utils/utils.js | 138 +++++++++++++++++---- 3 files changed, 221 insertions(+), 44 deletions(-) diff --git a/docs/API-Reference.md b/docs/API-Reference.md index dd83f87..fbbfee7 100644 --- a/docs/API-Reference.md +++ b/docs/API-Reference.md @@ -646,21 +646,11 @@ The following example illustrates how to use http.request to make a request to a ## Utilities Module -Miscellaneous utility functions and classes to help with programming. +The `utils` module is a storehouse for various useful utility +functions which can be used by plugin and module authors. It contains +miscellaneous utility functions and classes to help with programming. - * locationToString(Location) - returns a [bukkit Location][bkloc] object in string form. - - * player(playerName) - returns the Player object for a named player or `self` if no name is provided. - - * 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. - -[bkloc]: http://jd.bukkit.org/dev/apidocs/org/bukkit/Location.html - -### player() function +### utils.player() function The utils.player() function will return a [bukkit Player][bkpl] object with the given name. This function takes a single parameter @@ -670,17 +660,110 @@ String, then it tries to find the player with that name. #### Parameters - * playerName : A String or Player object. If no parameter is provided then player() will try to return the `self` variable . It is strongly recommended to provide a parameter. + * playerName : A String or Player object. If no parameter is provided + then player() will try to return the `self` variable . It is + strongly recommended to provide a parameter. #### Example var utils = require('utils'); - var player = utils.player('walterh'); - player.sendMessage('Got you!'); + var name = 'walterh'; + var player = utils.player(name); + if (player) { + player.sendMessage('Got ' + name); + }else{ + console.log('No player named ' + name); + } [bkpl]: http://jd.bukkit.org/dev/apidocs/org/bukkit/entity/Player.html +[bkloc]: http://jd.bukkit.org/dev/apidocs/org/bukkit/Location.html -### foreach() function +### utils.locationToJSON() function + +utils.locationToJSON() returns a [org.bukkit.Location][bkloc] object in JSON form... + + { world: 'world5', + x: 56.9324, + y: 103.9954, + z: 43.1323, + yaw: 0.0, + pitch: 0.0 + } + +This can be useful if you write a plugin that needs to store location data since bukkit's Location object is a Java object which cannot be serialized to JSON by default. + +#### Parameters + + * location: An object of type [org.bukkit.Location][bkloc] + +#### Returns + +A JSON object in the above form. + +### utils.locationToString() function + +The utils.locationToString() function returns a +[org.bukkit.Location][bkloc] object in string form... + + '{"world":"world5",x:56.9324,y:103.9954,z:43.1323,yaw:0.0,pitch:0.0}' + +... which can be useful if you write a plugin which uses Locations as +keys in a lookup table. + +#### Example + + var utils = require('utils'); + ... + var key = utils.locationToString(player.location); + lookupTable[key] = player.name; + +### utils.locationFromJSON() function + +This function reconstructs an [org.bukkit.Location][bkloc] object from +a JSON representation. This is the counterpart to the +`locationToJSON()` function. It takes a JSON object of the form +returned by locationToJSON() and reconstructs and returns a bukkit +Location object. + +### utils.getPlayerPos() function + +This function returns the player's [Location][bkloc] (x, y, z, pitch +and yaw) for a named player. If the "player" is in fact a +[org.bukkit.command.BlockCommandSender][bkbcs] then the attached +Block's location is returned. + +#### Parameters + + * player : A [org.bukkit.command.CommandSender][bkbcs] (Player or BlockCommandSender) or player name (String). + +#### Returns + +An [org.bukkit.Location][bkloc] object. + +[bkbcs]: http://jd.bukkit.org/dev/apidocs/org/bukkit/command/BlockCommandSender.html +[bksndr]: http://jd.bukkit.org/dev/apidocs/index.html?org/bukkit/command/CommandSender.html +### utils.getMousePos() function + +This function returns a [org.bukkit.Location][bkloc] object (the +x,y,z) of the current block being targeted by the named player. This +is the location of the block the player is looking at (targeting). + +#### Parameters + + * player : The player whose targeted location you wish to get. + +#### Example + +The following code will strike lightning at the location the player is looking at... + + var utils = require('utils'); + var playerName = 'walterh'; + var targetPos = utils.getMousePos(playerName); + if (targetPos){ + targetPos.world.strikeLightning(targetPos); + } + +### 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 diff --git a/src/main/javascript/modules/signs/menu.js b/src/main/javascript/modules/signs/menu.js index 0d08b86..397f25a 100644 --- a/src/main/javascript/modules/signs/menu.js +++ b/src/main/javascript/modules/signs/menu.js @@ -1,4 +1,4 @@ -var _utils = require('utils'); +var utils = require('utils'); var stringExt = require('utils/string-exts'); var _store = {}; /* @@ -78,7 +78,7 @@ signs.menu = function( save = true; if (typeof sign == "undefined"){ - var mouseLoc = _utils.getMousePos(); + var mouseLoc = utils.getMousePos(); if (mouseLoc){ sign = mouseLoc.block.state; }else{ @@ -105,7 +105,7 @@ signs.menu = function( get a unique ID for this particular sign instance */ var signLoc = sign.block.location; - var menuSignSaveData = [""+signLoc.world.name, signLoc.x,signLoc.y,signLoc.z]; + var menuSignSaveData = utils.locationToJSON(signLoc); var menuSignUID = JSON.stringify(menuSignSaveData); /* keep a reference to the update function for use by the event handler @@ -177,7 +177,7 @@ events.on('player.PlayerInteractEvent',function(listener, event) { if (! event.clickedBlock.state instanceof org.bukkit.block.Sign) return; - var evtLocStr = _utils.locationToString(event.clickedBlock.location); + var evtLocStr = utils.locationToString(event.clickedBlock.location); var signUpdater = _updaters[evtLocStr] if (signUpdater) signUpdater(event.player, event.clickedBlock.state); diff --git a/src/main/javascript/modules/utils/utils.js b/src/main/javascript/modules/utils/utils.js index d5c76e8..1e45a3b 100644 --- a/src/main/javascript/modules/utils/utils.js +++ b/src/main/javascript/modules/utils/utils.js @@ -1,23 +1,11 @@ /************************************************************************ ## Utilities Module -Miscellaneous utility functions and classes to help with programming. +The `utils` module is a storehouse for various useful utility +functions which can be used by plugin and module authors. It contains +miscellaneous utility functions and classes to help with programming. - * locationToString(Location) - returns a [bukkit Location][bkloc] object in string form. - - * player(playerName) - returns the Player object for a named player or `self` if no name is provided. - - * 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. - -[bkloc]: http://jd.bukkit.org/dev/apidocs/org/bukkit/Location.html - -***/ -/************************************************************************ -### player() function +### utils.player() function The utils.player() function will return a [bukkit Player][bkpl] object with the given name. This function takes a single parameter @@ -27,15 +15,23 @@ String, then it tries to find the player with that name. #### Parameters - * playerName : A String or Player object. If no parameter is provided then player() will try to return the `self` variable . It is strongly recommended to provide a parameter. + * playerName : A String or Player object. If no parameter is provided + then player() will try to return the `self` variable . It is + strongly recommended to provide a parameter. #### Example var utils = require('utils'); - var player = utils.player('walterh'); - player.sendMessage('Got you!'); + var name = 'walterh'; + var player = utils.player(name); + if (player) { + player.sendMessage('Got ' + name); + }else{ + console.log('No player named ' + name); + } [bkpl]: http://jd.bukkit.org/dev/apidocs/org/bukkit/entity/Player.html +[bkloc]: http://jd.bukkit.org/dev/apidocs/org/bukkit/Location.html ***/ var _player = function ( playerName ) { @@ -52,7 +48,30 @@ var _player = function ( playerName ) { return playerName; // assumes it's a player object } }; +/************************************************************************* +### utils.locationToJSON() function +utils.locationToJSON() returns a [org.bukkit.Location][bkloc] object in JSON form... + + { world: 'world5', + x: 56.9324, + y: 103.9954, + z: 43.1323, + yaw: 0.0, + pitch: 0.0 + } + +This can be useful if you write a plugin that needs to store location data since bukkit's Location object is a Java object which cannot be serialized to JSON by default. + +#### Parameters + + * location: An object of type [org.bukkit.Location][bkloc] + +#### Returns + +A JSON object in the above form. + +***/ var _locationToJSON = function(location){ return { world: ''+location.world.name, @@ -63,14 +82,49 @@ var _locationToJSON = function(location){ pitch: location.pitch }; }; +/************************************************************************* +### utils.locationToString() function + +The utils.locationToString() function returns a +[org.bukkit.Location][bkloc] object in string form... + + '{"world":"world5",x:56.9324,y:103.9954,z:43.1323,yaw:0.0,pitch:0.0}' + +... which can be useful if you write a plugin which uses Locations as +keys in a lookup table. + +#### Example + + var utils = require('utils'); + ... + var key = utils.locationToString(player.location); + lookupTable[key] = player.name; + +***/ exports.locationToString = function(location){ return JSON.stringify(_locationToJSON(location)); }; exports.locationToJSON = _locationToJSON; +/************************************************************************* +### utils.locationFromJSON() function + +This function reconstructs an [org.bukkit.Location][bkloc] object from +a JSON representation. This is the counterpart to the +`locationToJSON()` function. It takes a JSON object of the form +returned by locationToJSON() and reconstructs and returns a bukkit +Location object. + +***/ exports.locationFromJSON = function(json){ - var world = org.bukkit.Bukkit.getWorld(json.world); - return new org.bukkit.Location(world, json.x, json.y , json.z, json.yaw, json.pitch); + if (json.constuctor == Array){ + // for support of legacy format + var world = org.bukkit.Bukkit.getWorld(json[0]); + return new org.bukkit.Location(world, json[1], json[2] , json[3]); + }else{ + var world = org.bukkit.Bukkit.getWorld(json.world); + return new org.bukkit.Location(world, json.x, json.y , json.z, json.yaw, json.pitch); + } }; exports.player = _player; @@ -78,7 +132,25 @@ exports.getPlayerObject = function(player){ console.warn('utils.getPlayerObject() is deprecated. Use utils.player() instead.'); return _player(player); }; +/************************************************************************* +### utils.getPlayerPos() function +This function returns the player's [Location][bkloc] (x, y, z, pitch +and yaw) for a named player. If the "player" is in fact a +[org.bukkit.command.BlockCommandSender][bkbcs] then the attached +Block's location is returned. + +#### Parameters + + * player : A [org.bukkit.command.CommandSender][bkbcs] (Player or BlockCommandSender) or player name (String). + +#### Returns + +An [org.bukkit.Location][bkloc] object. + +[bkbcs]: http://jd.bukkit.org/dev/apidocs/org/bukkit/command/BlockCommandSender.html +[bksndr]: http://jd.bukkit.org/dev/apidocs/index.html?org/bukkit/command/CommandSender.html +***/ exports.getPlayerPos = function( player ) { player = _player(player); if (player){ @@ -90,7 +162,29 @@ exports.getPlayerPos = function( player ) { else return null; }; +/************************************************************************ +### utils.getMousePos() function +This function returns a [org.bukkit.Location][bkloc] object (the +x,y,z) of the current block being targeted by the named player. This +is the location of the block the player is looking at (targeting). + +#### Parameters + + * player : The player whose targeted location you wish to get. + +#### Example + +The following code will strike lightning at the location the player is looking at... + + var utils = require('utils'); + var playerName = 'walterh'; + var targetPos = utils.getMousePos(playerName); + if (targetPos){ + targetPos.world.strikeLightning(targetPos); + } + +***/ exports.getMousePos = function (player) { player = _player(player); @@ -106,7 +200,7 @@ exports.getMousePos = function (player) { return targetedBlock.location; }; /************************************************************************ -### foreach() function +### 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