Bukkit

Implementing Cannons allows you to manipulate cannons or alter the behaviour of cannons. The driving force behind the implementation of this API was to keep Cannons synchronized with movement plugins e.g. Ships, iSail. The problem with this plugins is that the cannon is moved without notifying Cannons or updating the cannon position. Since Cannons still believes the cannon is on the old position, it will create a new cannon on the new position. You end up with a new cannon and a ghost cannon on the old location.
You can put a sign with the cannon name on a cannon to find it, even if it was moved. However the location of the cannon will only be updated when you touch the cannon. Therefore the applications for cannons with signs are limited
However the API allows you to find all cannons on your ship, and update their location on every move. The cannons will therefore stay synchronized with the ship. You can therefore e.g.: fire several shots with a cannon while moving the ship at the same time.

Importing Cannons

You can either add the .jar file to your project or use my Maven repository and add Cannons as dependency.

Adding dependencies

When you use Cannons for your plugin then you have to tell Bukkit to load your plugin after Cannons. Go to your plugin.yml add a 'depend' or 'softdepend' for Cannons. 'Depend' means that your plugin will NOT run without Cannons as additionional plugin. For 'softdepend' your plugin will be loaded in any case, but after Cannons (if present). If you make a ship plugin with additional support for cannons on their ships, you will need 'softdepend'. So your plugin will work with or without cannons.

main: com.example.someplugin.Someplugin
name: Someplugin
softdepend: [Cannons]

Events

Cannons has a bunch of events which you can use to e.g. detect when a cannon was created. You find all the events on my github page:
https://github.com/DerPavlov/Cannons/tree/master/src/main/java/at/pavlov/cannons/event

Hooking into Cannons

To use the internal methods in Cannons you can request the main class from Bukkit. Use something like that:

    public CannonsAPI loadCannonsAPI()
    {
        Plugin plug = pm.getPlugin("Cannons");

        if (plug != null && plug instanceof Cannons) {
            Cannons c = (Cannons) plug;
            return c.getCannonsAPI();
        }
        return null;
    }

Note: Whenever you use softdepend you have to make sure that the API can be 'null'.

Code examples

Find a cannon with a given UID

 Cannon cannon = plugin.getCannonsAPI().getCannon(uid);

Returns all Cannons for a given box.

 HashSet<Cannon> cannons = plugin.getCannonsAPI().getCannonsInBox(player.getLocation(), 10, 10, 10);

Hand over a list of block locations and it will return all cannons where one block of the cannon is given in the list. It will also create new cannons if it finds something. Make silent: false to prevent several messages for created cannons.

HashSet<Cannon> cannons = plugin.getCannonsAPI().getCannons(locations, player.getUniqueId(), silent)

Moving a cannon by a given vector

cannon.move(new Vector(1,0,0));

Turning a cannon around the player location

cannon.rotateRight(player.getLocation().toVector());

Working with vectors can be confusing. Therefore I recommend the cannon.show() and cannon.hide() command to force the cannon stored in the cannons plugin to become visible.
Note: This will overwrite all other blocks at the cannon location

cannon.show();

Cannons have an on ship option, which affects the aiming angle. If the cannon is on a ship it can be reduced (or increased) depending on AngleOnShip.

cannon.setOnShip(true);

If you make a ship plugin, than the mass of a cannon might be interesting for you. The mass is changeable via config.

cannon.getCannonDesign().getMassOfCannon();