added documentation for the bukkit object.

docs/API-Reference.md

@@ -43,6 +43,7 @@ Walter Higgins
    * [module name resolution](#module-name-resolution)
  * [events Module](#events-module)
    * [events.on() static method](#eventson-static-method)
+   * [bukkit](#bukkit)
  * [console global variable](#console-global-variable)
    * [Example](#example)
    * [Using string substitutions](#using-string-substitutions)
@@ -867,6 +868,65 @@ events.on( org.bukkit.event.block.BlockBreakEvent, function( evt ) {
 [buk2]: http://wiki.bukkit.org/Event_API_Reference
 [buk]: http://jd.bukkit.org/dev/apidocs/index.html?org/bukkit/event/Event.html
 
+
+### bukkit
+
+The bukkit global variable provides short names for commonly used Bukkit
+Java classes and Enums. It also provides some helper functions for getting
+players, player names and worlds.
+
+#### bukkit.stat and bukkit.stats
+
+This is a short name for the [org.bukkit.Statistic](http://jd.bukkit.org/rb/apidocs/org/bukkit/Statistic.html) Enum. 
+
+##### Usage
+
+    var jumpStat = bukkit.stat.JUMP; // var jumpStat = org.bukkit.Statistic.JUMP
+
+#### bukkit.material
+
+This is a short name for the [org.bukkit.Material](http://jd.bukkit.org/rb/apidocs/org/bukkit/Material.html) Enum. 
+
+##### Usage
+    
+    var apple = bukkit.material.APPLE;
+
+#### bukkit.art
+
+This is a short name for the [org.bukkit.Art](http://jd.bukkit.org/rb/apidocs/org/bukkit/Art.html) Enum. 
+
+##### Usage
+    
+    var sunsetArt = bukkit.art.SUNSET;
+
+#### bukkit.mode
+
+This is a short name for the [org.bukkit.GameMode](http://jd.bukkit.org/rb/apidocs/org/bukkit/GameMode.html) Enum. 
+
+##### Usage
+    
+    var creative = bukkit.mode.CREATIVE;
+
+#### bukkit.sound
+
+This is a short name for the [org.bukkit.Sound](http://jd.bukkit.org/rb/apidocs/org/bukkit/Sound.html) Enum. 
+
+##### Usage
+    
+    var oink = bukkit.sound.PIG_IDLE;
+
+#### bukkit.players() function
+
+This function returns a javascript array of all online players on the server.
+
+#### bukkit.playerNames() function
+
+This function returns a javascript array of player names (as javascript strings)
+
+#### bukkit.worlds() function
+
+This function returns a javascript array of all worlds on the server.
+
 ## console global variable
 
 ScriptCraft provides a `console` global variable with the followng methods...
@@ -2491,8 +2551,8 @@ a simpler way to play sounds. All of the org.bukkit.Sound Enum values are attach
 ### Usage:
 
     var sounds = require('sounds');
-    sounds.play( org.bukkit.Sound.VILLAGER_NO , self, 1, 0); // plays VILLAGER_NO sound at full volume and medium pitch
-    sounds.play( org.bukkit.Sound.VILLAGER_NO , self );       // same as previous statement
+    sounds.play( bukkit.sound.VILLAGER_NO , self, 1, 0); // plays VILLAGER_NO sound at full volume and medium pitch
+    sounds.play( bukkit.sound.VILLAGER_NO , self );       // same as previous statement
 
 The play() function takes either a Location object or any object which has a location.
 The volume parameter is in the range 0 to 1 and the pitch parameter is in the range 0 to 4.    

src/main/js/lib/bukkit.js

@@ -1,3 +1,64 @@
+/************************************************************************
+
+### bukkit
+
+The bukkit global variable provides short names for commonly used Bukkit
+Java classes and Enums. It also provides some helper functions for getting
+players, player names and worlds.
+
+#### bukkit.stat and bukkit.stats
+
+This is a short name for the [org.bukkit.Statistic](http://jd.bukkit.org/rb/apidocs/org/bukkit/Statistic.html) Enum. 
+
+##### Usage
+
+    var jumpStat = bukkit.stat.JUMP; // var jumpStat = org.bukkit.Statistic.JUMP
+
+#### bukkit.material
+
+This is a short name for the [org.bukkit.Material](http://jd.bukkit.org/rb/apidocs/org/bukkit/Material.html) Enum. 
+
+##### Usage
+    
+    var apple = bukkit.material.APPLE;
+
+#### bukkit.art
+
+This is a short name for the [org.bukkit.Art](http://jd.bukkit.org/rb/apidocs/org/bukkit/Art.html) Enum. 
+
+##### Usage
+    
+    var sunsetArt = bukkit.art.SUNSET;
+
+#### bukkit.mode
+
+This is a short name for the [org.bukkit.GameMode](http://jd.bukkit.org/rb/apidocs/org/bukkit/GameMode.html) Enum. 
+
+##### Usage
+    
+    var creative = bukkit.mode.CREATIVE;
+
+#### bukkit.sound
+
+This is a short name for the [org.bukkit.Sound](http://jd.bukkit.org/rb/apidocs/org/bukkit/Sound.html) Enum. 
+
+##### Usage
+    
+    var oink = bukkit.sound.PIG_IDLE;
+
+#### bukkit.players() function
+
+This function returns a javascript array of all online players on the server.
+
+#### bukkit.playerNames() function
+
+This function returns a javascript array of player names (as javascript strings)
+
+#### bukkit.worlds() function
+
+This function returns a javascript array of all worlds on the server.
+
+***/
 var bukkit = {
   stat: org.bukkit.Statistic,
   stats: org.bukkit.Statistic,

src/main/js/modules/items.js

@@ -1,13 +1,12 @@
-var bkItemStack = org.bukkit.inventory.ItemStack,
-  bkMaterial = org.bukkit.Material;
+var bkItemStack = org.bukkit.inventory.ItemStack;
 
 var items =   function( material, amount ) {
   material = material.toUpperCase();
-  return new bkItemStack(bkMaterial[material],amount);
+  return new bkItemStack(bukkit.material[material],amount);
 };
 module.exports = items;
 
-var materials = bkMaterial.values();
+var materials = bukkit.material.values();
 
 for (var i = 0;i < materials.length; i++ ){
   var name = (''+materials[i].name()).toLowerCase();

src/main/js/modules/sounds.js

@@ -1,8 +1,7 @@
-var bkSound = org.bukkit.Sound,
-  bkLocation = org.bukkit.Location,
+var bkLocation = org.bukkit.Location,
   i = 0,
   foreach = require('utils').foreach,
-  allSounds = bkSound.values(),
+  allSounds = bukkit.sound.values(),
   len = allSounds.length,
   sound,
   soundName;
@@ -47,8 +46,8 @@ a simpler way to play sounds. All of the org.bukkit.Sound Enum values are attach
 ### Usage:
 
     var sounds = require('sounds');
-    sounds.play( org.bukkit.Sound.VILLAGER_NO , self, 1, 0); // plays VILLAGER_NO sound at full volume and medium pitch
-    sounds.play( org.bukkit.Sound.VILLAGER_NO , self );       // same as previous statement
+    sounds.play( bukkit.sound.VILLAGER_NO , self, 1, 0); // plays VILLAGER_NO sound at full volume and medium pitch
+    sounds.play( bukkit.sound.VILLAGER_NO , self );       // same as previous statement
 
 The play() function takes either a Location object or any object which has a location.
 The volume parameter is in the range 0 to 1 and the pitch parameter is in the range 0 to 4.    

src/main/js/plugins/examples/example-7-hello-events.js

@@ -93,7 +93,7 @@ Update: Since version 2.0.8 the above code can be replaced by the more succinct:
     });
     
 ***/
-events.on( 'player.PlayerJoinEvent', function( event ) {
+events.playerJoin( function( event ) {
   if ( event.player.op ) {
     event.player.sendMessage( 'Welcome to ' + __plugin );
   }

src/main/js/plugins/minigames/cow-clicker.js

@@ -44,7 +44,6 @@ your own mini-game...
 var store = {},
   bkBukkit = org.bukkit.Bukkit,
   bkCow = org.bukkit.entity.Cow,
-  bkSound = org.bukkit.Sound,
   bkOfflinePlayer = org.bukkit.OfflinePlayer,
   scoreboardConfig = { 
     cowclicker: {
@@ -71,9 +70,9 @@ var _onPlayerInteract = function( event ) {
     scoreboard.update( 'cowclicker', player, store[ player.name ].score );
     
     bkBukkit.dispatchCommand( player, 'me clicked a cow!' );
-    sound( bkSound.CLICK, 1, 1 );
+    sound( bukkit.sound.CLICK, 1, 1 );
     setTimeout( function( ) {
-      sound( bkSound.COW_HURT, 10, 0.85 ) ;
+      sound( bukkit.sound.COW_HURT, 10, 0.85 ) ;
     }, 200 );
   }
 };