〽️ 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, voting, scheduled voting, manual queues 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.3-release</version>
    <scope>provided</scope>
</dependency>

info

Use provided scope because EventForge provides the API at runtime.

---

Spigot dependency

EventForge v1.0.3 supports Spigot, Paper and Purpur across the supported 1.21.x range.

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.3-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 EventForge API 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.3-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 if your addon can still run without EventForge:

softdepend:
  - 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.3, this returns:

1.0.3-release

---

Common services

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

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

---

v1.0.3 service additions

EventForge v1.0.3 added public services for:

manual event voting
scheduled hybrid voting
manual event queues

EventVoteService voteService = EventForgeAPI.getEventVoteService();
ScheduledVoteService scheduledVoteService = EventForgeAPI.getScheduledVoteService();
EventQueueService queueService = EventForgeAPI.getEventQueueService();

These services use safe immutable snapshots such as:

EventVoteInfo
ScheduledVoteInfo
EventQueueInfo

---

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);

    // Send parsed message to your Discord bridge here.
});

---

Listening to EventForge events

EventForge exposes Bukkit events for addon plugins.

getServer().getPluginManager().registerEvents(new MyEventForgeListener(), this);

v1.0.3 includes events for:

event lifecycle
score changes
milestones
rewards
reloads
manual votes
scheduled votes
manual queues
dialogues

See the Bukkit Events page for examples.

---

Notes for release users

The API dependency is for addon development only.

Server owners only need to install the EventForge plugin jar on their server.

Do not shade EventForge API classes into your addon jar unless you know exactly why you need to. The normal setup is provided / compileOnly.