Creating a simple plugin with ItemMeta and Fireworks

Hey, I thought this may be help to plugin developers who want to learn how to change things like the name of an item and creating a firework using the new ItemMeta system. I am also using Maven for this tutorial so you will need m2eclipse unless you do not want to use Maven.

Step 1: Setting up your project
Start by creating a new java project, I am going to name mine "ChristmasSurprise".



Then convert it to a Maven project.



Then create your source folders and add the Bukkit repository and dependency to your pom.xml as well as the resources to make sure all config files and the plugin.yml is included in the jar.. Also make sure you are using Bukkit 1.4.6 or later. I use "LATEST" as my version.

Code:

<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>
 
    <!-- Project information -->
    <name>ChristmasSurprise</name>
    <groupId>me.limebyte</groupId>
    <artifactId>christmassurprise</artifactId>
    <version>0.0.1</version>
    <inceptionYear>2012</inceptionYear>
    <description>Surprise your users on Christmas with a cool little gift.</description>
 
    <!-- Repositories -->
    <repositories>
        <repository>
            <id>bukkit-repo</id>
            <url>http://repo.bukkit.org/content/groups/public</url>
        </repository>
    </repositories>
 
    <!-- Dependencies -->
    <dependencies>
        <dependency>
            <groupId>org.bukkit</groupId>
            <artifactId>bukkit</artifactId>
            <version>LATEST</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
 
    <!-- Build settings -->
    <build>
        <finalName>${project.name}</finalName>
        <defaultGoal>clean package</defaultGoal>
 
        <!-- Resources -->
        <resources>
            <resource>
                <targetPath>.</targetPath>
                <directory>${basedir}/src/main/resources/</directory>
                <filtering>true</filtering>
                <includes>
                    <include>*.yml</include>
                    <include>*.dat</include>
                </includes>
            </resource>
        </resources>
 
        <!-- Plugins -->
        <plugins>
            <!-- Compiler -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>2.4</version>
                <configuration>
                    <source>1.6</source>
                    <target>1.6</target>
                    <showDeprecation>true</showDeprecation>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Step 2: Plugin basics
Next create your plugin.yml in the src/main/resources folder.

Code:

name: ${project.name}
author: LimeByte
version: ${project.version}
description: ${project.description}
 
main: ${project.groupId}.${project.artifactId}.${project.name}
load: POSTWORLD

Then create the main class in src/main/java inside your package for your plugin and extend JavaPlugin



Finally create the onEnable and onDisable methods and add a bit of logging for the console.

Code:

package me.limebyte.christmassurprise;
 
import java.util.logging.Logger;
 
import org.bukkit.plugin.PluginDescriptionFile;
import org.bukkit.plugin.java.JavaPlugin;
 
public class ChristmasSurprise extends JavaPlugin {
 
    private static Logger log;
 
    public void onEnable() {
        log = this.getLogger();
 
        // Enable Message
        PluginDescriptionFile pdf = getDescription();
        log.info("Version " + pdf.getVersion() + " enabled successfully.");
        log.info("Made by LimeByte.");
    }
 
    public void onDisable() {
        // Disable Message
        PluginDescriptionFile pdf = getDescription();
        log.info("Version " + pdf.getVersion() + " has been disabled.");
    }
 
}

Step 3: Player Join Event
Create a new class which implements Listener, I am going to call mine EventListener.java.



Next, register it in your main class in onEnable().

Code:

public void onEnable() {
    log = this.getLogger();
 
    // Event Registration
    PluginManager pm = getServer().getPluginManager();
    pm.registerEvents(new EventListener(), this);
 
    // Enable Message
    PluginDescriptionFile pdf = getDescription();
    log.info("Version " + pdf.getVersion() + " enabled successfully.");
    log.info("Made by LimeByte.");
}

Then at the bottom of the main class, create a static method called giveGift.

Code:

public static void giveGift(Player player) {
 
}

Finally go back to the EventListener.java class and add a listener for the PlayerJoinEvent and call the giveGift(Player player) method.

Code:

package me.limebyte.christmassurprise;
 
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;
 
public class EventListener implements Listener {
 
    @EventHandler
    public void onPlayerJoin(PlayerJoinEvent event) {
        ChristmasSurprise.giveGift(event.getPlayer());
    }
 
}

Step 4: Creating the Gift
In the main class create another static method called contstructGift(). In this method we will create the gift and return it as an ItemStack.

Code:

public static ItemStack constructGift() {
    ItemStack stack = new ItemStack(Material.FIREWORK, 1);
    return stack;
}

The above code will return one firework when it is called. But because fireworks don't do too much by default we need to modify its ItemMeta to make it a little more exciting.

Code:

public static ItemStack constructGift() {
    ItemStack stack = new ItemStack(Material.FIREWORK, 1);
    FireworkMeta meta = (FireworkMeta) stack.getItemMeta();
 
    Builder effect1 = FireworkEffect.builder();
    effect1.with(Type.BALL_LARGE);
    effect1.withColor(Color.RED);
    effect1.withFlicker();
    meta.addEffect(effect1.build());
 
    Builder effect2 = FireworkEffect.builder();
    effect2.with(Type.BALL);
    effect2.withColor(Color.GREEN);
    effect2.withFlicker();
    meta.addEffect(effect2.build());
 
    meta.setPower(3);
 
    stack.setItemMeta(meta);
    return stack;
}

This code will create a firework with power 3, a large red ball with flicker and a small green ball with flicker. To inform the player a little more on why they have a firework we will rename the item by setting its display name.

Code:

meta.setDisplayName("Christmas Gift");

Since the gift is going to be the same for every player, we want to call this method in onEnable instead of running the same code every time a player joins. So we need to create a variable to store the created ItemStack and call the method in the onEnable.

Code:

private static Logger log;
private static ItemStack gift;
 
public void onEnable() {
    log = this.getLogger();
    gift = constructGift();
 
    // Event Registration
    PluginManager pm = getServer().getPluginManager();
    pm.registerEvents(new EventListener(), this);
 
    // Enable Message
    PluginDescriptionFile pdf = getDescription();
    log.info("Version " + pdf.getVersion() + " enabled successfully.");
    log.info("Made by LimeByte.");
}

Finally we need to give it to the player so in the giveGift method.

Code:

public static void giveGift(Player player) {
    player.getInventory().addItem(gift);
}

Step 5: Testing!
Now we can test our plugin. Export the project as a jar and place it in the plugins folder of a test server.



Open Minecraft and join your server. As you can see below, the name and all of the effects are on the given firework.



And when placed, it gives of a nice Christmas effect.



Step 6: Final Touches
I thought the flight duration was a little too long so I set it to two by changing the power.

Code:

meta.setPower(2);

Players can currently exploit this at the moment by continuously joining to get a heap of fireworks. To fix this I added a list to the default config file that contains players who already have a gift.

Files and Source Code

ChristmasSurprise.jar


Github.com

 

Perfect for my plugin thanks for this. One internet cookie for you sir.

 

Thank you for the tutorial. This is helping me further my java programming knowledge. I really appreciate the detailed tutorials that people publish on the internet!

Thanks again!

 

That helped me a lot!
Thanks for this great tutorial!

 

Eeeew, Windows 8! (Linux user)

Great tutorial on the new ItemMeta classes! This helped to explain a few things where the JavaDoc was a bit vague. I only knew how to use it because I always keep up to date with CraftBukkit on github.