Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

❓ 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, voting, queues, schedules, 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
whether players join automatically or through a queue
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
start from player votes
open manual participation queues
teleport queued players to a lobby
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
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 add more objective types.

Automatic or manual participation

Events can use classic automatic participation or manual queue-based participation.

Automatic events start normally and players can score without joining first.

Manual events open a timed queue before the event starts. Players join with:

/events join <event>

Manual queues can show bossbars, 3-2-1 title countdowns, optional lobby teleports, and only queued players can score once the event begins.

Fresh installs use automatic participation by default.

Player-driven event voting

EventForge includes manual and scheduled voting.

Admins can start a vote:

/eventforge vote start mining_rush mob_hunt fishing_frenzy

Players vote with:

/events vote mining_rush

Scheduled voting can also start automatic votes from schedule_config.yml.

If a winning event uses manual participation, EventForge opens the queue instead of starting the event instantly.

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"
  event_plain_name: "Mining Rush"
  arena_name: "Spawn Mine"
  reward_name: "Mining Tokens"

Then use:

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

Example:

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

Plain variables such as event_plain_name are especially useful when using optional TextEffect tags.

Visual displays

EventForge can show event information through:

chat messages
broadcasts
titles
subtitles
actionbars
bossbars
sidebars
GUI item names and lore

EventForge also includes built-in no-resource-pack text effects.

If the separate TextEffect plugin is installed and enabled, supported EventForge display areas can use TextEffect shader-powered tags as well.

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.

Scheduled voting is configured globally in schedule_config.yml, because it chooses from multiple event templates rather than belonging to one event file.

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
read and control event votes
read scheduled votes
read and join event queues
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.3-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
Event Voting
Manual Event Queues
Schedules & Conditions

If you are a developer, start with:

Maven Setup
API Overview
Bukkit Events
EventVoteService
ScheduledVoteService
EventQueueService
Custom Objectives
Action Registry

If you use Skript, start with:

Skript Addon
Skript Example Scripts