Bukkit

Note that this guide is not final and that we plan to make it much more thorough once we have some time to work on it. However, as the API is fully functional, we thought we might as well post this for more experienced java users who won't need as much explanation. Here's the link to the javadoc: Javadoc

In order to use the spells API, you must import spells.jar (the same jar as is used to run the plugin), in addition to whatever version you want of bukkit.jar (or craftbukkit.jar if you like).

Spells is capable of loading 3 things: a class file whose class extends Spell (use this for any spell that you only need a single class for), a jar file with your spell and whichever other files you want (use this if you want multiple classes) or a jar file with multiple spells and other helper classes (use this if you want to package multiple spells together. This is not recommended, as we like the idea of server owners being able to choose which spells they want on the server without being forced to use groups containing spells they might not want).

Whichever option you choose, you will need a class that extends Spell (aor.spells.Spell). There are a few methods which you are required to override and others which are optional, but usually overridden. Note that SpelUtils (aor.spells.SpellUtils) contains some useful helper functions, which might be worth looking at. In addition, Spell implements Listener (org.bukkit.event.Listener), which means you can listen to any bukkit events in your spell, giving you a lot of flexibility with the spells you can create. All Spells are automatically registered for their events. For more information about bukkit event listeners go here. Spells actually calls a SpellCastEvent every time a spell is cast, which you can use to cancel a spell being cast, if you want.

Spells must override the following methods:

• String getName()
• String getDescription()
• void cast()
• String getRequirements()

It is recommended that they also override these methods, although they are not required and sometimes unnecesary:

• String getGroup()
• String getCooldownMessage()
• int getCooldown()
• boolean checkRequirements()
• boolean removeRequirements()

For more information about all of these methods, please take a look at the javadoc.

Once you finish your spell, simply compile it to a .class file and put it in the spells directory of your server. If you export the spell to a .jar file, make sure to name the jar the same thing as your main class, so spells can find it. If you wish to have multiple spells in a .jar, create another class which extends SpellSet and override getSpells(), making it return a collection (list etc.) of spells in the jar. The spell set class must have the same name as the jar file. ex. spellset.jar would have a class file called spellset.class, which would extend spellset.

We recommend that you take a look at some of our spells, so you can see some examples of how to use the API, in addition to looking at the javadoc.

If there is any additional functionality you think the Spells API should have, please leave us a comment.