Installation

This page will show you how to download and setup QuarterBukkit in your plugin.

Setup

First, you have to add several QuarterBukkit jars to the classpath of your project. You can do that in two different ways:

Maven

If you build with Maven, you have to add some dependencies related to QuarterBukkit to your project object model.

Add the LoadingByte maven repository to the pom.xml of your maven project:

<repository>
    <id>quartercode-repository</id>
    <name>QuarterCode Repository</name>
    <url>https://repo.loadingbyte.com/content/groups/maven-public/</url>
</repository>

Add these dependencies to the pom.xml of your maven project (change VERSION to the version of QuarterBukkit you want to use):

<dependency>
    <groupId>com.quartercode</groupId>
    <artifactId>quarterbukkit-plugin</artifactId>
    <version>VERSION</version>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>com.quartercode</groupId>
    <artifactId>quarterbukkit-integration</artifactId>
    <version>VERSION</version>
</dependency>

Add the scope provided to all of your other dependencies which shouldn't be included in the final jar (e.g. bukkit or craftbukkit):

<dependency>
    <groupId>org.bukkit</groupId>
    <artifactId>bukkit</artifactId>
    <version>...</version>
    <scope>provided</scope>
</dependency>

Add the maven shade plugin (if you don't use it already) to your build plugin list:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>2.1</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <createDependencyReducedPom>false</createDependencyReducedPom>
            </configuration>
        </execution>
    </executions>
</plugin>

In the end, your final pom.xml should look like this:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>...</groupId>
    <artifactId>...</artifactId>
    <version>...</version>
    <packaging>jar</packaging>

    ...

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        ...
    </properties>

    <dependencies>
        <!-- Bukkit -->
        <dependency>
            <groupId>org.bukkit</groupId>
            <artifactId>bukkit</artifactId>
            <version>...</version>
            <scope>provided</scope>
        </dependency>

        <!-- QuarterBukkit -->
        <dependency>
            <groupId>com.quartercode</groupId>
            <artifactId>quarterbukkit-plugin</artifactId>
            <version>...</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>com.quartercode</groupId>
            <artifactId>quarterbukkit-integration</artifactId>
            <version>...</version>
        </dependency>

        ...
    </dependencies>

    <repositories>
        <repository>
            <id>bukkit-repository</id>
            <name>Bukkit Repository</name>
            <url>http://repo.bukkit.org/content/groups/public</url>
        </repository>
        <repository>
            <id>quartercode-repository</id>
            <name>QuarterCode Repository</name>
            <url>https://repo.loadingbyte.com/content/groups/maven-public/</url>
        </repository>
    </repositories>

    <build>
        <plugins>
            ...

            <!-- Shade JAR -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>2.1</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                        <configuration>
                            <createDependencyReducedPom>false</createDependencyReducedPom>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Keep in mind that you have to change the versions in your pom.xml if you want to use an updated version of QuarterBukkit.

Ant

If you build with Ant, you can download the precompiled package for the current version from the official download page. After that, you can add QuarterBukkit-Plugin.jar and QuarterBukkit-Integration.jar to your classpath.

Your build.xml script should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<project name="Build Plugin Jar" default="main" basedir=".">
    <!-- Set this to the path of your class folder -->
    <property name="bin" value="bin/" />
    <!-- Set this to the path of your final plugin jar file -->
    <property name="dest" value="Plugin.jar" />
    <!-- Set this to the path of your QuarterBukkit-Integration.jar library -->
    <property name="integrationlib" value="QuarterBukkit-Integration.jar" />

    <target name="main">
        <jar destfile="${dest}">
            <fileset dir="${bin}"/>
            <zipfileset src="${integrationlib}"/>
        </jar>
    </target>
</project>

Of course, you have to modify the property values to suit your directory structure.

Integration Code

Simply import com.quartercode.quarterbukkit.QuarterBukkitIntegration and call QuarterBukkitIntegration.integrate(Plugin) with your plugin object (probably just this) in your onEnable()-method. The method returns true if the integration was sucessful. If not, you should disable your plugin, because it probably wouldn't function without QuarterBukkit. Of course, you could develop plugins which don't completely depend on QuarterBukkit, but the doesn't seem to make any sense ...

Example:

@Override
public void onEnable() {

    if (!QuarterBukkitIntegration.integrate(this)) {
        Bukkit.getPluginManager().disablePlugin(this);
        return;
    }

    // Your code here
}

After that, you should add QuarterBukkit-Plugin to your softdepend-list in the plugin.yml of your plugin. If you don't have this entry yet, simply add this line:

softdepend: [QuarterBukkit-Plugin]

And you're done! Now you can use all the amazing QuarterBukkit-features! See the JavaDoc and [API-Page](API Overview) for more information on those features.

Important Notes

If you want to use QuarterBukkit in your plugin, remember one thing: Don't import/use any QuarterBukkit class or method anywhere in your main class (the one which extends JavaPlugin). You cannot import something from QuarterBukkit before using QuarterBukkitIntegration! That will cause NoClassDefFoundErrors because QuarterBukkit may not be installed yet!

We recommend to use a second main class which also implements onEnable() and onDisable(). You can put all your code in there and call the methods from your real main plugin class.

Keep in mind: Always check your plugins for this issue!