Plugin Developers Guide to the IslandCraft API

DISCLAIMER: Consider the API features of IslandCraft to be in Beta. They have not been thoroughly tested and are subject to change in the future. I would love to hear any feedback you have if you try to use this!

Overview

This page contains information useful to plugin developers who wish to create a plugin which integrates with IslandCraft.

You can query IslandCraft to find information about the islands which could be useful for a real-estate plugin (an official real-estate plugin will be released, but there's nothing stopping you making your own as well). There are also a number ways you can extend or modify the behavior of IslandCraft's biome generation.

Using the IslandCraft API

The IslandCraft source is split into a few packages. The Bukkit specific code is in com.github.hoqhuuep.islandcraft.bukkit and the public API is in com.github.hoqhuuep.islandcraft.api.

To get a reference to the IslandCraft API from your Bukkit plugin, you must first get a reference to the IslandCraftPlugin. From this point you should try to only refer to classes in the IslandCraft API Here is an example of how to do this:

import org.bukkit.plugin.java.JavaPlugin;

import com.github.hoqhuuep.islandcraft.api.IslandCraft;
import com.github.hoqhuuep.islandcraft.bukkit.IslandCraftPlugin;

public class MyPlugin extends JavaPlugin {
    private IslandCraft islandCraft;

    @Override
    public void onEnable() {
        try {
            final IslandCraftPlugin islandCraftPlugin = getPlugin(IslandCraftPlugin.class);
            islandCraft = islandCraftPlugin.getIslandCraft();
        } catch (final Exception e) {
            getLogger().severe("Could not find IslandCraft, please make sure plugin is installed correctly.");
            setEnabled(false);
            return;
        }

        // TODO use IslandCraft
    }

    @Override
    public void onDisable() {
        islandCraft = null;
    }
}

With a reference to the IslandCraft API you can query various information about the worlds IslandCraft is enabled for and the islands which they contain.

Implementing a Custom Ocean Biome Distribution

The ocean biome distribution is used as a background layer behind any islands which are generated.

You do not need to get a reference to the API to implement your own custom ocean biome distribution. All you need is to create a class which implements the BiomeDistribution interface and include it in your plugin. This class must also contain a public constructor which accepts an array of Strings, these are the parameters passed to your BiomeDistribution from config.yml.

For an example of a BiomeDistribution implementation you can refer to ConstantBiomeDistribution which is provided by IslandCraft.

To use your custom ocean biome distribution, just include your plugin and IslandCraft in your plugins folder and change the value of worlds.<world-name>.ocean in IslandCraft's config.yml to the fully qualified name of your custom biome distribution class followed by space separated parameters which will be passed to the constructor.

Implementing a Custom Island Distribution

The island distribution is used to determine the location and size of all islands in an IslandCraft world.

You do not need to get a reference to the API to implement your own custom island distribution. All you need is to create a class which implements the IslandDistribution interface and include it in your plugin. This class must also contain a public constructor which accepts an array of Strings, these are the parameters passed to your IslandDistribution from config.yml.

It is critical that your IslandDistribution follows these rules:

• The center of an island must be the center of that island's inner-region.
• The inner-region of an island must be no smaller than 16 * 16.
• The outer-region of an island must contain the inner-region of that island (the borders can overlap, they could be the same size).
• The coordinates of the corners of the inner-region and outer-region must be on chunk boundaries, that is they must be divisible by 16.

For some examples of IslandDistribution implementations you can refer to:

• EmptyIslandDistribution - A world with only ocean.
• SquareIslandDistribution - Islands organised in a square pattern.
• HexagonalIslandDistribution - Islands organised in a hexagonal pattern.

These are provided by IslandCraft.

To use your custom island distribution, just include your plugin and IslandCraft in your plugins folder and change the value of worlds.<world-name>.island-distribution in IslandCraft's config.yml to the fully qualified name of your custom island distribution class followed by space separated parameters which will be passed to the constructor.

Implementing a Custom Island Generator

An island generator is used to determine the biomes distribution for an island.

You do not need to get a reference to the API to implement your own custom island generator. All you need is to create a class which implements the IslandGenerator interface and include it in your plugin. This class must also contain a public constructor which accepts an array of Strings, these are the parameters passed to your IslandGenerator from config.yml.

For some examples of IslandGenerator implementations you can refer to:

• EmptyIslandGenerator - Atlantis?
• ConstantIslandGenerator - Big rectangle of a single biome.
• IslandGeneratorAlpha - The original IslandCraft islands, made with Poisson-Voronoi tessalation and Simplex noise ;)

These are provided by IslandCraft.

To use your custom island generator, just include your plugin and IslandCraft in your plugins folder and modify the value of worlds.<world-name>.island-generators in IslandCraft's config.yml to include the fully qualified name of your custom island distribution class followed by space separated parameters which will be passed to the constructor.