2014-01-02 19:46:46 +01:00
|
|
|
'use strict';
|
2013-02-10 14:42:32 +01:00
|
|
|
/************************************************************************
|
2013-12-28 09:44:40 +01:00
|
|
|
## events Module
|
|
|
|
|
2013-02-10 14:42:32 +01:00
|
|
|
The Events module provides a thin wrapper around Bukkit's
|
|
|
|
Event-handling API. Bukkit's Events API makes use of Java Annotations
|
|
|
|
which are not available in Javascript, so this module provides a
|
|
|
|
simple way to listen to minecraft events in javascript.
|
|
|
|
|
2013-12-28 09:44:40 +01:00
|
|
|
### events.on() static method
|
|
|
|
|
2013-02-10 14:42:32 +01:00
|
|
|
This method is used to register event listeners.
|
|
|
|
|
2013-12-28 09:44:40 +01:00
|
|
|
#### Parameters
|
|
|
|
|
2013-02-10 14:42:32 +01:00
|
|
|
|
|
|
|
* eventName - A string or java class. If a string is supplied it must
|
|
|
|
be part of the Bukkit event class name. See [Bukkit API][buk] for
|
|
|
|
details of the many bukkit event types. When a string is supplied
|
|
|
|
there is no need to provide the full class name - you should omit
|
|
|
|
the 'org.bukkit.event' prefix. e.g. if the string
|
|
|
|
"block.BlockBreakEvent" is supplied then it's converted to the
|
|
|
|
org.bukkit.event.block.BlockBreakEvent class .
|
|
|
|
|
|
|
|
If a java class is provided (say in the case where you've defined
|
|
|
|
your own custom event) then provide the full class name (without
|
|
|
|
enclosing quotes).
|
|
|
|
|
|
|
|
* callback - A function which will be called whenever the event
|
2014-03-15 19:06:23 +01:00
|
|
|
fires. The callback should take a single parameter, event (the event fired).
|
2013-02-10 14:42:32 +01:00
|
|
|
|
|
|
|
* priority (optional - default: "HIGHEST") - The priority the
|
|
|
|
listener/callback takes over other listeners to the same
|
|
|
|
event. Possible values are "HIGH", "HIGHEST", "LOW", "LOWEST",
|
|
|
|
"NORMAL", "MONITOR". For an explanation of what the different
|
|
|
|
priorities mean refer to bukkit's [Event API Reference][buk2].
|
|
|
|
|
2013-12-28 09:44:40 +01:00
|
|
|
#### Returns
|
|
|
|
|
2014-03-15 19:06:23 +01:00
|
|
|
An object which can be used to unregister the listener.
|
2013-02-10 14:42:32 +01:00
|
|
|
|
2013-12-28 09:44:40 +01:00
|
|
|
#### Example:
|
2013-02-10 14:42:32 +01:00
|
|
|
|
2013-12-28 09:44:40 +01:00
|
|
|
The following code will print a message on screen every time a block is broken in the game
|
2013-12-24 01:16:07 +01:00
|
|
|
|
2014-02-04 22:49:12 +01:00
|
|
|
```javascript
|
2014-03-15 19:06:23 +01:00
|
|
|
events.on( 'block.BlockBreakEvent', function( evt ) {
|
2014-02-04 22:49:12 +01:00
|
|
|
evt.player.sendMessage( evt.player.name + ' broke a block!');
|
|
|
|
} );
|
|
|
|
```
|
2013-02-10 14:42:32 +01:00
|
|
|
|
|
|
|
To handle an event only once and unregister from further events...
|
2014-02-04 22:49:12 +01:00
|
|
|
|
|
|
|
```javascript
|
2014-03-15 19:06:23 +01:00
|
|
|
events.on( 'block.BlockBreakEvent', function( evt ) {
|
2014-02-04 22:49:12 +01:00
|
|
|
evt.player.sendMessage( evt.player.name + ' broke a block!');
|
2014-03-15 19:06:23 +01:00
|
|
|
this.unregister();
|
2014-02-04 22:49:12 +01:00
|
|
|
} );
|
2013-02-10 14:42:32 +01:00
|
|
|
|
2014-03-15 19:06:23 +01:00
|
|
|
The `this` keyword when used inside the callback function refers to
|
|
|
|
the Listener object created by ScriptCraft. It has a single method
|
|
|
|
`unregister()` which can be used to stop listening. This is the same
|
|
|
|
object which is returned by the `events.on()` function.
|
|
|
|
|
2013-02-10 14:42:32 +01:00
|
|
|
To unregister a listener *outside* of the listener function...
|
|
|
|
|
2014-02-04 22:49:12 +01:00
|
|
|
```javascript
|
2014-03-15 19:06:23 +01:00
|
|
|
var myBlockBreakListener = events.on( 'block.BlockBreakEvent', function( evt ) { ... } );
|
2014-02-04 22:49:12 +01:00
|
|
|
...
|
2014-03-15 19:06:23 +01:00
|
|
|
myBlockBreakListener.unregister();
|
2014-02-04 22:49:12 +01:00
|
|
|
```
|
2013-02-10 14:42:32 +01:00
|
|
|
|
2013-12-28 09:44:40 +01:00
|
|
|
To listen for events using a full class name as the `eventName` parameter...
|
|
|
|
|
2014-02-04 22:49:12 +01:00
|
|
|
```javascript
|
2014-03-15 19:06:23 +01:00
|
|
|
events.on( org.bukkit.event.block.BlockBreakEvent, function( evt ) {
|
2014-02-04 22:49:12 +01:00
|
|
|
evt.player.sendMessage( evt.player.name + ' broke a block!');
|
|
|
|
} );
|
|
|
|
```
|
2013-12-28 09:44:40 +01:00
|
|
|
|
2013-02-10 14:42:32 +01:00
|
|
|
[buk2]: http://wiki.bukkit.org/Event_API_Reference
|
|
|
|
[buk]: http://jd.bukkit.org/dev/apidocs/index.html?org/bukkit/event/Event.html
|
|
|
|
|
|
|
|
***/
|
2013-12-24 01:16:07 +01:00
|
|
|
|
2014-02-19 23:17:19 +01:00
|
|
|
var bkEventPriority = org.bukkit.event.EventPriority,
|
|
|
|
bkEventExecutor = org.bukkit.plugin.EventExecutor,
|
|
|
|
bkRegisteredListener = org.bukkit.plugin.RegisteredListener,
|
|
|
|
bkEventPackage = 'org.bukkit.event.';
|
2013-12-24 01:16:07 +01:00
|
|
|
|
|
|
|
exports.on = function(
|
2014-01-29 20:49:15 +01:00
|
|
|
/* String or java Class */
|
|
|
|
eventType,
|
|
|
|
/* function( registeredListener, event) */
|
|
|
|
handler,
|
|
|
|
/* (optional) String (HIGH, HIGHEST, LOW, LOWEST, NORMAL, MONITOR), */
|
|
|
|
priority ) {
|
|
|
|
var handlerList,
|
|
|
|
listener = {},
|
|
|
|
eventExecutor;
|
|
|
|
|
|
|
|
if ( typeof priority == 'undefined' ) {
|
2014-02-19 23:17:19 +01:00
|
|
|
priority = bkEventPriority.HIGHEST;
|
2014-01-29 20:49:15 +01:00
|
|
|
} else {
|
2014-02-19 23:17:19 +01:00
|
|
|
priority = bkEventPriority[priority.toUpperCase()];
|
2014-01-29 20:49:15 +01:00
|
|
|
}
|
|
|
|
if ( typeof eventType == 'string' ) {
|
|
|
|
/*
|
|
|
|
Nashorn doesn't support bracket notation for accessing packages.
|
|
|
|
E.g. java.net will work but java['net'] won't.
|
|
|
|
|
|
|
|
https://bugs.openjdk.java.net/browse/JDK-8031715
|
|
|
|
*/
|
|
|
|
if ( typeof Java != 'undefined' ) {
|
|
|
|
// nashorn environment
|
2014-02-19 23:17:19 +01:00
|
|
|
eventType = Java.type( bkEventPackage + eventType );
|
2014-01-29 20:49:15 +01:00
|
|
|
} else {
|
2014-02-19 23:17:19 +01:00
|
|
|
eventType = eval( bkEventPackage + eventType );
|
2013-01-15 21:55:41 +01:00
|
|
|
}
|
2014-01-29 20:49:15 +01:00
|
|
|
}
|
|
|
|
handlerList = eventType.getHandlerList( );
|
2014-03-15 19:06:23 +01:00
|
|
|
|
|
|
|
var result = { };
|
2014-04-25 02:51:11 +02:00
|
|
|
eventExecutor = new bkEventExecutor( {
|
2014-03-15 19:06:23 +01:00
|
|
|
execute: function( l, evt ) {
|
|
|
|
handler.call( result, evt );
|
2014-01-29 20:49:15 +01:00
|
|
|
}
|
2014-04-25 02:51:11 +02:00
|
|
|
} );
|
2014-01-29 20:49:15 +01:00
|
|
|
/*
|
|
|
|
wph 20130222 issue #64 bad interaction with Essentials plugin
|
|
|
|
if another plugin tries to unregister a Listener (not a Plugin or a RegisteredListener)
|
|
|
|
then BOOM! the other plugin will throw an error because Rhino can't coerce an
|
|
|
|
equals() method from an Interface.
|
|
|
|
The workaround is to make the ScriptCraftPlugin java class a Listener.
|
|
|
|
Should only unregister() registered plugins in ScriptCraft js code.
|
|
|
|
*/
|
2014-02-19 23:17:19 +01:00
|
|
|
listener.reg = new bkRegisteredListener( __plugin, eventExecutor, priority, __plugin, true );
|
2014-01-29 20:49:15 +01:00
|
|
|
handlerList.register( listener.reg );
|
2014-03-15 19:06:23 +01:00
|
|
|
result.unregister = function(){
|
|
|
|
handlerList.unregister( listener.reg );
|
|
|
|
};
|
|
|
|
return result;
|
2013-12-24 01:16:07 +01:00
|
|
|
};
|