Share

Share

Welcome to the BukkitWiki!

This Wiki is home to Bukkit's documentation and regulations surrounding the Bukkit Project and it's services. Want to help out? We would love to have you! Signup to get started!

User:Sagacious Zed/Maven Plugin Tutorial

From BukkitWiki
Jump to: navigation, search

This tutorial will help you create your first plugin with the presumption that you, the reader, understands Java and Maven project conventions. The steps on this page are should be IDE agnostic.

Create a project[edit]

Create a new Maven project, this can be done on the command line or in the IDE of choice. For the purpose of a plugin, a simple maven project will be sufficient, however, it may be quicker and easier to use an archetype.

For additional instructions in Eclipse, see User:Sagacious Zed/Maven Plugin Tutorial/Eclipse#Creating A Maven Project

With your own groupId, artifiactId, and version, the following forms the minimal information needed by Maven to mange your plugin:

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example.plugins</groupId>
  <artifactId>ExamplePlugin</artifactId>
  <version>0.0.1-SNAPSHOT</version>
</project>

As your complete you plugin, you will need to tell maven more about your project.

Add Bukkit as a Dependency[edit]

In order to start building your Bukkit plugin, you must declare in your pom.xml the BukkitAPI as a dependency. This is necessary for IDE's and compiling from the command line.

For instructions, see Bukkit as a Maven Dependency

For the purpose of this tutorial, we will make a plugin named Example Plugin. After Adding the Bukkit repository the Bukkit API as a dependency, your pom.xml will similar to this:.

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example.plugin</groupId>
    <artifactId>ExamplePlugin</artifactId>
    <version>1.0.0-SNAPSHOT</version>
 
    <repositories>
        <repository>
            <id>bukkit-repo</id>
            <url>http://repo.bukkit.org/content/groups/public/</url>
        </repository>
    </repositories>
 
    <dependencies>
        <dependency>
            <groupId>org.bukkit</groupId>
            <artifactId>bukkit</artifactId>
            <!-- Bukkit API Version, change if out dated -->
            <version>1.5.2-R1.0</version>
            <type>jar</type>
            <scope>provided</scope>
        </dependency>
    </dependencies>
</project>

Writing your plugin description file[edit]

The plugin description file is commonly refered to as the 'plugin.yml' due to its file name. It describes several aspects of your plugin to the Bukkit API, these aspects will be covered later, for now, this tutorial will focus on the required information for bukkit to load your plugin.

In order for bukkit to load your plugin, the plugin description file must provide three nodes: plugin name, plugin version, and the fully qualified classname of the main class (the entry point to your plugin). The following example is the minimal description that can be found in a plugin, it provides the name for this plugin: ExamplePlugin, the current version: 1.0.0-SNAPSHOT , and the main class: com.example.plugin.ExamplePlugin

name: ExamplePlugin
version: 1.0.0-SNAPSHOT
main: com.example.plugin.ExamplePlugin

By Maven convention, as a resource file for a Java project, it should be saved in src/java/resources folder.

Lightbulb.png Note: While in this example, the plugin description file had actual values, it is possible to use Maven to filter the plugin description file so that the name and version only exist in one place, the pom.

Writing your plugin's main class[edit]

You must create your own JavaPlugin by extending it. It must have the same fully qualified name as decalred in your plugin.yml

We will define the class Exampleplugin which extends JavaPlugin.

package com.example.plugin;
 
import org.bukkit.plugin.JavaPlugin;
 
public final class ExamplePlugin extends JavaPlguin {
 
}

This plugin currently does nothing, however this is the base which all plugins must build upon.

By maven convention, the root of the package structure goes in the src/main/java folder.

Packaging your plugin[edit]

After you have completed the code to your plugin, you should use maven to package your plugin. As with all other projects managed by maven, simply run

mvn package

If this is your first time packaging, you should check the produced jar in target/my-app-0.0.1-SNAPSHOT.jar and make sure that your plugin.yml and (if applicable) config.yml and any other resources are in the correct places.

Deploying your plugin[edit]

Before you can install your plugin on a server it must first be packaged. This can be done quickly by running 'mvn package' on your project from the command line, or in the IDE of your choicce. After the packaging process is completed it is ready to be installed on a CraftBukkit server.

For instructions on installing Bukkit plugins, see Installing Plugins