📣 Bukkit Events

EventForge exposes Bukkit events so addons can react to EventForge activity.

Use these when you want your plugin to run custom logic when events start, stop, finish, reload, score changes happen, or milestones are reached.

---

Available events

EventForgeEventStartEvent
EventForgeEventStopEvent
EventForgeEventFinishEvent
EventForgePlayerScoreChangeEvent
EventForgePlayerMilestoneEvent
EventForgeReloadEvent

---

Register a listener

public final class MyAddonPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        getServer().getPluginManager().registerEvents(new MyEventForgeListener(), this);
    }
}

---

Event start

Called when an EventForge event starts.

@EventHandler
public void onEventStart(EventForgeEventStartEvent event) {
    String eventId = event.getEventId();
    String displayName = event.getEventDisplayName();

    Bukkit.getLogger().info("Event started: " + displayName + " (" + eventId + ")");
}

Useful for:

starting addon-side timers
announcing custom messages
loading temporary addon state
starting external integrations

---

Event stop

Called when an EventForge event is stopped.

@EventHandler
public void onEventStop(EventForgeEventStopEvent event) {
    Bukkit.getLogger().info("Event stopped: " + event.getEventId());
}

This can happen when:

an admin stops the event
EventForge reloads
the server shuts down
another system stops the event

---

Event finish

Called when an EventForge event finishes normally.

@EventHandler
public void onEventFinish(EventForgeEventFinishEvent event) {
    Bukkit.getLogger().info("Event finished: " + event.getEventId());
}

Use this for logic that should happen after an event completes naturally.

---

Player score change

Called when a player's score changes during an active EventForge event.

@EventHandler
public void onScoreChange(EventForgePlayerScoreChangeEvent event) {
    Player player = event.getPlayer();

    int oldScore = event.getOldScore();
    int newScore = event.getNewScore();
    int difference = event.getDifference();

    player.sendMessage("Your score changed from " + oldScore + " to " + newScore + " (+" + difference + ")");
}

Useful methods:

event.getEventId();
event.getEventDisplayName();
event.getPlayer();
event.getOldScore();
event.getNewScore();
event.getDifference();

---

Player milestone

Called when a player crosses a configured EventForge milestone.

@EventHandler
public void onMilestone(EventForgePlayerMilestoneEvent event) {
    Player player = event.getPlayer();

    player.sendMessage("Milestone reached: " + event.getMilestone().getDisplayName());
}

Useful methods:

event.getEventId();
event.getEventDisplayName();
event.getPlayer();
event.getMilestone();
event.getOldScore();
event.getNewScore();
event.getScoreChange();

Milestone information:

event.getMilestone().getId();
event.getMilestone().getDisplayName();
event.getMilestone().getThreshold();
event.getMilestone().isOncePerPlayer();
event.getMilestone().getActions();

---

Cancelling milestones

EventForgePlayerMilestoneEvent is cancellable.

If cancelled, the milestone actions will not run and the milestone will not be marked as triggered for that player.

@EventHandler
public void onMilestone(EventForgePlayerMilestoneEvent event) {
    if (event.getMilestone().getThreshold() >= 1000) {
        event.setCancelled(true);
    }
}

Use this only when your addon has a clear reason to block milestone behaviour.

---

Reload event

Called when EventForge reloads.

@EventHandler
public void onReload(EventForgeReloadEvent event) {
    Bukkit.getLogger().info("EventForge reloaded.");
}

Useful reload information:

event.getLoadedEvents();
event.getValidationWarnings();
event.getValidationErrors();
event.getScheduledEvents();
event.getRegisteredObjectives();

Use this to refresh addon-side caches after EventForge reloads.

---

Example listener

package com.example.eventforgeaddon;

import dev.hxze.eventforge.api.event.EventForgeEventStartEvent;
import dev.hxze.eventforge.api.event.EventForgePlayerMilestoneEvent;
import dev.hxze.eventforge.api.event.EventForgePlayerScoreChangeEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public final class MyEventForgeListener implements Listener {

    @EventHandler
    public void onEventStart(EventForgeEventStartEvent event) {
        System.out.println("Started: " + event.getEventId());
    }

    @EventHandler
    public void onScoreChange(EventForgePlayerScoreChangeEvent event) {
        event.getPlayer().sendMessage("Score: " + event.getNewScore());
    }

    @EventHandler
    public void onMilestone(EventForgePlayerMilestoneEvent event) {
        event.getPlayer().sendMessage("Milestone: " + event.getMilestone().getDisplayName());
    }
}

---

Notes

Some events are player-based and some are not.

Player-based events:

EventForgePlayerScoreChangeEvent
EventForgePlayerMilestoneEvent

Event lifecycle events:

EventForgeEventStartEvent
EventForgeEventStopEvent
EventForgeEventFinishEvent
EventForgeReloadEvent

---

Summary

Use Bukkit events when your addon needs to react to EventForge without directly modifying event configs.

Common uses:

custom announcements
quest progress
external logging
discord integrations
custom rewards
milestone integrations
addon-side cleanup