Skip to main content

📖 API Overview

EventForge provides a public API for addon developers.

Use it to read EventForge state, start or stop events, register custom objectives, execute actions, parse variables, work with schedules, react to Bukkit events, and integrate with the newer v1.0.3 systems such as event voting, scheduled voting and manual event queues.

Add EventForge as a dependency

Addon plugins should depend on the EventForge API module.

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

Use provided because EventForge is supplied by the server at runtime.

plugin.yml

Your addon should softdepend or depend on EventForge.

softdepend:
  - EventForge

Use depend instead if your plugin cannot run without EventForge:

depend:
  - EventForge

Accessing the API

Use:

EventForgeAPI

Example:

import dev.hxze.eventforge.api.EventForgeAPI;

if (!EventForgeAPI.isAvailable()) {
    getLogger().warning("EventForge API is not available yet.");
    return;
}

Always check EventForgeAPI.isAvailable() before using services during startup or reload-sensitive logic.

API version

You can check the API version:

String version = EventForgeAPI.getApiVersion();

For EventForge v1.0.3, this returns:

1.0.3-release

Main services

EventForge exposes these 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();

EventService

Use EventService to read and control events.

EventService eventService = EventForgeAPI.getEventService();

Common uses:

eventService.getLoadedEvents();
eventService.getActiveEvents();
eventService.getEventInfo("mining_rush");
eventService.isEventLoaded("mining_rush");
eventService.isEventActive("mining_rush");
eventService.canStartEvent("mining_rush");
eventService.startEvent("mining_rush");
eventService.stopEvent("mining_rush");
eventService.finishEvent("mining_rush");

Winning votes and manual queues still use EventForge's normal event start flow, so event checks remain consistent across commands, schedules and API calls.

EventInfo

EventInfo contains public information about an event.

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

It can include:

event id
display name
duration
active state
metadata
variables
objectives
milestones

Event voting API

v1.0.3 adds EventVoteService.

Use it to read active vote state, start votes, cast votes, cancel votes and confirm pending winners.

EventVoteService voteService = EventForgeAPI.getEventVoteService();

Common uses:

voteService.isVotingEnabled();
voteService.isVoteActive();
voteService.getActiveVote();
voteService.getActiveVoteOptionIds();
voteService.startVote(sender, List.of("mining_rush", "mob_hunt"));
voteService.castVote(player, "mining_rush");
voteService.cancelVote(sender);
voteService.confirmWinner(sender);

See the EventVoteService page for full examples.

Scheduled voting API

v1.0.3 adds ScheduledVoteService.

Use it to read scheduled vote definitions loaded from schedule_config.yml.

ScheduledVoteService scheduledVoteService = EventForgeAPI.getScheduledVoteService();

Common uses:

scheduledVoteService.isScheduledVotingEnabled();
scheduledVoteService.getScheduledVotes();
scheduledVoteService.getScheduledVote("hourly_vote");
scheduledVoteService.getNextScheduledVote();
scheduledVoteService.getUpcomingScheduledVotes(5);
scheduledVoteService.getSecondsUntilNextVote("hourly_vote");

See the ScheduledVoteService page for full examples.

Event queue API

v1.0.3 adds EventQueueService.

Use it to read and interact with manual event queues.

EventQueueService queueService = EventForgeAPI.getEventQueueService();

Common uses:

queueService.isQueueActive();
queueService.getFirstQueue();
queueService.getQueue("mining_rush");
queueService.getQueues();
queueService.getQueuedEventIds();
queueService.isPlayerQueued(player.getUniqueId(), "mining_rush");
queueService.joinQueue(player, "mining_rush");
queueService.leaveQueue(player, "mining_rush");

See the EventQueueService page for full examples.

StatsService

Use StatsService to read player stats.

StatsService statsService = EventForgeAPI.getStatsService();

Common uses:

statsService.getPlayerStats(playerUuid);
statsService.getEventStats(playerUuid, "mining_rush");

ScheduleService

Use ScheduleService to read normal EventForge event schedule data.

ScheduleService scheduleService = EventForgeAPI.getScheduleService();

Common uses:

scheduleService.getScheduledEvents();
scheduleService.getNextScheduledEvent();

For scheduled voting, use ScheduledVoteService instead.

ObjectiveService and ObjectiveRegistry

Use ObjectiveService to read registered objective types.

ObjectiveService objectiveService = EventForgeAPI.getObjectiveService();
Set<String> objectiveTypes = objectiveService.getRegisteredObjectiveTypes();

Use ObjectiveRegistry to register custom objective handlers.

ObjectiveRegistry registry = EventForgeAPI.getObjectiveRegistry();

Custom objectives should register during addon startup after confirming the EventForge API is available.

Action services

Use ActionRegistry to register custom actions.

Use ActionService to execute EventForge actions from addon code.

ActionRegistry actionRegistry = EventForgeAPI.getActionRegistry();
ActionService actionService = EventForgeAPI.getActionService();

VariableService

Use VariableService to parse EventForge variables.

String parsed = EventForgeAPI.getVariableService()
        .parse(player, "Current event: {event_display}");

This is useful for addon messages, custom menus, external dashboards and command output.

TextEffectService

Use TextEffectService for EventForge's built-in text effect parsing.

String parsed = EventForgeAPI.getTextEffectService()
        .parse("<rainbow>Event Started</rainbow>");

This is EventForge's public text effect service. It is separate from the optional TextEffect plugin integration used by EventForge displays.

Bukkit events

EventForge exposes Bukkit events for addons.

Important event groups include:

event lifecycle events
score change events
milestone events
reward events
reload events
manual vote events
scheduled vote events
manual queue events
dialogue events

See the Bukkit Events page for examples.

Snapshot safety

v1.0.3 keeps the public API snapshot-based.

Addon developers receive immutable public info objects such as:

EventInfo
EventVoteInfo
ScheduledVoteInfo
EventQueueInfo
EventMilestoneInfo
EventHistoryInfo

The API does not expose internal runtime objects such as active vote sessions, queued event objects, scheduler tasks or mutable maps.

This keeps EventForge safe while still allowing useful integrations.

Good addon pattern

A simple safe pattern:

if (!EventForgeAPI.isAvailable()) {
    getLogger().warning("EventForge is not ready yet.");
    return;
}

EventForgeAPI.getEventService()
        .getEventInfo("mining_rush")
        .ifPresent(eventInfo -> {
            getLogger().info("Loaded EventForge event: " + eventInfo.getDisplayName());
        });

Avoid storing live assumptions forever. EventForge can reload, events can change, and queues/votes are runtime state. Read fresh snapshots when you need current information.