Skip to main content
The best way to understand the Dimensions addon API is to read a working example from end to end. This page walks through a complete addon that listens for the CustomPortalIgniteEvent and spawns explosion particles at the center of any portal ignited by a player who holds the dimensions.exampleaddon.explosion permission. The full source is available on GitHub.

​
The Complete Main Class

Below is the full implementation. Each section is explained after the code block. 
package me.xxastaspastaxx.dimensions.addons.exampleaddon;

import me.xxastaspastaxx.dimensions.Dimensions;
import me.xxastaspastaxx.dimensions.DimensionsUtils;
import me.xxastaspastaxx.dimensions.addons.DimensionsAddon;
import me.xxastaspastaxx.dimensions.addons.DimensionsAddonPriority;
import me.xxastaspastaxx.dimensions.completePortal.CompletePortal;
import me.xxastaspastaxx.dimensions.events.CustomPortalIgniteEvent;
import org.bukkit.Bukkit;
import org.bukkit.Location;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.Listener;

public class DimensionsExampleAddonMain extends DimensionsAddon implements Listener {

    public DimensionsExampleAddonMain() {
        super("ExampleAddon", "4.0.0", "An example addon", DimensionsAddonPriority.NORMAL);
    }

    @Override
    public void onEnable(Dimensions pl) {
        Bukkit.getPluginManager().registerEvents(this, pl);
    }

    @EventHandler(ignoreCancelled = true, priority = EventPriority.NORMAL)
    public void postPortalIgnite(CustomPortalIgniteEvent e) {
        if (!(e.getEntity() instanceof Player) ||
            !e.getEntity().hasPermission("dimensions.exampleaddon.explosion")) return;

        CompletePortal complete = e.getCompletePortal();
        Location location = complete.getCenter();
        location.getWorld().spawnParticle(
            DimensionsUtils.getParticle("EXPLOSION", "EXPLOSION_NORMAL"), location, 5);
    }
}

​
Code Walkthrough

Class declaration — extends DimensionsAddon implements Listener Every addon must extend DimensionsAddon. Implementing Listener is optional but required whenever you want to handle Bukkit or Dimensions events directly in the same class. Constructor — super(...) The super(...) call registers the addon’s metadata with Dimensions. Pass in a unique name, the target version, a short description, and a priority. DimensionsAddonPriority.NORMAL is the right choice for most addons. onEnable(Dimensions pl) Dimensions calls this method when it activates your addon. Registering this as a listener here ensures your @EventHandler methods receive events. The pl parameter is the live Dimensions plugin instance — pass it to registerEvents so Bukkit ties the listener lifetime to the Dimensions plugin. @EventHandler — postPortalIgnite Setting ignoreCancelled = true means your handler is skipped if another addon or listener already cancelled the event — a good default that prevents double-triggering side effects. The guard at the top of the method exits early if the igniting entity is not a Player or if the player lacks the required permission, keeping the logic clean and safe. e.getCompletePortal() returns the physical portal in the world, and getCenter() gives you a Location to anchor the particle effect. DimensionsUtils.getParticle(...) is a Dimensions helper that resolves the correct particle name across different server versions.

​
ServiceLoader Registration File

After writing the main class, create the following file structure inside your src directory so Dimensions can discover your addon: 
src/main/java/META-INF/services/me.xxastaspastaxx.dimensions.addons.DimensionsAddon
The content of that file should be the fully-qualified class name of your main class: 
me.xxastaspastaxx.dimensions.addons.exampleaddon.DimensionsExampleAddonMain
The file name must be exactly me.xxastaspastaxx.dimensions.addons.DimensionsAddon — no extension, no extra characters. This is how Java’s ServiceLoader locates service implementations at runtime.

​
Deploying the Addon

Build your project into a JAR and place it in ./plugins/Dimensions/Addons/. Restart the server and Dimensions will load your addon automatically.
Follow the Creating an Addon guide for a full explanation of each setup step, including build-path configuration and project structure.