Skip to main content

🚀 EventForge v1.0.1 Release

EventForge v1.0.1 expands the plugin into a more complete event framework update.

This release adds reusable event variables, chance rewards, event cooldowns, multi-objective events, the action/trigger system, webhook actions, configurable GUI titles, NPC-style dialogues, API improvements, updated addon examples, and a much larger Skript addon.

tip

This update is focused on making EventForge easier to configure, easier to extend, and better for addon developers.

Highlights

Event variables
Chance rewards
Event cooldowns
Better API filtering
Start check reasons
Upcoming schedule API
Action and trigger system
Webhook action
Multi-objective events
GUI title customization
NPC-style dialogue system
Updated simple addon
Updated advanced addon
Updated Skript addon
Bundled Skript example scripts
API published to Maven Central

Event variables

Event configs can now define reusable variables:

variables:
  event_color: "&b"
  arena_name: "Spawn Mine"
  reward_name: "Mining Tokens"

Use them with:

{var:key}

Example:

display-name: "{var:event_color}Mining Rush"

messages:
  start:
    - "{var:event_color}&lMining Rush has started!"
    - "&7Mine blocks in &f{var:arena_name}&7."

Variables can be used in player-facing event text such as messages, rewards, bossbars, sidebars, titles, actions, dialogues, and webhooks.

Variable keys are normalised, so hyphens and underscores are treated consistently.

Chance rewards

Rewards now support optional chance-based bonus rewards.

rewards:
  participation:
    enabled: true
    minimum-score: 1
    commands:
      - "eco give {player} 100"

    chance-rewards:
      bonus_key:
        chance: 10.0
        commands:
          - "crate key give {player} event 1"

Chance rewards are supported under:

rewards.participation.chance-rewards
rewards.leaderboard.<position>.chance-rewards

Chance values are percentages.

5.0 = 5%
25.0 = 25%
100.0 = guaranteed

Chance rewards use the same reward command pipeline as normal rewards, so developer reward listeners still work.

Event cooldowns

Events can now have cooldowns.

cooldown:
  enabled: true
  duration: 1h

Cooldown behaviour:

natural event finish starts cooldown
forced stop does not start cooldown
reload/shutdown does not start cooldown
manual starts respect cooldown
scheduled starts respect cooldown
API starts respect cooldown
Skript addon starts respect cooldown through the API
cooldowns persist in cooldowns.yml

Cooldowns are stored in:

plugins/EventForge/cooldowns.yml

Better API filtering and start checks

The API now includes better event filtering and start validation.

New EventService methods include:

getEventsByCategory(String category);
getEventsWithTag(String tag);
getEventsByDifficulty(String difficulty);
getStartCheckResult(String eventId);
canStartEvent(String eventId);

EventStartCheckResult provides:

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

This is useful for:

custom GUIs
Discord bots
event browsers
admin dashboards
setup tools
start buttons

Upcoming schedule API

ScheduleService now includes:

getUpcomingEvents(int limit);

This lets addons and dashboards show several upcoming scheduled events instead of only the next one.

Action and trigger system

v1.0.1 expands the action and trigger system.

Supported triggers:

event-start
event-finish
event-stop
player-score

Built-in action types:

BROADCAST
MESSAGE
TITLE
ACTIONBAR
SOUND
COMMAND
EFFECT
PARTICLE
FIREWORK
WEBHOOK

Example:

triggers:
  event-start:
    actions:
      - type: BROADCAST
        message: "&b{event_display} has started!"

  player-score:
    actions:
      - type: ACTIONBAR
        message: "&a+{score_change} points &8| &f{new_score} total"

Webhook action

The new WEBHOOK action can send HTTP POST messages asynchronously.

triggers:
  event-start:
    actions:
      - type: WEBHOOK
        url: "https://discord.com/api/webhooks/..."
        username: "EventForge"
        message: "**{event_display}** has started!"

Webhook safety improvements include:

HTTPS-only URLs
async execution
main thread is not blocked
Discord message length cap
username length cap
webhook URL is not printed in logs
placeholder support
{var:key} support
warning

Do not share real webhook URLs in public configs, screenshots, template packs, or support messages.

Custom action API

Developers can now register custom actions.

EventForgeAPI.getActionRegistry().register("DISCORD_LOG", (action, context) -> {
    String message = action.getString("message", "{event_display} started!");
    String parsed = context.parsePlaceholders(message);

    Bukkit.getLogger().info(parsed);
});

Server owners can use registered custom actions in event YAML:

triggers:
  event-start:
    actions:
      - type: DISCORD_LOG
        message: "{event_display} started!"

Custom action executor errors are caught safely so events continue running.

Multi-objective events

Events can now run multiple objectives at the same time.

objectives:
  mining:
    type: MINE_BLOCKS
    weight: 1.0

  mobs:
    type: KILL_MOBS
    weight: 1.5

  fishing:
    type: FISH_ITEMS
    weight: 1.0

All objectives contribute to the same event score and leaderboard.

The old format still works:

objective:
  type: MINE_BLOCKS

Objective weight acts like a score multiplier.

Player-facing displays should show:

Multiplier: x1.5

not:

Weight: 1.5

Multi-objective developer API

