Events

Events Addon

The Events addon is an optional premium add-on for X-Prison that runs server-wide, timed events — such as Payday (2× money), Token Frenzy (2× tokens) or Enchant Frenzy (+20% enchant procs). Every running event is shown to all online players as a live countdown bossbar, and fires configurable title, sound and chat notifications when it starts and ends.

Events are fully config-driven: you define each one in its own file, choose what it boosts, how long it lasts, how it looks, and how it is announced. Multiple events can run at the same time, each with its own bossbar. Events can be started manually or automatically on a schedule.

Requirements

Requirement	Notes
X-Prison	`2026.2.6.1` or newer
Java 17+	Required
Paper / Spigot / Folia	1.13 – latest (bossbars require a 1.9+ client)
PlaceholderAPI	Optional — only needed for the placeholders below
Battle Pass module	Optional — only needed for `XP_MULTIPLIER` events

Currencies: currency events reference a currency by its internal name. money and tokens exist by default; a gems event requires a gems currency to be registered in currencies.yml.

Installation

Download X-Prison-Events-*.jar from your purchase platform.
Place the JAR inside plugins/X-Prison/addons/.
Restart the server (do not use /reload).
Default config files are created at plugins/X-Prison/addons/Events/:
- events.yml — global settings, messages, bossbar defaults and the scheduler.
- events/ — one file per event (ships with payday, token-frenzy, gem-rush, enchant-frenzy, xp-boost).
Edit the files to taste, then run /events reload to apply changes without restarting.

How It Works

An event starts (manually via /events start <id>, or automatically via the scheduler).
Every online player sees a start title + sound and a chat broadcast, and a countdown bossbar appears.
While the event is active its effects apply — e.g. mining income is doubled, or enchants proc more often. The bossbar ticks down every second.
When the timer reaches zero (or an admin stops it) the event ends: an end title + sound + broadcast fire and the bossbar disappears.

Multiple events run independently and concurrently — each keeps its own bossbar and its own timer. Events are transient: they do not survive a server restart.

Included Events

Id	Effect	Default duration
`payday`	2× money from mining/selling	30 min
`token-frenzy`	2× tokens from mining	30 min
`gem-rush`	2× gems from mining	20 min
`enchant-frenzy`	+20% proc chance for all enchants	15 min
`xp-boost`	2× Battle Pass XP (all sources)	30 min

All of these are just example config files — edit, delete, or add your own freely.

Effect Types

Each event has an effects: list. An event may combine several effects (e.g. 2× money and 2× tokens at once). The available effect types are:

`type`	What it does	Key options
`CURRENCY_MULTIPLIER`	Multiplies a currency a player receives	`currency`, `multiplier`, `apply-to-causes`
`XP_MULTIPLIER`	Multiplies Battle Pass XP gains	`multiplier`, `sources`
`ENCHANT_PROC_MULTIPLIER`	Multiplies enchant trigger chances	`multiplier`, `enchants`

See Effect Reference below for the full option list of each.

Commands & Permissions

Command	Permission	Default	Description
`/events`	(optional — see `command.permission`)	All players	List running events and their time left
`/events list`	(same as above)	All players	Same as `/events`
`/events start <id>`	`xprison.events.admin`	Operators	Start an event immediately
`/events stop <id>`	`xprison.events.admin`	Operators	Stop a running event
`/events stop all`	`xprison.events.admin`	Operators	Stop every running event
`/events reload`	`xprison.events.admin`	Operators	Reload settings, messages and event definitions

Aliases: /event

The base command name, aliases and an optional view-permission are configurable under command: in events.yml. Changing the command name/aliases requires a server restart.

Configuration — `events.yml`

enabled: true

command:
  name: events
  aliases: [event]
  # Permission required to view /events. Leave empty to allow everyone.
  permission: ""

