Skip to main content

๐Ÿ“– API Overview

EventForge provides a public API for addon developers.

You can use it to:

read loaded events
start, stop, and finish events
check whether events can start
read leaderboards
read player stats
read schedules
register custom objectives
register custom actions
execute EventForge actions
parse EventForge variables
parse text effects
start dialogues
listen to EventForge Bukkit events
read event milestones

Accessing the API

Use:

EventForgeAPI

Example:

import dev.hxze.eventforge.api.EventForgeAPI;

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

API version

You can check the API version:

String version = EventForgeAPI.getApiVersion();

For EventForge v1.0.2, this returns:

1.0.2-release

Main services

EventForge exposes these public services:

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

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

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 milestones

v1.0.2 added public milestone data.

EventForgeAPI.getEventService()
        .getEventInfo("mining_rush")
        .ifPresent(eventInfo -> {
            eventInfo.getMilestones().forEach(milestone -> {
                String id = milestone.getId();
                String display = milestone.getDisplayName();
                int threshold = milestone.getThreshold();
            });
        });

Useful classes:

EventMilestoneInfo
EventForgePlayerMilestoneEvent

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 schedule data.

ScheduleService scheduleService = EventForgeAPI.getScheduleService();

Common uses:

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

ObjectiveService

Use ObjectiveService to read registered objective types.

ObjectiveService objectiveService = EventForgeAPI.getObjectiveService();

Example:

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

ObjectiveRegistry

Use ObjectiveRegistry to register custom objective handlers.

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.

Protected built-in objectives:

MINE_BLOCKS
KILL_MOBS
FISH_ITEMS
COLLECT_ITEMS
MOB_INVASION
CAPTURE_ZONE
VISIT_REGIONS
INTERACT_BLOCKS

ActionRegistry

Use ActionRegistry to register custom action types.

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

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

Protected built-in actions include:

BROADCAST
MESSAGE
TITLE
ACTIONBAR
SOUND
COMMAND
EFFECT
PARTICLE
FIREWORK
WEBHOOK
ANIMATED_TITLE
ANIMATED_ACTIONBAR

ActionService

v1.0.2 added the public ActionService.

Use it when your addon wants to execute EventForge actions from its own systems.

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

This is useful for custom objectives that load configured action sections.

VariableService

v1.0.2 added the public VariableService.

Use it to parse EventForge variables such as:

{var:event_color}

Example:

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

Player-aware parsing:

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

TextEffectService

v1.0.2 added the public TextEffectService.

Use it to parse EventForge text effects.

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

Animated parsing:

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

DialogueService

Use DialogueService to start EventForge dialogues.

EventForgeAPI.getDialogueService()
        .startEventDialogue(player, "relic_hunt", "guide_intro")
        .thenAccept(session -> {
            if (session.isCompleted()) {
                // Dialogue finished.
            }
        });

Dialogues can be used by custom objectives, NPC integrations, quest plugins, or Skript integrations.

Bukkit events

EventForge also exposes Bukkit events.

Common events include:

EventForgeEventStartEvent
EventForgeEventStopEvent
EventForgeEventFinishEvent
EventForgePlayerScoreChangeEvent
EventForgePlayerMilestoneEvent
EventForgeReloadEvent

Example:

@EventHandler
public void onEventStart(EventForgeEventStartEvent event) {
    getLogger().info("Event started: " + event.getEventId());
}

Custom objective flow

A custom objective usually needs:

objective data class
objective handler class
objective registration
optional event template

Basic registration:

@Override
public void onEnable() {
    if (!EventForgeAPI.isAvailable()) {
        getServer().getPluginManager().disablePlugin(this);
        return;
    }

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

Custom action flow

A custom action usually needs:

action type ID
action executor
registration on enable
unregister on disable

Basic registration:

EventForgeAPI.getActionRegistry().register("MY_ACTION", (action, context) -> {
    String message = action.getString("message", "Hello from my addon!");
    context.getPlayer().ifPresent(player -> player.sendMessage(message));
});

Null safety

Public EventForge API objects are designed to be safe for addon usage.

Still, addons should always check:

API availability
Optional results
player presence
event loaded state
event active state

Example:

EventForgeAPI.getEventService()
        .getEventInfo("mining_rush")
        .ifPresent(eventInfo -> {
            // Safe to use eventInfo here.
        });

Summary

Use EventForgeAPI as the main entry point.

For most addons, the most common services are:

EventForgeAPI.getEventService();
EventForgeAPI.getObjectiveRegistry();
EventForgeAPI.getActionRegistry();
EventForgeAPI.getActionService();
EventForgeAPI.getVariableService();
EventForgeAPI.getTextEffectService();
EventForgeAPI.getDialogueService();