〽️ Maven Setup

EventForge provides a public API jar for addon developers.

Use this if you want to build plugins that hook into EventForge events, stats, schedules, objectives, actions, variables, text effects, dialogues, or Bukkit events.

---

Maven dependency

Add the EventForge API dependency to your plugin:

<dependency>
    <groupId>dev.hxze</groupId>
    <artifactId>eventforge-api</artifactId>
    <version>1.0.2-release</version>
    <scope>provided</scope>
</dependency>

info

Use provided scope because EventForge provides the API at runtime.

---

Spigot dependency

EventForge v1.0.2 supports Spigot, Paper, and Purpur.

For a Spigot-compatible addon, use:

<dependency>
    <groupId>org.spigotmc</groupId>
    <artifactId>spigot-api</artifactId>
    <version>1.21.11-R0.1-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>

---

Full Maven example

<project>
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>eventforge-addon</artifactId>
    <version>1.0.0</version>

    <properties>
        <maven.compiler.release>21</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <eventforge.version>1.0.2-release</eventforge.version>
        <spigot.version>1.21.11-R0.1-SNAPSHOT</spigot.version>
    </properties>

    <repositories>
        <repository>
            <id>spigot-repo</id>
            <url>https://hub.spigotmc.org/nexus/content/repositories/snapshots/</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>dev.hxze</groupId>
            <artifactId>eventforge-api</artifactId>
            <version>${eventforge.version}</version>
            <scope>provided</scope>
        </dependency>

        <dependency>
            <groupId>org.spigotmc</groupId>
            <artifactId>spigot-api</artifactId>
            <version>${spigot.version}</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
</project>

---

Gradle example

If you use Gradle, add the dependency as compileOnly.

repositories {
    mavenCentral()

    maven {
        name = "spigot-repo"
        url = "https://hub.spigotmc.org/nexus/content/repositories/snapshots/"
    }
}

dependencies {
    compileOnly "dev.hxze:eventforge-api:1.0.2-release"
    compileOnly "org.spigotmc:spigot-api:1.21.11-R0.1-SNAPSHOT"
}

---

plugin.yml

Your addon should depend on EventForge.

name: MyEventForgeAddon
version: '1.0.0'
main: com.example.myeventforgeaddon.MyEventForgeAddonPlugin
api-version: '1.21'
depend:
  - EventForge

Use depend if your addon requires EventForge to work.

Use softdepend only if the addon can still run without EventForge.

---

Basic startup check

package com.example.myeventforgeaddon;

import dev.hxze.eventforge.api.EventForgeAPI;
import org.bukkit.plugin.java.JavaPlugin;

public final class MyEventForgeAddonPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        if (!EventForgeAPI.isAvailable()) {
            getLogger().severe("EventForgeAPI is not available. Is EventForge installed?");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }

        getLogger().info("Hooked into EventForge API " + EventForgeAPI.getApiVersion());
    }
}

---

API version

You can read the EventForge API version at runtime:

String apiVersion = EventForgeAPI.getApiVersion();

For v1.0.2, this returns:

1.0.2-release

---

Common services

Once the API is available, you can use the public services:

EventForgeAPI.getEventService();
EventForgeAPI.getEventPackService();
EventForgeAPI.getStatsService();
EventForgeAPI.getScheduleService();
EventForgeAPI.getObjectiveService();
EventForgeAPI.getObjectiveRegistry();
EventForgeAPI.getActionRegistry();
EventForgeAPI.getActionService();
EventForgeAPI.getVariableService();
EventForgeAPI.getTextEffectService();
EventForgeAPI.getDialogueService();

---

Registering custom objectives

Custom objectives are registered through the objective registry:

EventForgeAPI.getObjectiveRegistry().register(new MyObjectiveHandler());

Unregister on disable:

EventForgeAPI.getObjectiveRegistry().unregister("MY_OBJECTIVE");

Built-in EventForge objective types are protected and cannot be unregistered by addons.

---

Registering custom actions

Custom actions are registered through the action registry.

EventForgeAPI.getActionRegistry().register("DISCORD_LOG", (action, context) -> {
    String message = action.getString("message", "{event_display} started!");
    String parsed = context.parsePlaceholders(message);

    Bukkit.getLogger().info("[DISCORD_LOG] " + parsed);
});

Server owners can then use that action type in event configs:

triggers:
  event-start:
    actions:
      - type: DISCORD_LOG
        message: "{event_display} started!"

Built-in EventForge action types are protected and cannot be unregistered by addons.

---

Parsing variables

v1.0.2 added the public VariableService.

String parsed = EventForgeAPI.getVariableService().parse(
        "mining_rush",
        "{var:event_color}{event_display}"
);

For player-aware parsing:

String parsed = EventForgeAPI.getVariableService().parse(
        "mining_rush",
        player,
        "Hello {player}, your score is {score}."
);

---

Parsing text effects

v1.0.2 added the public TextEffectService.

String parsed = EventForgeAPI.getTextEffectService().parse(
        "<gradient:#22d3ed:#ffffff>Event Started</gradient>"
);

For animated effects, pass an animation tick:

String parsed = EventForgeAPI.getTextEffectService().parse(
        "<stack:rainbow,wobble>Event Started</stack>",
        animationTick
);

---

Executing EventForge actions

v1.0.2 added the public ActionService.

This lets addons execute EventForge actions through the same action system used by normal event configs.

EventForgeAPI.getActionService().executeAll(
        eventId,
        player,
        actions,
        placeholders
);

Use this when a custom objective needs to run configured EventForge actions.

---

Starting dialogues

EventForgeAPI.getDialogueService()
        .startEventDialogue(player, "relic_hunt", "guide_intro")
        .thenAccept(session -> {
            if (session.isCompleted()) {
                // Continue your task or quest logic.
            }
        });

---

Recommended Java version

EventForge targets modern Minecraft servers and Java 21.

Use:

<maven.compiler.release>21</maven.compiler.release>