# How multiple concurrently-active events that boost the SAME dimension combine:
#   MULTIPLY -> factors multiply   (two 2x money events => 4x money)
#   HIGHEST  -> strongest applies  (two 2x money events => 2x money)
stacking: MULTIPLY

messages:
  prefix: "<gradient:#f7971e:#ffd200><bold>EVENTS</bold></gradient> <dark_gray>» </dark_gray>"
  no-permission: "<red>You don't have permission to do that."
  unknown-event: "<red>No event with id <yellow>%event%<red>."
  event-started: "<green>Started event <yellow>%event%<green>."
  event-already-active: "<red>Event <yellow>%event% <red>is already running."
  event-stopped: "<green>Stopped event <yellow>%event%<green>."
  event-not-active: "<red>Event <yellow>%event% <red>is not running."
  stopped-all: "<green>Stopped <yellow>%count% <green>active event(s)."
  reloaded: "<green>Events configuration reloaded."
  list-header: "<gray>Active events (<yellow>%count%<gray>):"
  list-active-line: "<gray>» <white>%event% <gray>- <yellow>%time% <gray>left"
  list-none: "<gray>There are no active events right now."

# Default bossbar look, used when an event file omits its own bossbar settings.
bossbar-defaults:
  color: YELLOW          # PINK, BLUE, RED, GREEN, YELLOW, PURPLE, WHITE
  style: SOLID           # SOLID, SEGMENTED_6, SEGMENTED_10, SEGMENTED_12, SEGMENTED_20

# Fallback sound played on start/end when a notification section omits its own.
default-sound: BLOCK_NOTE_BLOCK_PLING

# Automatic event scheduler.
scheduler:
  enabled: false
  mode: ROTATION           # ROTATION | SEQUENTIAL | OFF
  interval: 3600           # seconds between automatic starts
  min-online-players: 1    # don't auto-start below this many players online
  prevent-duplicates: true # never auto-start an event that is already running
  events-per-interval: 1   # how many distinct events to start each interval
  pool: []                 # events eligible for auto-start; empty = every enabled event

Key options

Option	Description
`enabled`	Master switch. `false` disables the whole addon
`command.name` / `command.aliases`	The command label and its aliases (restart to change)
`command.permission`	Permission to run `/events`. Empty = everyone can view the list
`stacking`	How concurrent events on the same dimension combine — `MULTIPLY` or `HIGHEST`
`messages.*`	All player-facing text (raw MiniMessage; `prefix` is prepended automatically)
`bossbar-defaults.color` / `.style`	Fallback bossbar look when an event omits its own
`default-sound`	Fallback sound name (Bukkit/XSeries sound) for notifications
`scheduler.*`	The automatic scheduler — see Automatic Scheduler

All text uses MiniMessage formatting.

Creating an Event

Every file in the events/ folder defines one event. The file name is the event id unless you set id: explicitly. Here is the full annotated structure (events/payday.yml):

id: payday                 # unique id (defaults to the file name)
display-name: "<gold>Payday"
enabled: true
duration: 1800             # seconds
weight: 10                 # relative chance when the scheduler is in ROTATION mode

bossbar:
  color: YELLOW
  style: SOLID
  # Placeholders: %name%  %multiplier%  %time%
  # MiniMessage is supported, including <gradient:...> which renders as true RGB on the bar.
  title: "<gradient:#f7971e:#ffd200><bold>Payday</bold></gradient> <white>(%multiplier%x Money) <gray>(%time%)"

effects:
  - type: CURRENCY_MULTIPLIER
    currency: money
    multiplier: 2.0
    apply-to-causes: [MINING, MINING_OTHERS]   # empty = all causes

