❓ What is EventForge?

EventForge is a configurable event framework for Minecraft servers.

It lets server owners create timed server events through YAML files, while also giving developers a public API for custom objectives, actions, dialogues, addons, and integrations.

The simple idea

Instead of coding a separate plugin for every event, EventForge gives you one framework.

You create event files like:

mining_rush.yml
mob_hunt.yml
fishing_frenzy.yml
relic_hunt.yml
seasonal_event.yml

Each event file controls things like:

how long the event lasts
how players score
what rewards are given
when the event starts
whether it has a cooldown
what messages players see
what actions run
what bossbar/sidebar is shown

Who is it for?

EventForge is useful for:

SMP servers
survival servers
prison servers
economy servers
RPG servers
seasonal event servers
small networks
server owners selling event packs
developers building EventForge addons

What can events do?

Events can:

track player scores
show bossbars and sidebars
announce results
reward participation
reward leaderboard positions
roll chance rewards
start on schedules
respect cooldowns
run conditions before starting
run actions when triggers happen
send webhooks
play dialogue sequences
store stats and history

Built-in event types

EventForge includes built-in objective types such as:

MINE_BLOCKS
KILL_MOBS
FISH_ITEMS
COLLECT_ITEMS
MOB_INVASION

These can be used to create events such as:

Mining Rush
Mob Hunt
Fishing Frenzy
Collection Rush
Mob Invasion

Custom addons can add more objective types.

One event, multiple ways to score

EventForge supports single-objective and multi-objective events.

Single-objective example:

objective:
  type: MINE_BLOCKS

Multi-objective example:

objectives:
  mining:
    type: MINE_BLOCKS
    weight: 1.0

  mobs:
    type: KILL_MOBS
    weight: 1.5

  fishing:
    type: FISH_ITEMS
    weight: 1.0

This makes it possible to create mixed events like:

Survival Rush
Dungeon Challenge
Seasonal Competition
Economy Weekend Event

Easier event configs with variables

Event variables let you reuse values inside an event file.

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

Then use:

{var:event_color}
{var:arena_name}
{var:reward_name}

Example:

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

This is useful when you want clean, reusable configs.

Actions and triggers

Events can run actions when something happens.

Example triggers:

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

Example actions:

broadcast messages
send titles
send actionbars
play sounds
run commands
spawn particles
launch fireworks
send webhooks
run custom addon actions

Example:

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

Dialogues

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

Example:

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

EventForge does not force one NPC plugin. Addons, Skript, NPC plugins, or custom objectives can decide when to start a dialogue.

Rewards

Rewards are command-based, so they work with many existing server plugins.

Example:

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

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

Chance rewards are also supported:

chance-rewards:
  rare_key:
    chance: 5.0
    commands:
      - "crate key give {player} rare 1"

Schedules and cooldowns

Events can start automatically:

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

Events can also have cooldowns:

cooldown:
  enabled: true
  duration: 1h

Cooldowns help stop larger events from being spammed or restarted too often.

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 event packs
addon examples
drag-and-drop event bundles

Developer-friendly

EventForge provides a public Java API.

Developers can:

read loaded and active events
start, stop, and finish events
read scores and leaderboards
read stats and history
read schedules
register custom objectives
register custom actions
start dialogue sequences
listen to Bukkit events

The 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>

Skript support

EventForgeSkriptAddon lets Skript users interact with EventForge.

It can be used for:

custom admin commands
event status commands
leaderboard commands
start buttons
cooldown checks
dialogue commands
simple server-specific workflows

The addon also includes ready-to-use example scripts.

A typical setup

A simple server might have:

plugins/EventForge/events/mining_rush.yml
plugins/EventForge/events/mob_hunt.yml
plugins/EventForge/events/fishing_frenzy.yml

A larger server might have:

plugins/EventForge/packs/survival/
plugins/EventForge/packs/seasonal/
plugins/EventForge/packs/economy/

A developer setup might include:

EventForge
EventForgeSimpleExample
EventForgeAdvancedExample
EventForgeSkriptAddon

What EventForge is not

EventForge is not designed to replace every plugin on your server.

It works best as an event framework that connects with your existing setup.

For example:

Use your economy plugin for money rewards
Use your crate plugin for crate keys
Use your permissions plugin for temporary groups
Use your custom item plugin for custom content
Use EventForge to run the event logic around them

Where to start

If you are a server owner, start with:

Installation
Folder Structure
Mining Rush
Rewards
Schedules & Conditions

If you are a developer, start with:

Maven Setup
API Overview
Simple Addon Example
Custom Objectives
Action Registry

If you use Skript, start with:

Skript Addon
Skript Example Scripts