Skip to main content

๐Ÿ”Œ EventService API

EventService is the main API service for interacting with EventForge events.

Use it to:

check loaded events
check active events
start, stop, and finish events
read active sessions
read player scores and ranks
read leaderboards
manage cooldowns
check whether an event can start
filter events by metadata

Getting the service

EventService eventService = EventForgeAPI.getEventService();

Always check the API is available first:

if (!EventForgeAPI.isAvailable()) {
    return;
}

Loaded events

Check if an event is loaded:

boolean loaded = eventService.isEventLoaded("mining_rush");

Get loaded event IDs:

Set<String> loadedEventIds = eventService.getLoadedEventIds();

Get loaded event count:

int count = eventService.getLoadedEventCount();

Get loaded event info:

Optional<EventInfo> eventInfo = eventService.getEventInfo("mining_rush");

Active events

Check if an event is active:

boolean active = eventService.isEventActive("mining_rush");

Get active event IDs:

Set<String> activeEventIds = eventService.getActiveEventIds();

Get active event count:

int count = eventService.getActiveEventCount();

Get active events:

Set<EventInfo> activeEvents = eventService.getActiveEvents();

EventInfo

EventInfo contains public event information.

eventService.getEventInfo("mining_rush").ifPresent(eventInfo -> {
    String id = eventInfo.getId();
    String displayName = eventInfo.getDisplayName();
    int durationSeconds = eventInfo.getDurationSeconds();
    boolean active = eventInfo.isActive();
});

It also includes:

eventInfo.getMetadata();
eventInfo.getVariables();
eventInfo.getObjectives();
eventInfo.hasMultipleObjectives();

Event variables

v1.0.1 added event variables to the public API.

eventService.getEventInfo("relic_hunt").ifPresent(eventInfo -> {
    String arena = eventInfo.getVariables().getVariable("arena_name", "Unknown");
    String color = eventInfo.getVariables().getVariable("event_color", "&f");
});

Useful methods:

getVariables();
getVariable(key);
getVariable(key, fallback);
hasVariable(key);
isEmpty();
size();

Event metadata

Event metadata is useful for browsers, dashboards, and custom menus.

eventService.getEventInfo("mining_rush").ifPresent(eventInfo -> {
    var metadata = eventInfo.getMetadata();

    String category = metadata.getCategory();
    String difficulty = metadata.getDifficulty();
    List<String> tags = metadata.getTags();
});

Filtering events

v1.0.1 added metadata filtering.

Set<EventInfo> survivalEvents = eventService.getEventsByCategory("Survival");
Set<EventInfo> miningEvents = eventService.getEventsWithTag("mining");
Set<EventInfo> hardEvents = eventService.getEventsByDifficulty("Hard");

Use this for:

category menus
event browsers
Discord bot commands
admin dashboards
setup tools

Start checks

Before starting an event, you can check whether it is allowed to start.

EventStartCheckResult result = eventService.getStartCheckResult("relic_hunt");

if (result.hasFailed()) {
    sender.sendMessage("Cannot start: " + result.getReason());
    return;
}

eventService.startEvent("relic_hunt");

Quick boolean check:

boolean canStart = eventService.canStartEvent("relic_hunt");

EventStartCheckResult includes:

canStart();
hasPassed();
hasFailed();
getEventId();
getReason();

Cooldowns

v1.0.1 added cooldown methods.

boolean onCooldown = eventService.isEventOnCooldown("relic_hunt");

Get remaining seconds:

long remaining = eventService
        .getEventCooldownRemainingSeconds("relic_hunt")
        .orElse(0L);

Get cooldown end epoch second:

long endEpoch = eventService
        .getEventCooldownEndEpochSecond("relic_hunt")
        .orElse(0L);

Clear a cooldown:

boolean cleared = eventService.clearEventCooldown("relic_hunt");
info

Cooldowns start after a natural event finish. Forced stop, reload, and shutdown do not start cooldowns.

Starting events

Start an event:

boolean started = eventService.startEvent("mining_rush");

Start an event with a sender:

boolean started = eventService.startEvent("mining_rush", sender);

For custom GUIs or commands, prefer checking first:

EventStartCheckResult result = eventService.getStartCheckResult("mining_rush");

if (!result.canStart()) {
    sender.sendMessage(result.getReason());
    return;
}

eventService.startEvent("mining_rush", sender);

Stopping events

Force-stop an event:

boolean stopped = eventService.stopEvent("mining_rush");

With sender:

boolean stopped = eventService.stopEvent("mining_rush", sender);
warning

A forced stop does not start cooldown.

Finishing events

Finish an event naturally:

boolean finished = eventService.finishEvent("mining_rush");

A natural finish processes normal finish behaviour, such as results and cooldowns.

Reloading events

Reload EventForge events:

boolean reloaded = eventService.reloadEvents();

This reloads event files.

Stopping all events

int stopped = eventService.stopAllEvents();

This returns the number of events stopped.

Active sessions

Get the active objective session:

Optional<EventObjectiveSession> session = eventService.getActiveSession("mining_rush");

Example:

eventService.getActiveSession("mining_rush").ifPresent(session -> {
    long remaining = session.getSecondsRemaining();
    int participants = session.getParticipantCount();
});

Scores

Add score:

eventService.addScore("mining_rush", player, 10);

Set score:

eventService.setScore("mining_rush", player, 50);

Get score:

int score = eventService
        .getScore("mining_rush", player)
        .orElse(0);

Get rank:

int rank = eventService
        .getRank("mining_rush", player)
        .orElse(0);

Check participation:

boolean participating = eventService.isParticipating("mining_rush", player);

Leaderboards

Get a leaderboard:

List<EventScoreEntry> leaderboard = eventService.getLeaderboard("mining_rush", 10);

Example:

for (EventScoreEntry entry : leaderboard) {
    int rank = entry.getRank();
    String name = entry.getPlayerName();
    int score = entry.getScore();
}

Multi-objective info

v1.0.1 added objective info to EventInfo.

eventService.getEventInfo("survival_rush").ifPresent(eventInfo -> {
    if (eventInfo.hasMultipleObjectives()) {
        for (EventObjectiveInfo objective : eventInfo.getObjectives()) {
            getLogger().info(objective.getId()
                    + " | type=" + objective.getType()
                    + " | weight=" + objective.getWeight());
        }
    }
});

Fields:

objective.getId();
objective.getType();
objective.getDisplayName();
objective.getWeight();
objective.isPrimary();
tip

When showing weight to players, display it as a multiplier, for example Multiplier: x1.5.

Example admin command logic

String eventId = "relic_hunt";

EventStartCheckResult result = eventService.getStartCheckResult(eventId);

if (result.hasFailed()) {
    sender.sendMessage("Cannot start " + eventId + ": " + result.getReason());
    return;
}

boolean started = eventService.startEvent(eventId, sender);

if (started) {
    sender.sendMessage("Started " + eventId + ".");
}

Common mistakes

Starting without checkingโ€‹

This works:

eventService.startEvent("mining_rush");

But for menus and admin tools, this is better:

EventStartCheckResult result = eventService.getStartCheckResult("mining_rush");

That lets you show a useful reason when the event cannot start.

Forgetting cooldownsโ€‹

If an event cannot start, check:

eventService.isEventOnCooldown(eventId);

Assuming every event has multiple objectivesโ€‹

Some events still use the old single-objective format.

Check:

eventInfo.hasMultipleObjectives();

or safely loop:

eventInfo.getObjectives();

Using internal classesโ€‹

Do not cast API objects to internal EventForge classes.

Use the public API methods only.