Event handling

CmdrDats edited this page Dec 30, 2012 · 5 revisions

Events

(:require [cljminecraft.events :as ev])

Source: events.clj

Bukkit Docs: http://wiki.bukkit.org/Event_API_Reference - Note that the cljminecraft framework for handling events does not use the annotations, so is quite different

Description

This is a wrapper over the set of event classes in Bukkit and lets you register functions as callbacks for when events happen on the server as well as giving you a way to explore the events from within a REPL environment.

Usage

To register an event, all you need is a single argument function and a call to register-event:

(defn block-break [ev]
  {:msg "You broke a block!"}

(ev/register-eventlist plugin [(ev/event "block.block-break" #'block-break)])

If the callback function returns a map with :msg, it will be dispatched to the player that the event happened to, automagically.

Multiple calls to register-eventlist will make sure that the same event callback won't get registered twice.

Exploration

Now for the fun bit, if you're unsure of the event you're looking for - instead of trawling through the event classes, simply fire up the REPL and do something like:

user=> (in-ns 'cljminecraft.core)
#<Namespace cljminecraft.core>
cljminecraft.core=> (ev/find-event "break")
("painting.painting-break-by-entity" "hanging.hanging-break" "painting.painting-break" "entity.entity-break-door" "hanging.hanging-break-by-entity" "player.player-item-break" "block.block-break")
;;; block.block-break looks good.. lets see what we can get out of it
cljminecraft.core=> (ev/describe-event "block.block-break")
#{"setExpToDrop" "isCancelled" "getEventName" "setCancelled" "getExpToDrop" "getPlayer" "getBlock"}

The key functions here are find-event and describe-event that you can use to find and describe interesting events in Bukkit.

Enum lists

Of special note are the actions and priorities enums which you can use to pull Enum's out for use with Bukkit instead of dealing with the Action and Priority enums directly:

cljminecraft.core=> ev/actions
{:left_click_block #<Action LEFT_CLICK_BLOCK>, :left_click_air #<Action LEFT_CLICK_AIR>, :right_click_air #<Action RIGHT_CLICK_AIR>, :physical #<Action PHYSICAL>, :right_click_block #<Action RIGHT_CLICK_BLOCK>}
cljminecraft.core=> ev/priorities
{:normal #<EventPriority NORMAL>, :monitor #<EventPriority MONITOR>, :lowest #<EventPriority LOWEST>, :low #<EventPriority LOW>, :high #<EventPriority HIGH>, :highest #<EventPriority HIGHEST>}

This will automatically be correct for whichever version of Bukkit you are using.