notifications:
  start:
    title:
      enabled: true
      title: "<gold><bold>PAYDAY!"
      subtitle: "<white>Earn <yellow>2x Money <white>for 30 minutes"
      fade-in: 1
      stay: 3
      fade-out: 1
    sound:
      enabled: true
      sound: ENTITY_PLAYER_LEVELUP
      volume: 1.0
      pitch: 1.0
    broadcast: "<gold>Payday has begun! <white>Earn <yellow>2x Money <white>for the next 30 minutes!"
  end:
    title:
      enabled: true
      title: "<gray>Payday ended"
      subtitle: ""
    sound:
      enabled: true
      sound: BLOCK_NOTE_BLOCK_BASS
    broadcast: "<gray>Payday has ended. Thanks for playing!"

Event fields

Field	Description
`id`	Unique event id used in commands and placeholders (defaults to the file name)
`display-name`	Name shown in `/events list` and the `%name%` placeholder (MiniMessage)
`enabled`	`false` hides the event from commands and the scheduler
`duration`	Length of the event in seconds
`weight`	Relative pick chance in the scheduler's `ROTATION` mode (higher = more likely)
`bossbar.color` / `.style`	Bossbar appearance (falls back to `bossbar-defaults`)
`bossbar.title`	Bossbar title template — supports `%name%`, `%multiplier%`, `%time%` and full MiniMessage, including `<gradient:...>` / hex colors which render as true RGB on the bar
`effects`	List of effects the event applies while active (see below)
`notifications.start` / `.end`	Title + sound + broadcast fired when the event starts/ends

Effect Reference

`CURRENCY_MULTIPLIER`

Multiplies a single currency a player receives.

- type: CURRENCY_MULTIPLIER
  currency: money                    # internal currency name (money, tokens, gems, ...)
  multiplier: 2.0
  apply-to-causes: [MINING, MINING_OTHERS]

Option	Description
`currency`	The internal currency name to boost (required)
`multiplier`	The multiplier applied to the received amount
`apply-to-causes`	Which currency-receive reasons are boosted. Empty = all reasons. Common values: `MINING` (mining/sellall income), `MINING_OTHERS` (e.g. Charity), `PAY`, `REDEEM`

Event currency boosts stack multiplicatively with the Multipliers module (global × rank × personal). Leaving apply-to-causes at [MINING, MINING_OTHERS] matches the Multipliers module and boosts mining income only.

`XP_MULTIPLIER`

Multiplies Battle Pass XP gains.

- type: XP_MULTIPLIER
  multiplier: 2.0
  sources: []                        # empty = all sources

Option	Description
`multiplier`	The multiplier applied to XP gained
`sources`	Restrict to specific XP sources. Empty = all. Valid: `QUEST`, `DAILY_REWARD`, `MINING`, `PRESTIGE`, `REBIRTH`, `ADMIN`, `OTHER`

A "Quest XP" event is simply sources: [QUEST]; Quest completions award Battle Pass XP, so this scales the XP quests grant.

`ENCHANT_PROC_MULTIPLIER`

Multiplies enchant trigger chances — the "Enchant Frenzy" effect.

- type: ENCHANT_PROC_MULTIPLIER
  multiplier: 1.20                   # +20%
  enchants: []                       # empty = all enchants

Option	Description
`multiplier`	Factor applied to each enchant's proc chance (`1.20` = +20%). The final chance is capped at 100%
`enchants`	Restrict to specific enchants by raw name (e.g. `nuke`) or numeric id. Empty = all enchants

Stacking

When two or more running events boost the same dimension (e.g. both boost money), the stacking setting in events.yml decides how their factors combine:

`stacking`	Two active 2× money events give
`MULTIPLY` (default)	4× money (factors multiply)
`HIGHEST`	2× money (only the strongest factor applies)

Events that boost different dimensions (e.g. one money, one tokens) never interfere — each simply applies to its own currency.

Automatic Scheduler

The scheduler can start events for you on a fixed interval. Configure it under scheduler: in events.yml.