Custom objective developers now have access to:

EventObjectiveSession#getObjectiveId();
EventObjectiveSession#getObjectiveDisplayName();
EventObjectiveSession#getObjectiveWeight();
EventObjectiveSession#getWeightedScore(int amount);

EventInfo also exposes objective data:

EventInfo#getObjectives();
EventInfo#hasMultipleObjectives();

Custom objectives should use the public EventObjectiveSession API and should not cast sessions to internal classes.

GUI config updates

GUI title customization is now available in config.yml.

gui:
  enabled: true
  rows: 6

  titles:
    player-main: "&b&lEventForge"
    player-active: "&b&lActive Events"
    admin-main: "&c&lEventForge Admin"

Implemented in v1.0.1:

GUI titles can be customized
colour codes are supported
configured titles are respected by GUI listeners
GUI config reloads through EventForge reload
hardcoded title constants remain as fallbacks

Current limitation:

GUI layouts still use fixed 6-row menus.
gui.rows is reserved for a future layout update.

Dialogue system

v1.0.1 adds an NPC-style dialogue engine.

dialogues:
  guide_intro:
    npc-id: "guide"
    display-name: "Guide Introduction"
    cancel-existing: true
    lines:
      - speaker: "&eGuide"
        text: "&fHello {player}."
        title: "&eGuide"
        subtitle: "&fWelcome."
        sound: ENTITY_VILLAGER_AMBIENT
        delay: 3

Simple line format is also supported:

dialogues:
  guide_intro:
    lines:
      - "&eGuide: &fHello there!"
      - "&eGuide: &fBring me 5 relics."

EventForge provides the dialogue engine. Addons, Skript, NPC plugins, or custom objectives decide when to start a dialogue.

Dialogue API

New public API:

DialogueLineInfo
DialogueSequenceInfo
DialogueSessionInfo
DialogueService
EventForgeAPI#getDialogueService()

Common usage:

EventForgeAPI.getDialogueService()
        .startEventDialogue(player, "relic_hunt", "guide_intro")
        .thenAccept(session -> {
            if (session.isCompleted()) {
                // Move player to next task.
            }
        });

New Bukkit events:

EventForgeDialogueCompleteEvent
EventForgeDialogueCancelEvent

PlaceholderAPI additions

v1.0.1 adds placeholders for variables, cooldowns, filtering, and start checks.

Examples:

%eventforge_event_variable_<event>_<variable>%
%eventforge_event_on_cooldown_<event>%
%eventforge_event_cooldown_<event>%
%eventforge_events_category_count_<category>%
%eventforge_events_tag_count_<tag>%
%eventforge_events_difficulty_count_<difficulty>%
%eventforge_event_can_start_<event>%
%eventforge_event_start_reason_<event>%

API published to Maven Central

The EventForge API is available from Maven Central.

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

Simple addon update

The Simple Addon has been updated to v1.0.1.

It now demonstrates:

EventService cooldown checks
event start check reasons
category/tag/difficulty filtering
upcoming schedules
event variables
multi-objective inspection
registered action listing
dialogue Bukkit events
player-facing multiplier display

The package structure was cleaned into:

command
listener
util

Advanced addon update

The Advanced Relic Hunt addon has been updated to v1.0.1.

It now demonstrates:

custom RELIC_HUNT objective
custom RELIC_LOG action
multi-objective sessions
weighted score display
DialogueService usage
variables
cooldowns
triggers
built-in actions
custom actions
chance rewards

The package structure was cleaned into:

action
objective
model
util

Skript addon update

EventForgeSkriptAddon has been updated to v1.0.1.

New effects:

clear eventforge cooldown of event %string%
start eventforge dialogue %string% of event %string% for %player%
cancel eventforge dialogue for %player%

New expression groups:

cooldowns
start checks
event variables
metadata filtering
upcoming schedules
multi-objective info
dialogues

The addon now depends on:

dev.hxze:eventforge-api:1.0.1-release

Skript example scripts

The Skript addon now includes ready-to-use example scripts under:

example-scripts/

Included scripts:

eventforge-player-status.sk
eventforge-admin-tools.sk
eventforge-leaderboard.sk
eventforge-event-browser.sk
eventforge-upcoming-events.sk
eventforge-dialogues.sk
eventforge-custom-rewards.sk
eventforge-multi-objective.sk
README.txt

These can be copied into:

plugins/Skript/scripts/

Notes for upgrading

Existing v1.0.0 event files should continue to work.

You can keep using:

objective:
  type: MINE_BLOCKS

or move to:

objectives:
  mining:
    type: MINE_BLOCKS

when you want multi-objective events.

Recommended upgrade steps:

Update EventForge jar
Restart the server
Check console for validation warnings
Add cooldowns only where needed
Add variables to simplify large configs
Move new events to objectives: format
Update addon examples to 1.0.1-release API
Update Skript addon if you use Skript integration

Related docs

Event Variables
Multi-objective Events
Rewards
Schedules & Conditions
Actions & Triggers
Dialogues
GUI Customization
PlaceholderAPI
Maven Setup
Action Registry
Dialogue Service
Simple Addon Example
Advanced Relic Hunt Example
Skript Addon
Skript Example Scripts