Skip to main content

✨ Features

EventForge is a server events framework for Spigot, Paper, and Purpur servers.

It can be used as a ready-to-play events plugin, or as a framework for event packs, addon objectives, custom actions, and developer integrations.

Core features

Config-driven events
Built-in objectives
Event packs
Schedules
Conditions
Cooldowns
Rewards
Chance rewards
Leaderboards
Bossbars
Sidebars
Titles
Actionbars
Text effects
Animated titles
Animated actionbars
Animated bossbar text
Event milestones
PlaceholderAPI support
Developer API
Addon support
Skript addon support

Supported platforms

EventForge v1.0.2 supports:

Spigot 1.21 - 1.21.11
Paper 1.21 - 1.21.11
Purpur 1.21 - 1.21.11

Java 21 is recommended.

Config-driven events

Events are configured through YAML files.

A normal event can include:

id
display name
duration
metadata
variables
schedule
cooldown
conditions
objectives
milestones
rewards
bossbar
sidebar
messages
announcements
triggers
dialogues

This keeps events easy to edit, share, and expand.

Built-in objectives

EventForge includes several built-in objective types.

MINE_BLOCKS
KILL_MOBS
FISH_ITEMS
COLLECT_ITEMS
MOB_INVASION
CAPTURE_ZONE
VISIT_REGIONS
INTERACT_BLOCKS

These can be used to create events such as:

Mining Rush
Mob Hunt
Fishing Frenzy
Collection Rush
Mob Invasion
Capture Zone
Exploration Hunt
Interact Blocks Hunt

Custom addons can also register their own objective types.

Multi-objective events

Events can use one objective or several objectives at the same time.

Example:

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 single-objective format still works:

objective:
  type: MINE_BLOCKS
tip

Use multi-objective events for larger server-wide competitions where players can score in different ways.

Event variables

Event variables let you reuse values across an event file.

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 help keep larger event files cleaner and easier to edit.

Text effects

EventForge includes no-resource-pack text effects.

Example:

title: "<gradient:#22d3ed:#ffffff>{event_display}</gradient>"

Common effects include:

<rainbow>Text</rainbow>
<gradient:#22d3ed:#ffffff>Text</gradient>
<pulse:#22d3ed:#ffffff>Text</pulse>
<shimmer:#22d3ed:#ffffff>Text</shimmer>
<wobble:#22d3ed:#ffffff>Text</wobble>
<jump:#22d3ed:#ffffff>Text</jump>
<stack:rainbow,wobble>Text</stack>

Text effects can be used in titles, actionbars, bossbars, messages, triggers, milestones, and addon actions that use EventForge parsing.

Animated titles and actionbars

Events can show animated title and actionbar sequences.

triggers:
  event-start:
    actions:
      - type: ANIMATED_TITLE
        frames:
          - title: "<stack:rainbow,wobble>{event_display}</stack>"
            subtitle: "&7Get ready!"
            fade-in: 5
            stay: 40
            fade-out: 10
            interval: 5

Actionbar example:

triggers:
  player-score:
    actions:
      - type: ANIMATED_ACTIONBAR
        frames:
          - message: "<pulse:#22d3ed:#ffffff>+{score_change} points</pulse> &8| &7Total: &f{new_score}"
            duration: 30
            interval: 5

Animations are tracked and cancelled safely when events stop, reload, or the plugin disables.

Event milestones

Milestones let you run actions when players reach score thresholds.

milestones:
  enabled: true
  thresholds:
    50:
      display-name: "&e50 Points"
      once-per-player: true
      actions:
        - type: MESSAGE
          message: "&aYou reached {milestone_display}!"
        - type: SOUND
          sound: ENTITY_PLAYER_LEVELUP

Milestones are useful for:

score goals
progress rewards
server-wide announcements
mid-event feedback
bonus effects

Rewards

EventForge rewards are command-based, so they work with most server plugins.

Common reward types include:

participation rewards
leaderboard rewards
chance rewards

Example:

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

  leaderboard:
    1:
      commands:
        - "give {player} diamond 3"

Chance rewards

Chance rewards let you add optional bonus rewards.

chance-rewards:
  rare_key:
    chance: 5.0
    commands:
      - "give {player} diamond 1"

They can be used for participation rewards and leaderboard rewards.

Schedules and cooldowns

Events can run on schedules:

schedule:
  enabled: true
  type: INTERVAL
  every: 1h

Events can also have cooldowns:

cooldown:
  enabled: true
  duration: 1h

Cooldowns help stop events from being started too often.

Conditions

Conditions control whether an event can start.

Examples include:

minimum players
world checks
region checks
permissions
OP/non-OP checks
Minecraft time
weather
cooldowns

This helps keep events from starting at the wrong time.

Bossbars and sidebars

Events can show progress with bossbars and sidebars.

bossbar:
  enabled: true
  text: "&b{event_display} &8| &f{time_left} &8| &eScore: {score}"
sidebar:
  enabled: true
  title: "&b&l{event_display}"
  lines:
    - "&7Score: &a{score}"
    - "&7Rank: &e#{rank}"

Bossbars can also rotate through animated text frames.

bossbar:
  animated-text:
    enabled: true
    interval: 20
    frames:
      - "<stack:rainbow,wobble>{event_display}</stack> &8| &f{time_left}"
      - "&eScore: &f{score} &8| &7Rank: &e#{rank}"

Actions and triggers

EventForge can run actions when event triggers happen.

Supported triggers include:

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

Built-in action types include:

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

Example:

triggers:
  player-score:
    actions:
      - type: ANIMATED_ACTIONBAR
        frames:
          - message: "<pulse:#22d3ed:#ffffff>+{score_change} points</pulse> &8| &f{new_score} total"
            duration: 30
            interval: 5

Mob Invasion

Mob Invasion supports wave-based invasion events.

v1.0.2 adds safer empty-area handling:

empty-area:
  pause-waves: true
  radius: 50

Players can also teleport to configured invasion events with:

/events join <event>

Webhooks

The WEBHOOK action can send event messages to external services such as Discord webhooks.

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

Webhook actions run asynchronously and do not block the main server thread.

warning

Never share real webhook URLs publicly.

Dialogues

EventForge includes a dialogue engine for NPC-style message sequences.

dialogues:
  guide_intro:
    display-name: "Guide Introduction"
    lines:
      - "&eGuide: &fWelcome, {player}."
      - "&eGuide: &fFind the hidden relics."

Dialogues can be started by addons, Skript, NPC integrations, or custom objectives.

EventForge provides the dialogue engine. It does not require one specific NPC plugin.

GUI customization

EventForge GUI titles can be customized from config.yml.

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

Current GUI layouts still use fixed 6-row menus. More layout customization can be expanded in future updates.

PlaceholderAPI support

EventForge supports PlaceholderAPI for scoreboards, TAB, menus, holograms, and other plugins.

Examples:

%eventforge_active_names%
%eventforge_next_event%
%eventforge_next_event_time%
%eventforge_event_mining_rush_active%
%eventforge_event_mining_rush_player_score%
%eventforge_event_mining_rush_player_rank%

Event packs

Event packs let you group events together.

Example:

plugins/EventForge/packs/survival-pack/
├─ pack.yml
└─ events/
   ├─ mining_rush.yml
   └─ mob_hunt.yml

This is useful for seasonal packs, server-mode packs, premium packs, and addon examples.

Developer API

EventForge provides a public API for addon developers.

The API can be used for:

reading events
starting/stopping/finishing events
reading leaderboards
reading schedules
reading stats
registering custom objectives
registering custom actions
executing EventForge actions
parsing EventForge variables
parsing text effects
starting dialogues
listening to Bukkit events
reading milestones

Maven dependency:

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

Addon examples

EventForge includes example addons for developers.

Simple Addon Example
Advanced Relic Hunt Example
EventForgeSkriptAddon

The Simple Addon shows how to read EventForge API data.

The Advanced Relic Hunt addon shows how to create a custom objective and custom action.

The Skript addon exposes EventForge features to Skript users.

Useful event ideas!

EventForge can be used for:

Mining Rush
Mob Hunt
Fishing Frenzy
Collection Rush
Mob Invasion
Capture Zones
Exploration Hunts
Interact Block Hunts
Relic Hunts
Supply Drops
Seasonal Hunts
Weekend Competitions
Economy Events
Dungeon Events
Server-wide Challenges

What to read next

Installation
Quick Links
Text Effects
Event Variables
Multi-objective Events
Rewards
Actions & Triggers
Dialogues
Maven Setup
Skript Addon