Skip to main content

🧰 Simple Addon Example

The Simple Addon is a small developer example showing how another plugin can hook into EventForge and read public API data.

It is meant to stay simple. Use this example when you want to learn the API without registering custom objectives or custom actions.

Requirements

Java 21
Spigot, Paper, or Purpur 1.21 - 1.21.11
EventForge v1.0.2+
EventForge API 1.0.2-release

What it demonstrates

The addon demonstrates:

checking whether EventForgeAPI is available
reading loaded events
reading active events
reading event packs
reading schedules
reading objectives
reading registered actions
reading player stats
reading leaderboards
parsing EventForge variables
parsing EventForge text effects
reading event milestones
listening to EventForge Bukkit events

For custom objectives and custom actions, use the Advanced Relic Hunt example instead.

Maven dependency

The addon uses the EventForge API as a provided dependency.

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

For Spigot compatibility, it also uses the Spigot API:

<dependency>
    <groupId>org.spigotmc</groupId>
    <artifactId>spigot-api</artifactId>
    <version>1.21.11-R0.1-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>

plugin.yml

The addon depends on EventForge.

name: EventForgeSimpleExample
version: '1.0.2'
main: dev.hxze.eventforgesimpleexample.EventForgeSimpleExamplePlugin
api-version: '1.21'
author: HxZe
description: Simple example addon demonstrating EventForge v1.0.2 API services, variables, text effects, milestones, cooldowns, schedules, objectives, and Bukkit events.
depend:
  - EventForge

commands:
  efsimple:
    description: Simple EventForge API example command.
    usage: /efsimple
    aliases:
      - efs

Main command

The addon provides one command:

/efsimple

Running it without arguments shows the available examples.

Commands included

/efsimple info
/efsimple events
/efsimple active
/efsimple leaderboard <event>
/efsimple packs
/efsimple schedules
/efsimple upcoming
/efsimple objectives
/efsimple eventobjectives <event>
/efsimple actions
/efsimple texteffects <text>
/efsimple parse <event> <text>
/efsimple variables <event>
/efsimple milestones <event>
/efsimple metadata <event>
/efsimple filter <category|tag|difficulty> <value>
/efsimple canstart <event>
/efsimple cooldown <event>
/efsimple stats <player>
/efsimple history

API availability check

The addon checks that EventForge is available before continuing.

if (!EventForgeAPI.isAvailable()) {
    getLogger().severe("EventForgeAPI is not available. Is EventForge installed?");
    getServer().getPluginManager().disablePlugin(this);
    return;
}

After that, it registers its command and listeners.

Reading EventForge data

The addon uses the public API services from EventForgeAPI.

EventForgeAPI.getEventService();
EventForgeAPI.getEventPackService();
EventForgeAPI.getStatsService();
EventForgeAPI.getScheduleService();
EventForgeAPI.getObjectiveService();
EventForgeAPI.getActionRegistry();

The command examples show how to read common public data such as:

loaded event count
loaded event ids
active event ids
event metadata
event variables
configured objectives
registered objective types
registered action types
upcoming schedules
leaderboard entries
player stats
event history

Text effects example

EventForge v1.0.2 exposes TextEffectService through the public API.

The Simple Addon includes:

/efsimple texteffects <text>

Example:

/efsimple texteffects <stack:rainbow,wobble>Hello EventForge</stack>

The command demonstrates:

String parsed = EventForgeAPI.getTextEffectService()
        .parse(input, (int) (System.currentTimeMillis() / 50L));

This is useful if your addon wants to display text using the same effects as EventForge configs.

Variable parsing example

EventForge v1.0.2 also exposes VariableService.

The Simple Addon includes:

/efsimple parse <event> <text>

Example:

/efsimple parse mining_rush {var:event_color}{event_display}

The command demonstrates:

String parsed = EventForgeAPI.getVariableService()
        .parse(eventId, input);

Use this when your addon needs to parse EventForge variables from an event config or command.

Milestone example

EventForge v1.0.2 added public milestone data.

The Simple Addon includes:

/efsimple milestones <event>

Example:

/efsimple milestones mining_rush

The command reads:

EventInfo#getMilestones()
EventMilestoneInfo

It shows each configured milestone with:

milestone id
display name
threshold
once-per-player setting
action count

Bukkit event listeners

The addon listens to EventForge Bukkit events and logs simple messages to the console.

Included examples:

EventForgeEventStartEvent
EventForgeEventStopEvent
EventForgeEventFinishEvent
EventForgePlayerScoreChangeEvent
EventForgePlayerMilestoneEvent
EventForgeRewardExecuteEvent
EventForgeReloadEvent
EventForgeDialogueCompleteEvent
EventForgeDialogueCancelEvent

The v1.0.2 milestone event is also included.

@EventHandler
public void onMilestone(EventForgePlayerMilestoneEvent event) {
    plugin.getLogger().info("[EventForge Bukkit Event] Milestone reached: "
            + event.getPlayer().getName()
            + " | event="
            + event.getEventId()
            + " | milestone="
            + event.getMilestone().getId()
            + " | display="
            + event.getMilestone().getDisplayName()
            + " | threshold="
            + event.getMilestone().getThreshold()
            + " | score="
            + event.getNewScore());
}

Testing the addon

Install both plugins:

plugins/
├─ EventForge.jar
└─ EventForgeSimpleExample.jar

Start the server and run:

/efsimple
/efsimple info
/efsimple events
/efsimple active

Then test the v1.0.2 API examples:

/efsimple texteffects <stack:rainbow,wobble>Hello EventForge</stack>
/efsimple parse mining_rush {var:event_color}{event_display}
/efsimple milestones mining_rush

To test the milestone listener, start an event with milestones configured and give a player enough score to reach one.

/events start mining_rush
/eventforge points <player> mining_rush 50

When to use this example

Use the Simple Addon when you want a clean reference for reading EventForge data from another plugin.

It is best for learning:

how to hook into EventForge
how to read public event information
how to parse variables and text effects
how to listen to EventForge events
how to read milestone data

For a larger addon with a custom objective, custom action, milestones, dialogue integration, and animated text examples, use the Advanced Relic Hunt example.

Summary

The Simple Addon is the easiest EventForge developer example.

In v1.0.2 it now showcases:

Spigot-compatible setup
EventForge API 1.0.2-release
TextEffectService
VariableService
Event milestones
EventForgePlayerMilestoneEvent