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. The filename (without .yml extension) becomes the event identifier.
Example: my_cool_event.yml is referenced as my_cool_event
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
Sets the list of bosses which will be spawned. Mandatory!
| Key | Values | Default |
|---|---|---|
bossFilenames | String List | none |
Example
bossFilenames:
- balrog.yml
- my_event_boss.yml
announcementPriority
Sets the announcement priority.
| Key | Values | Default |
|---|---|---|
announcementPriority | Integer | 0 |
Example
announcementPriority: 1
startMessage
Sets the message sent at the start of the event.
| 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 the commands that run at the start of the event.
| Key | Values | Default |
|---|---|---|
eventStartCommands | String List | none |
Example
eventStartCommands:
- say The event now starts!!
- "$chance=0.5$ say What a spawn!"
eventEndCommands
Sets the commands that run at the end of the event.
| 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 amount of online players required for the event to start.
This is only checked for Action Events. Timed Events ignore it - they only require at least one player to be online.
| Key | Values | Default |
|---|---|---|
minimumPlayerCount | Integer | 1 |
Example
minimumPlayerCount: 5
Event 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!
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
minimumPlayerCount: 1
Action Events
Events that have a chance of running when a specific action, such as breaking a block or fishing, happen.
Note: Action events automatically apply a per-player cooldown to prevent the same player from repeatedly triggering events. The cooldown defaults to 4 minutes and is configurable via actionEventMinimumCooldownMinutes in events.yml. Action events can also be disabled server-wide by setting actionEventsEnabled to false in the same file.
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 player reels something in. Casts that catch nothing never trigger the event. |
TILL_SOIL | A player right-clicks DIRT or GRASS_BLOCK while holding any hoe. |
In every case the location must be in a world EliteMobs is enabled for, must not be inside an EliteMobs dungeon world or an ongoing instance, and must pass the WorldGuard elitemobs-events flag.
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 are events that happen at configurable time intervals. Once the cooldown for a timed event is over, a random timed event is picked from the list of timed events based on the weight of the event.
Nothing is picked while the server has no players online, and an event that is already running is never picked a second time. Timed events can be disabled server-wide by setting timedEventsEnabled to 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 amount of time, in minutes, before this event can be picked again.
| Key | Values | Default |
|---|---|---|
localCooldown | Double | 0 |
Example
localCooldown: 120
globalCooldown
Sets the amount of time, in minutes, before the next event will be picked.
| Key | Values | Default |
|---|---|---|
globalCooldown | Double | 0 |
Example
globalCooldown: 60
weight
Sets the weight of the event, affecting the chance that it will be picked over other events. Recommended: 100.
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 timed event scheduler starts ~5 minutes after server start and then checks once per minute whether the global cooldown has elapsed and an event can be picked
| Key | Values | Default |
|---|---|---|
weight | Double | 0 |
Example
weight: 60.5
eventDuration
Sets the maximum duration of the event, in minutes.
| Key | Values | Default |
|---|---|---|
eventDuration | Double | 0 |
Example
eventDuration: 30
endEventWithBossDeath
Sets if the event ends with the boss death.
| 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.
| Key | Values | Default |
|---|---|---|
eventEndTime | Integer (0-24000, -1 to disable) | -1 |
Example
eventEndTime: 23000
Note that events get queued, meaning they will only start once the conditions defined in the spawnType are met.
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
minimumPlayerCount: 5
Triggering an event manually
/em event <event filename>
Queues a timed event to start at the next valid time and place, exactly as if the scheduler had picked it. It requires the elitemobs.event.start permission, must be run by a player, and only accepts filenames of enabled events whose eventType is TIMED.
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.
Server-wide event settings
These live in ~/plugins/EliteMobs/events.yml and apply to every event:
| 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 | Minimum time, in minutes, between one timed event starting and the next one being allowed to start | 4 |
announcementBroadcastWorldOnly | Whether event announcements are limited to the world the event is happening in | false |