Creating Events
This guide is for EliteMobs 10 and later
What are Custom Events?
Custom Events here refer to events that occur randomly in-game, whether based on player actions or having a timed trigger. The plugin comes preloaded with a number of Custom Events, such as the Balrog event, the Kraken event and the Treasure Goblin events, to name a few.
This system is called Custom Events because the events can not only be customized but created from scratch. What follows is a guide on how to create and customize your own events.
Creating Your Custom Events
Custom event configuration files should be created in:
plugins/EliteMobs/customevents/
Files must use the .yml format. Reference the full filename, including the .yml extension.
Example: my_cool_event.yml is referenced as my_cool_event.yml
Save the files and run /em reload to load changes. The corresponding action/timed event switch in events.yml must also be enabled.
Common configuration settings
The following settings can/should be used for both action and timed events.
isEnabled
Sets if the event is enabled.
| Key | Values | Default |
|---|---|---|
isEnabled | Boolean | true |
Example
isEnabled: true
eventType
Sets the type of event.
| Key | Values | Default |
|---|---|---|
eventType | BREAK_BLOCK / FISH / TILL_SOIL / TIMED | DEFAULT |
Note that BREAK_BLOCK, FISH and TILL_SOIL are Action Events and TIMED is Timed Events.
eventType is mandatory. DEFAULT is the placeholder EliteMobs falls back to when the setting is missing or does not match any of the types above. An event left on DEFAULT logs a warning and is not registered at all, so none of the settings below it are even read.
Example
eventType: BREAK_BLOCK
bossFilenames
Lists the custom boss filenames to spawn together, including .yml. Mandatory! This is not a random selection from the list. Check every referenced boss before using the event. Timed events skip invalid filenames and cannot queue with no valid bosses. An action event with any invalid filename is cancelled before anything spawns, and if a boss's spawn is refused, the bosses it already spawned are removed.
| Key | Values | Default |
|---|---|---|
bossFilenames | String List | none |
Example
bossFilenames:
- balrog.yml
- my_event_boss.yml
announcementPriority
Sets the audience for the event's start and end messages. Event priorities behave differently from boss announcement priorities:
| Priority | Audience |
|---|---|
0 | Players in the event's world; this does not silence messages |
1 | All online players, or just the event's world when announcementBroadcastWorldOnly: true |
2 | Players in the event's world |
3 or higher | Players in the event's world, plus DiscordSRV when configured |
Omit startMessage or endMessage to suppress that event message. A boss's own spawn announcement is separate.
| Key | Values | Default |
|---|---|---|
announcementPriority | Integer | 0 |
Example
announcementPriority: 1
startMessage
Sets the message sent when the event starts, rather than when a timed event is queued. Start and end messages support color formatting, but this event system does not substitute boss/player placeholders such as $boss or $player.
| Key | Values | Default |
|---|---|---|
startMessage | String | none |
Example
startMessage: An event has started!
endMessage
Sets the message sent at the end of the event.
| Key | Values | Default |
|---|---|---|
endMessage | String | none |
Example
endMessage: An event has ended!
eventStartCommands
Sets console commands run when the event starts. Omit the leading /. No player or boss placeholders are supplied. Each command runs independently; an optional $chance=0.5$ gives that command a 50% chance. Use a probability from 0 to 1; without it the command always runs.
| Key | Values | Default |
|---|---|---|
eventStartCommands | String List | none |
Example
eventStartCommands:
- say The event now starts!!
- "$chance=0.5$ say What a spawn!"
eventEndCommands
Sets console commands scheduled for the next server task when the event ends. They use the same syntax and per-command chance as eventStartCommands, with no player or boss placeholders.
| Key | Values | Default |
|---|---|---|
eventEndCommands | String List | none |
Example
eventEndCommands:
- say The event ends, so sad.
- "$chance=0.5$ say Too slow bud!"
minimumPlayerCount
Sets the minimum number of online players, counting every world and game mode. This is not a count of eligible participants near the event.
Action Events check it when the action triggers them. Timed Events check it when the automatic picker selects events, before a queued event searches for a location, and again right before its bosses spawn. A queued timed event waits until enough players are online; its custom spawn must still find a suitable location through its own player and location checks.
| Key | Values | Default |
|---|---|---|
minimumPlayerCount | Integer | 1 |
Example
minimumPlayerCount: 5
Event Config Example
Common settings only; a complete timed event also needs spawnType and a positive selection weight.
isEnabled: true
eventType: TIMED
bossFilenames:
- "cool_boss.yml"
- "other_cool_boss.yml"
announcementPriority: 3
startMessage: "Cool event is starting!"
endMessage: "Cool event is ending!"
eventStartCommands:
- say The event started!
eventEndCommands:
- say The event ended!
Complete Timed Event Example
isEnabled: true
eventType: TIMED
bossFilenames:
- "my_timed_boss.yml"
announcementPriority: 3
startMessage: "A timed event has started!"
endMessage: "The timed event has ended!"
eventStartCommands:
- say The timed event began!
eventEndCommands:
- say The timed event concluded!
spawnType: "my_spawn_location.yml"
localCooldown: 120
globalCooldown: 30
weight: 100
eventDuration: 15
endEventWithBossDeath: true
Action Events
Events that have a chance of running when a specific action, such as breaking a block or fishing, happen.
Action events apply a per-player cooldown after starting. It defaults to 4 minutes and is configurable via actionEventMinimumCooldownMinutes in events.yml. Only one action event starts per action: once a matching file starts, the player is on cooldown and the remaining files are skipped. An event that fails to start does not use up the cooldown. Action events can be disabled server-wide with actionEventsEnabled: false.
The three action types trigger as follows:
eventType | Trigger |
|---|---|
BREAK_BLOCK | A player breaks a block. chance is rolled first, then the broken block is checked against breakableMaterials. |
FISH | A fishing event has a caught entity, including a hooked mob. Casts with no caught entity cannot trigger it. The spawn position is the caught entity's location. |
TILL_SOIL | A player right-clicks DIRT or GRASS_BLOCK with a wooden, stone, iron, golden, diamond or netherite hoe in the main hand. The check does not require the block to become farmland. |
Cancelled Bukkit events are ignored. In every case the location must be in an enabled EliteMobs world, outside EliteMobs dungeon worlds and dungeon, arena or class trial instance regions, and allowed by the WorldGuard elitemobs-events flag. These listeners do not separately restrict the player's game mode.
Action events spawn at the interaction location: the broken block's center in X/Z, the caught entity, or one block above the clicked soil. They do not use spawnType, timed selection weights or timed selection cooldowns.
Peace Banner protection also prevents the event when suppressEvents is enabled. The duration, end-time and end-on-boss-removal settings documented below are common watchdog checks and also apply to action events.
chance
Sets the chance of the event happening when the action happens.
| Key | Values | Default |
|---|---|---|
chance | Value between 0.0 and 1.0 | 0 |
Example
chance: 0.001
breakableMaterials
Sets the list of materials to check if the action is set to BREAK_BLOCK.
| Key | Values | Default |
|---|---|---|
breakableMaterials | List of materials | none |
Example
breakableMaterials:
- BEEHIVE
- BIRCH_WOOD
Config Example
chance: 0.001
breakableMaterials:
- COAL_ORE
Sets a 0.1% chance of running the event when a coal ore block is broken, assuming that the event type is BREAK_BLOCK.
Complete Action Event Example
isEnabled: true
eventType: BREAK_BLOCK
bossFilenames:
- "mining_boss.yml"
announcementPriority: 2
startMessage: "You've awakened something..."
chance: 0.001
breakableMaterials:
- DIAMOND_ORE
- EMERALD_ORE
Timed Events
Timed events use weighted automatic selection followed by a custom-spawn queue. Selection is not a promise of immediate spawning or a fixed schedule. Different event files can be queued or running at the same time.
Nothing is picked while the server has no players online. The automatic picker excludes a filename while a copy is queued or running, or while fewer players than its minimumPlayerCount are online. Disable timed events server-wide with timedEventsEnabled: false in events.yml.
spawnType
Sets the Custom Spawn used by the event, which defines where the boss can spawn.
| Key | Values | Default |
|---|---|---|
spawnType | Filename | none |
Example
spawnType: nether_spawn.yml
localCooldown
Sets the delay in minutes before this event can be selected automatically again, measured from selection. The local delay is consumed even if validation or another plugin then prevents queuing. A queued or running copy also blocks automatic reselection, even after this delay expires.
| Key | Values | Default |
|---|---|---|
localCooldown | Double | 0 |
Example
localCooldown: 120
globalCooldown
Sets the global automatic-selection delay in minutes. It is assigned when an event successfully queues and assigned again when that event actually starts, including manually queued events. It does not begin when the event ends. A later assignment replaces the previous deadline.
| Key | Values | Default |
|---|---|---|
globalCooldown | Double | 0 |
Example
globalCooldown: 60
weight
Sets the relative selection weight among currently eligible timed events. Use a finite positive value. Recommended: 100. A zero weight is not a reliable disable switch, especially when all eligible weights are zero; use isEnabled: false instead.
The weight system determines relative probability of event selection. For example:
- Event A with weight 100 vs Event B with weight 50 = Event A is twice as likely to be selected
- Higher weight = higher chance of being picked
- The scheduler first checks about 5 minutes after initialization, then once per minute. Server lag can delay these checks.
| Key | Values | Default |
|---|---|---|
weight | Double | 0 |
Example
weight: 60.5
eventDuration
Sets the duration limit in minutes, measured from the actual event start. Use 0 to disable it; negative values also disable the check. The watchdog checks every 20 server ticks, so the event can end up to a second late, or later under server lag. This setting also applies to action events.
| Key | Values | Default |
|---|---|---|
eventDuration | Double | 0 |
Example
eventDuration: 30
endEventWithBossDeath
Ends the event when none of its primary boss objects still exists. With several bossFilenames, removing or defeating just one boss does not end the event while another remains. Reinforcements are not additional primary bosses. This checks existence rather than requiring a credited player kill. Ending an event for any reason removes remaining primary bosses as timed-out bosses. This setting also applies to action events.
| Key | Values | Default |
|---|---|---|
endEventWithBossDeath | Boolean | true |
Example
endEventWithBossDeath: true
eventEndTime
Sets the in-game time (in ticks) when the event ends. Use Minecraft's time system where 0=dawn, 6000=noon, 12000=dusk, 18000=midnight, 23000=late night. Set to -1 to disable time-based ending.
The check is world time > eventEndTime; it does not wait for a future day or an exact crossing. An event starting after that time can end on its first watchdog check. Keep the spawn's time window consistent with the end time. World time ranges from 0 to 23999, so thresholds of 23999 or higher are never exceeded. This setting also applies to action events.
| Key | Values | Default |
|---|---|---|
eventEndTime | Integer (0–23998 for a reachable threshold; -1 disables) | -1 |
Example
eventEndTime: 23000
Queuing starts the custom spawn's search and retry process. It can wait at a cached location for the time or moon phase to match; location checks are not all repeated during that wait. See the custom-spawn guide above for its checks and limitations. Only one timed event spawns at a time, and the spawn also waits for minimumPlayerCount and the timedEventMinimumCooldownMinutes interval. The start message and start commands run only after the timed event confirms its primary bosses exist.
Events Config Example
isEnabled: true
eventType: TIMED
bossFilenames:
- "cool_boss.yml"
- "other_cool_boss.yml"
announcementPriority: 3
startMessage: "Cool event is starting!"
endMessage: "Cool event is ending!"
eventStartCommands:
- say The event started!
eventEndCommands:
- say The event ended!
spawnType: "myCoolSpawn.yml"
localCooldown: 30
globalCooldown: 15
weight: 100
eventDuration: 20
endEventWithBossDeath: true
eventEndTime: 10000
Triggering an event manually
/em event <event filename>
Queues a timed event to start at a valid time and place. It requires the elitemobs.event.start permission, must be run by a player, and only accepts loaded timed-event blueprints. These are created from enabled TIMED files when timedEventsEnabled is enabled.
The command bypasses the scheduler's weighted selection, local/global selection cooldown checks, and check for an already queued or running copy. Repeating it can queue duplicate copies. The custom spawn's location and time conditions, the event's minimumPlayerCount, and the timedEventMinimumCooldownMinutes interval still apply.
If the event cannot be queued you get told why: no spawnType set, a spawnType that does not point at a valid custom spawn file, none of the bossFilenames being valid, or another plugin cancelling the event. A successful queue message confirms acceptance into the queue, not a visible spawn. Check the actual bosses and the console for spawn retries.
Server-wide event settings
These live in plugins/EliteMobs/events.yml. Reload after editing them:
| Key | Description | Default |
|---|---|---|
actionEventsEnabled | Whether action events happen at all | true |
timedEventsEnabled | Whether timed events happen at all | true |
actionEventMinimumCooldownMinutes | Per-player cooldown, in minutes, after an action event triggers | 4 |
timedEventMinimumCooldownMinutes | Delay in minutes after a timed event starts before another timed event can search for a location or spawn its bosses, including one already waiting at a cached location | 4 |
announcementBroadcastWorldOnly | Restricts priority 1 event messages to the event's world; other priorities already send in-game messages only to that world | false |