🪄 Event Packs

Event packs are drag-and-drop folders that contain multiple EventForge events.

They are useful for server owners, event pack creators, and developers who want to organise events into themed collections.

What is an event pack?

An event pack is a folder inside:

plugins/EventForge/packs/

Example:

plugins/EventForge/packs/EasterPack/
├─ pack.yml
└─ events/
   ├─ easter_egg_hunt.yml
   └─ bunny_hunt.yml

Each pack can contain one or more event files.

Why use event packs?

Event packs make it easy to:

install themed event collections
sell or share premium event expansions
separate events by category
disable entire packs without deleting files
keep the main events/ folder clean
create seasonal server content
create reusable event bundles
allow other creators to build for EventForge

Example packs:

Halloween Events Pack
Christmas Events Pack
Prison Events Pack
Boss Waves Pack
Survival Events Pack
Fishing Events Pack
Mining Events Pack
RPG Events Pack

Pack folder structure

A pack should follow this structure:

plugins/EventForge/packs/
└─ MyPack/
   ├─ pack.yml
   └─ events/
      ├─ first_event.yml
      └─ second_event.yml

The folder name can be friendly, such as:

HalloweenPack
ChristmasPack
PrisonPack

`pack.yml`

Every pack needs a pack.yml file.

Example:

id: halloween_pack
display-name: "&6Halloween Events Pack"
enabled: true
author: "HxZe"
version: "1.0.0"

Pack settings

Setting	Description
`id`	Internal pack ID
`display-name`	Display name shown in logs/menus
`enabled`	Whether the pack should load
`author`	Pack creator
`version`	Pack version

Enabling or disabling a pack

To enable a pack:

enabled: true

To disable a pack:

enabled: false

When a pack is disabled, EventForge will not load any event files inside that pack.

Event files inside packs

Pack events go inside:

plugins/EventForge/packs/<PackName>/events/

Example:

plugins/EventForge/packs/HalloweenPack/events/pumpkin_hunt.yml

Each event file still needs:

enabled: true

If the event has:

enabled: false

it will not load, even if the pack itself is enabled.

Loading rules

EventForge loads events from:

plugins/EventForge/events/

and also from:

plugins/EventForge/packs/<PackName>/events/

Pack events are loaded only when:

the pack has a valid pack.yml
the pack has enabled: true
the event file has enabled: true
the event YAML is valid
the objective type exists
any required custom objective addon is installed
any optional custom content provider used by the event is installed

Event metadata inside packs

EventForge supports optional event metadata.

This is especially useful for event packs because it lets pack creators describe, categorise, and organise their events.

Example:

metadata:
  category: "Mining"
  tags:
    - mining
    - survival
    - economy
  difficulty: "Easy"
  author: "HxZe"
  version: "1.0.0"
  description:
    - "Mine configured blocks to earn points."
    - "Compete for leaderboard rewards."

Metadata fields

Field	Description
`category`	Main event category
`tags`	Search/filter tags for menus, bots, dashboards, and docs
`difficulty`	Friendly difficulty label
`author`	Event or pack creator
`version`	Event/template version
`description`	Description lines for menus, docs, Discord embeds, or dashboards

Why metadata is useful

Metadata can be used by:

custom event browsers
admin GUIs
Discord bots
web dashboards
public APIs
PlaceholderAPI
future event pack marketplaces
documentation pages
custom addon plugins

Example uses:

Show all events tagged "mining"
Display only "Hard" events in a menu
Post event descriptions to Discord
List all events made by a specific pack author
Create event category filters

EventPackService API

Developers can read event pack information using the public EventForge API.

Example:

EventPackService packService = EventForgeAPI.getEventPackService();

for (EventPackInfo pack : packService.getPacks()) {
    Bukkit.getLogger().info(pack.getId()
            + " by "
            + pack.getAuthor()
            + " - events: "
            + pack.getEventFileCount());
}

This is useful for:

event pack browsers
custom GUIs
Discord integrations
dashboards
admin panels
pack management addons

Example pack

plugins/EventForge/packs/SurvivalPack/
├─ pack.yml
└─ events/
   ├─ mining_rush.yml
   ├─ fishing_frenzy.yml
   └─ mob_hunt.yml

pack.yml:

id: survival_pack
display-name: "&aSurvival Events Pack"
enabled: true
author: "HxZe"
version: "1.0.0"

events/mining_rush.yml:

id: survival_mining_rush
enabled: true
display-name: "&aSurvival Mining Rush"
duration: 10m

metadata:
  category: "Survival"
  tags:
    - mining
    - survival
    - economy
  difficulty: "Easy"
  author: "HxZe"
  version: "1.0.0"
  description:
    - "Mine ores and valuable blocks for points."
    - "Compete against other players for rewards."

schedule:
  enabled: false

conditions:
  minimum-players: 1
  worlds:
    - world

  permissions: []
  blocked-permissions: []

  require-op: false
  require-non-op: false

  time:
    enabled: false
    min: 0
    max: 23999

  weather:
    allowed: []

objective:
  type: MINE_BLOCKS
  display-name: "Mine valuable blocks"
  display-items:
    - "Mine ores for points"

Duplicate event IDs

Every event ID should be unique.

Bad:

id: mining_rush

in multiple packs.

Better:

id: halloween_mining_rush

or:

id: survival_mining_rush

Duplicate event IDs can cause one event to override or conflict with another.

Custom content in event packs

Event packs can include optional custom content support.

For example, a Halloween pack might use:

custom ItemsAdder items
custom Oraxen items
custom Nexo items
custom MMOItems items
MythicMobs bosses or invasion mobs

warning

EventForge does not require these plugins by default.

If a pack uses optional custom content, the required custom content plugin must be installed and enabled on the server.

Example custom item section:

custom-items:
  relic_coin:
    provider: ITEMSADDER
    id: eventforge:relic_coin
    points: 10
    display-name: "&eRelic Coin"

Example custom mob section:

custom-mobs:
  skeleton_king:
    provider: MYTHICMOBS
    id: SkeletonKing
    points: 50
    display-name: "&6Skeleton King"

Missing provider warnings

EventForge includes clearer validation warnings for optional providers.

If an event pack uses a provider that is not installed, EventForge will warn you during load/reload.

Example:

Custom item provider ITEMSADDER is used, but ItemsAdder is not installed or enabled.

Fix it by either:

installing the required provider plugin
removing the custom content section
commenting out the custom content section
using vanilla items/mobs instead

Installing an event pack

To install an event pack:

Stop the server.
Upload the pack folder into:

plugins/EventForge/packs/

Make sure the pack contains pack.yml.
Make sure the pack has an events/ folder.
Start the server.
Run:

/eventforge reload

Check:

/eventforge list

Reload summary

After running:

/eventforge reload

EventForge displays a summary showing how many events were loaded, warnings, and errors.

This helps diagnose broken packs quickly.

Example:

Loaded events: 5 | Warnings: 0 | Errors: 0

Best practices for pack creators

Use clear IDs:

id: halloween_pumpkin_hunt

Use metadata:

metadata:
  category: "Seasonal"
  tags:
    - halloween
    - collection
    - seasonal
  difficulty: "Easy"

Use safe condition defaults:

conditions:
  minimum-players: 1
  worlds:
    - world

  permissions: []
  blocked-permissions: []

  require-op: false
  require-non-op: false

  time:
    enabled: false
    min: 0
    max: 23999

  weather:
    allowed: []

Use comments for optional custom content:

# Optional custom item support.
# Requires ItemsAdder.
custom-items:
  relic_coin:
    provider: ITEMSADDER
    id: eventforge:relic_coin
    points: 10
    display-name: "&eRelic Coin"

Summary

Event packs are the best way to organise and distribute themed EventForge content.

They can contain vanilla events, custom-content events, metadata, schedules, advanced conditions, and custom objective addon events.

What is an event pack?​

Why use event packs?​

Pack folder structure​

pack.yml​

Pack settings​

Enabling or disabling a pack​

Event files inside packs​

Loading rules​

Event metadata inside packs​

Metadata fields​

Why metadata is useful​

EventPackService API​

Example pack​

Duplicate event IDs​

Custom content in event packs​

Missing provider warnings​

Installing an event pack​

Reload summary​

Best practices for pack creators​

Summary​

What is an event pack?

Why use event packs?

Pack folder structure

`pack.yml`

Pack settings

Enabling or disabling a pack

Event files inside packs

Loading rules

Event metadata inside packs

Metadata fields

Why metadata is useful

EventPackService API

Example pack

Duplicate event IDs

Custom content in event packs

Missing provider warnings

Installing an event pack

Reload summary

Best practices for pack creators

Summary