Bukkit

Introduction to the Lua Scripts API

Lua Scripts uses an event-based system, much like the one used in the Bukkit plugins themself. Unlike Bukkit, all events within the Lua Scripts API are "hooked" to a function, and then the plugin itself triggers the event.

Let's say you wanted to do something when the script loads (not to be confused with when the server itself is started, as script loading can occur post server loading). In order to do this, we must first create a local function and then we must hook it to an event. We do this like so:

local onScriptInit = function()
	print("Script was initialized!");
end
registerEvent("scriptInit", onScriptInit);

Let's analyse this step by step. Firstly, we are declaring a new local function called onScriptInit, though the name doesn't really matter. The function has to be local, otherwise it could cause complications with other functions similarly named. Within this function, we print a message to the console saying that the script was initialized. After the function has been declared and defined, it then has to be registered. This is where the event system of Lua Scripts come into play.

The function registerEvent() takes two parameters, the first being a string and the second being a function. The first parameter is the type of event we would like to associate the function with, in this case scriptInit which is triggered when the script is initialised. The second parameter is the function that will be called when the event is triggered.

You may have noticed we used the print() function which is a Lua native. I used that there just as it's something people are familiar with, however it is much better to use the log() function which points to the active Logger's info() method. In addition to that, there is also warn() - I'd imagine you can figure that one out for yourselves :)

The only event we've looked at so far is scriptInit, which is really basic and doesn't offer a lot of functionality. What if we want to do something when a player connects?

In the native Bukkit events that can be used within the Lua Scripts API, a parameter is actually passed to the function that has been hooked. This parameter is a Lua table equivalent of the Event instance passed in the listener callback. Here's an example of this.

local onPlayerJoin = function(event)
	local plr = event:getPlayer();
	plr:kickPlayer("Bye!");
end
registerEvent("playerJoin", onPlayerJoin);

As you can see, event is passed to the function. In this case, we are clearly dealing with a PlayerJoinEvent. All of the methods within the event can be accessed from the parameter passed, as displayed above (kicking the player).

That's pretty much it for the tutorial, although before I end it I'd like to show you one more trick. In order to get the most out of your script, you actually need a reference to the Bukkit Server. If you put the line

local server = getServer();

at the top of your script, server will be a Lua table equivalent of the Bukkit Server class.