API - Creating One, Looking for Feedback

Hello! I'm hoping to make the first non-Beta release of my little baby plugin, Magic, and I plan to have a fully-formed developer API on release.

Briefly, Magic is a plugin about casting spells with wands. It is meant to be an extension to SMP, as wand items are craftable, echantable, and discoverable with MagicWorlds.

A few people have asked about an API, and now there is one! Well, two, actually.

Other plugins can easily integrate with Magic for casting spells, creating wands, and a few other useful things via a lightweight stand-alone API:

http://jenkins.elmakers.com/job/MagicAPI/doxygen/

I plan on adding an API for the image map functionality ("Camera" spell), and probably a few other things, but this is what will be here for the 1.0 API release.

Other plugins may also more deeply integrate with Magic by adding completely new Spell classes. This is not (currently?) possible with only the API, however, a plugin must link to MagicPlugin itself. Think of this like linking to CraftBukkit when Bukkit fails you

http://jenkins.elmakers.com/job/MagicPlugin/doxygen/index.html

This is still very easy to do- Magic provides several base classes to work with, all of which extend the base Spell class. These classes provide utilities for entity and block targeting, batched undoable block manipulation, and more.

You only need to implement one abstract method, onCast, which will be called whenever you spell is cast.

Creating a new Class that extends Spell is all you need to do to add new spells to Magic- you don't even need to check for the Plugin on load, just add "softenable" to your plugin.yml. The rest is config-driven, an admin (or yourself) would add a definition for your spell to spells.yml, and your custom spell class will be auto-loaded.

I have provided the MagicWorlds plugin as an example of both, it links to MagicAPI to cast spells and create wands, and also links to MagicPlugin to add the custom PurgeSpell, which will clear a world of all entities of the target type. It's very simple, and meant to demonstrate how to add a custom spell- it's about 30 lines of code, with imports and formatting:

https://raw.githubusercontent.com/e...kit/plugins/magicworlds/spell/PurgeSpell.java

An example spells.yml file is also provided to show how you would add this spell to a server running your plugin and Magic:

https://github.com/elBukkit/MagicWorlds/blob/master/src/main/resources/examples/magic/spells.yml

At which point it acts like any other spell in magic- it will show up in lists, tab-completion, be available on wands, etc.

All three are Mavenized, and I have a repository available so this should be as easy as adding a few lines to your pom.xml (if your project is Mavenized, and it should be!).

Have I missed anything? Is anyone interested in working with me on integration, or making my API better? Have any cool spell ideas, particularly those that would be specific to your own plugin?

Thanks for reading!

 

This actually seems like a really neat idea. I probably won't personally have much use for it, but I may need to find some so that I can test it out.

 

I've been thinking about this some more, and I might like to try and make MagicAPI a stand-alone library. The image map (custom map images from URLs) functionality could be useful to others, and if I could abstract the batched block modification code, a lot of people might like to use that.

If I could make this all functional in the API itself without needing Magic, that might be cool. But I've never done something like that before- does anyone have any advice there?

For instance, is there something special I need to do to shade the API code so multiple plugins using different versions of it ("provided", so it's built in) don't conflict with one another?

 

Bump - I changed the topic to be more direct.

The more I think about this, the more I would like to make a stand alone lib, but I'm not sure about the versioning consequences (see my previous post). Can anyone help me out with that?

 

For what it's worth, here's where I ended up going with this: I separated out the interface-only API from the common, reusable functionality. I now have MagicLib. This turned out to be mostly an organizational thing, I was originally thinking it would be necessary for shading, but no.

There are 3 use cases I can think of:

- MagicLib may be shaded into your own plugin if you want to use anything in it but not interact with Magic.
- You may use MagicLib as "provided" if you plan on hard-depending on Magic.

And the weird case that's been giving me a lot of trouble, but is also the case I'm most interested in for MagicWorlds:

- If you want to use MagicLib, but also soft-depend on Magic to interact with it, you can. Just use MagicLib as "provided", and if you're not going to run Magic, run MagicLib as a stand-alone plugin. It will load in Bukkit solely for the purpose of providing the Lib implementation in a non-conflicting way. I'm not sure if this means I need to submit it as a real plugin, or what... probably.

... Does this all sound reasonable?

As a bonus, I've added a ton of stuff to MagicLib. Most of it needs some documentation, but briefly:

• URLMap : This can be used to easily load player skins or any other web image onto an in-game map.
• Target : A low-level targeting helper, I'd like to extend this into a reusable targeting system, but at the moment a lot of the higher-level logic is embedded in the Spell class. The "Target" object is a scoring mechanism, it takes a location/block/entity and scores it based on a number of criteria, allowing you to choose the most appropriate target from an arbitrary set, given a source entity/location.
• Effects : The Magic effects library is now part of the lib. All of the EffectPlayer classes used by Spells to produce visual and audio effects can be used stand-alone. This includes raw particles, fireworks, sounds and Bukkit effects via a number of different player mechanisms (trail, ring, etc).