Option	Description
`enabled`	Turn the scheduler on/off
`mode`	`ROTATION` — start a weighted-random event from the pool each interval. `SEQUENTIAL` — start the next pool event in order. `OFF` — never auto-start
`interval`	Seconds between automatic starts
`min-online-players`	Skip auto-starting if fewer than this many players are online
`prevent-duplicates`	If `true`, never auto-start an event that is already running
`events-per-interval`	How many distinct events to start each interval (default `1`). Capped at the number of eligible events. `ROTATION` picks them weighted-random without repeats; `SEQUENTIAL` takes the next N in order
`pool`	List of event ids eligible for auto-start. Empty = every enabled event. `ROTATION` uses each event's `weight`

Manual /events start <id> always works regardless of the scheduler.

PlaceholderAPI

If PlaceholderAPI is installed, the addon registers the xprisonevents expansion:

Placeholder	Returns
`%xprisonevents_active_count%`	Number of events currently running
`%xprisonevents_active_names%`	Comma-separated display names of running events
`%xprisonevents_<id>_active%`	`true` / `false` — whether the event with that id is running
`%xprisonevents_<id>_timeleft%`	Remaining time (e.g. `29m 49s`), or empty if not running
`%xprisonevents_<id>_multiplier%`	The event's headline multiplier (e.g. `2`), or empty if unknown

Example: %xprisonevents_payday_timeleft% → 12m 3s while Payday is running.

Notifications

Each event's start and end notification has three independent parts, any of which can be omitted:

notifications:
  start:
    title:                 # on-screen title
      enabled: true
      title: "<gold><bold>PAYDAY!"
      subtitle: "<white>2x Money for 30 minutes"
      fade-in: 1           # ticks... (seconds are handled internally)
      stay: 3
      fade-out: 1
    sound:                 # played to every online player
      enabled: true
      sound: ENTITY_PLAYER_LEVELUP
      volume: 1.0
      pitch: 1.0
    broadcast: "<gold>Payday has begun!"   # chat message to every online player

title — an on-screen title/subtitle. Set enabled: false to skip it.
sound — a Bukkit/XSeries sound name, played to every online player. Invalid names are ignored.
broadcast — a chat line sent to every online player (the messages.prefix is prepended). Omit or leave empty to skip.

The bossbar title, all messages and all notification text support %name%, %multiplier% and %time% placeholders where relevant.

Troubleshooting

The addon didn't load / commands don't exist

Confirm your X-Prison version is 2026.2.6.1 or newer.
Check the server startup log for Enabling Events addon vX... and any errors during addon enable.
Make sure the JAR is in plugins/X-Prison/addons/ and you fully restarted (not /reload).

A currency event does nothing

Verify the currency name matches an enabled currency in currencies.yml (names are case-insensitive but must exist).
If apply-to-causes is set, make sure the way players earn that currency is included (mining income is MINING).

The XP Boost event does nothing

The Battle Pass module must be enabled. XP events scale BattlePassXpGainEvent.

Enchant Frenzy has no visible effect

Enchants that don't roll a chance (passive enchants) are unaffected. The boost applies to chance-based enchant procs and is capped at 100%.

A change to a config file didn't apply

Run /events reload. Note that changing the command name/aliases requires a full restart.
Events already running keep the settings they started with; only newly-started events use the new config.

The scheduler never starts anything

Set scheduler.enabled: true and mode to ROTATION or SEQUENTIAL.
Check min-online-players isn't higher than your player count, and that the pool (if set) lists enabled event ids.

For Developers

The addon adds no new API, but it is built entirely on public X-Prison API events, which you can also use:

Events

Events Addon

Requirements

Installation

How It Works

Included Events

Effect Types

Commands & Permissions

Configuration — events.yml

Key options

Creating an Event

Event fields

Effect Reference

CURRENCY_MULTIPLIER

XP_MULTIPLIER

ENCHANT_PROC_MULTIPLIER

Stacking

Automatic Scheduler

PlaceholderAPI

Notifications

Troubleshooting

For Developers

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Configuration — `events.yml`

`CURRENCY_MULTIPLIER`

`XP_MULTIPLIER`

`ENCHANT_PROC_MULTIPLIER`