Dungeon Packager

What are dungeons?

You can find info about dungeons, including info about premade dungeons here.

---

What is the dungeon packager?

The dungeon packager allows admins to not only create and package dungeons but also package any kind of EliteMobs content. This includes things such as event packs, model packs, arenas, npc packs, item packs and so on.

Why use dungeon packages?

• Instanced dungeons! Instanced dungeons can only be created through the dungeon package system.
• Safe backups of Minidungeons! If you make a Dungeon Package, you'll be able to deploy and redeploy it in any server you want at any time and for any reason.
• Easy to turn off and on! You can always do /em setup and temporarily or permanently turn Dungeon Packages off and on.
• Easy to share! If you wish to share your creations, Dungeon Packages can just be zipped up and sent to other people. There is a Discord room dedicated to community creations if you are interested!
• Teleports! Dungeon packages automatically create teleport locations which can be accessed in the Teleports page of the /em menu, which might be very useful in a lot of setups.

Creating Dungeons

The following settings are used to create a configuration file which should go into the content_packages folder. These settings are used to create dungeons specifically, and are not required if you just want to use the dungeon packager to distribute non-dungeon content such as a pack of items or events.

Required plugins

In order to use the Dungeon Packager, you will need the following plugin:

WorldGuard - protects the Minidungeon

Creating a dungeon, step-by-step

EliteMobs used to have two major kinds of dungeons: world-based and schematic-based.

Schematic-based dungeons, were associated with a schematic build. They are now phased out and not supported anymore.

All EliteMobs dungeons are now world based.

Required pack.meta file

Your dungeon package should include a pack.meta file, which is simply a renamed .txt file with a .meta extension. This file should contain just one word, indicating which plugin the package is for (e.g., "elitemobs," written in lowercase). The pack.meta file must be located in the root directory of your package, alongside all the other folders.

---

Global values

The following values apply to all dungeons

isEnabled

Sets if the dungeon package is enabled.

Key	Values	Default	Mandatory
isEnabled	Boolean	false	✅

Example

isEnabled: true

---

name

Sets the name of the content. Supports Color Codes.

Key	Values	Default	Mandatory
name	String	false	✅

Example

name: '&c[lvl 999] &aThe Green Dungeon'

---

contentType

Sets the type of dungeon.

Key	Values	Default	Mandatory
contentType	OPEN_DUNGEON / INSTANCED_DUNGEON / DYNAMIC_DUNGEON / HUB / META_PACKAGE	none	✅

Example

contentType: INSTANCED_DUNGEON

---

customInfo

Sets the additional info that will appear in the /em setup screen. Only for information purposes. Supports Color Codes.

Key	Values	Default	Mandatory
customInfo	String List	none	✅

Example

customInfo:
- '&aThe best dungeon.'
- '&aMade by: CoolPlayer'

---

downloadLink

Sets the download link when the content is not downloaded. Only for information purposes.

Key	Values	Default	Mandatory
downloadLink	String	none	❌

Example

downloadLink: http://www.example.org

---

dungeonSizeCategory

Sets the size category of the dungeon package. Only for information purposes.

Key	Values	Default	Mandatory
dungeonSizeCategory	Special [1]	none	✅

Example

dungeonSizeCategory: MINIDUNGEON

Special [1]

Expand Table

Key	Description
LAIR	Lairs are a type of small dungeon which focuses on one big boss fight.
SANCTUM	Sanctums are the equivalent of instanced Lairs. This means that they focus around one huge boss fight.
MINIDUNGEON	Minidungeons are a type of medium sized dungeon which usually contains 3-15 minibosses and a big boss, as well as a lot of "trash" mobs which are meant to be "farmed" for coins and gear by players.
DUNGEON	Dungeons are the equivalent of instanced Minidungeons. This the the most traditional MMORPG type of dungeon, where players party up and go through a gauntlet of trash mobs and minibosses to fight a final boss.
RAID	Coming soon!
ADVENTURE	Adventures are full adventure maps. They include quests lines, npcs, large amounts of minibosses and bosses and can even contain their own arenas or dungeons inside of them.
ARENA	Arenas are wave-based survival areas in which players get rewarded for defeating waves.
OTHER	Anything else that does not alreeady fall in the previous categories.

For more detailed descriptions see Dungeons

---

protect

Sets if the dungeon package should be protected by WorldGuard.

Key	Values	Default	Mandatory
protect	Boolean	true	❌

Example

protect: true

---

dungeonVersion

Sets the version of the dungeon package.

Key	Values	Default	Mandatory
dungeonVersion	Integer	none	✅

Example

dungeonVersion: 1

---

playerInfo

Sets the info which appears in the menu. Supports Color Codes.

Works only when the /em is set to book mode using /em alt.

Key	Values	Default	Mandatory
playerInfo	String	none	✅

Example

playerInfo: 'Difficulty: &a1-man easy content!'

---

regionEnterMessage

Sets the message that appears when a player enters the dungeon zone. Supports Color Codes.

Key	Values	Default	Mandatory
regionEnterMessage	String	none	❌

Example

regionEnterMessage: '&aYou have entered the dungeon!'

---

regionLeaveMessage

Sets the message that appears when a player leaves the dungeon zone. Supports Color Codes.

Key	Values	Default	Mandatory
regionLeaveMessage	String	none	❌

Example

regionLeaveMessage: '&aYou have left the dungeon!'

---

hasCustomModels

Sets whether the dungeon package has custom models (for ModelEngine or FreeMinecraftModels).

Key	Values	Default	Mandatory
hasCustomModels	Boolean	none	❌

Example

hasCustomModels: false

---

dungeonConfigFolderName

Sets the name of the folders used for files associated to this dungeon.

Mandatory for instanced dungeons!.

Key	Values	Default	Mandatory
dungeonConfigFolderName	String	none	❌

Example

dungeonConfigFolderName: my_dungeon_folder

---

contentLevel

Sets the content level the dungeon should display in the EM menu.

Key	Values	Default	Mandatory
contentLevel	Integer	none	❌

Example

contentLevel: 20

---

enchantmentChallenge

Sets if the dungeon should be an Enchantment Challenge dungeon.

Key	Values	Default	Mandatory
enchantmentChallenge	Boolean	false	❌

Example

enchantmentChallenge: false

---

song

Sets if the dungeon should have a soundtrack.

Key	Values	Default	Mandatory
song	String	none	❌

name= This where you define which file from the resource pack should be played.
length= The length of the soundtrack in milliseconds.

Example

song: name=elitemobs:dark_cathedral.ambient length=93830

dungeonLockoutMinutes

Sets a dungeon lockout timer after the boss of the dungeon has been slain. Specified value set is in minutes.

Key	Values	Default	Mandatory
dungeonLockoutMinutes	Integer	none	❌

Example

dungeonLockoutMinutes: 1440

---

World-based dungeon packages

The following values only apply to world-based dungeons.

---

worldName

Sets the name of the world that should be packaged.

Key	Values	Default	Mandatory
worldName	String	none	✅

Example

worldName: my_minecraft_world

---

womholeWorldName

This function sets the name of the wormhole world, which serves as a secondary world linked to the main world. It is utilized for features like teleport hubs or unique boss chambers.

Key	Values	Default	Mandatory
womholeWorldName	String	none	❌

Example

womholeWorldName: my_minecraft_world_wormhole

---

environment

Sets the world's environment.

Key	Values	Default	Mandatory
environment	Environment	none	✅

Example

environment: NORMAL

---

teleportLocation

Sets the teleport location of the dungeon package. This is where the players will be teleported to when entering the dungeon.

Key	Values	Default	Mandatory
teleportLocation	String	none	✅

Example

teleportLocation: my_minecraft_world,-1.5,68,0.5,0.0,0.0

---

allowExplosionBlockDamage

Either allows or prevents explosions to damage blocks in a dungeon. The explosions are considered elite explosions so any damage to blocks will be regenerated within 2 minutes.

Key	Values	Default	Mandatory
allowExplosionBlockDamage	Boolean	false	❌

Example

allowExplosionBlockDamage: true

Instanced dungeons

Instanced dungeons create a new world for every time a group of players wants to complete a dungeon, and deletes it when it's done. For this to work correctly, you must put a folder following the dungeonConfigFolderName in the the world_blueprints configuration folder of EliteMobs.

You then place the world you'll be using inside of the folder you created, making sure that the session.lock file of the world is deleted.

The following values only apply to instanced dungeons. Note that all instanced dungeons are world dungeons, so they also use the values from world dungeons.

---

startLocation

Sets the teleport location of the instanced dungeon starting point. This is where the players will be teleported to when starting the instanced dungeon with /em start.

Key	Values	Default	Mandatory
startLocation	String	none	✅

Example

startLocation: my_minecraft_world,10.5,70,10.5,0.0,0.0

---

permission

Sets the permission required in order to enter the dungeon instance.

Key	Values	Default	Mandatory
permission	String	none	❌

Example

permission: elitedungeon.mypermission

---

minPlayerCount

Sets the minimum player count required to start a dungeon.

Key	Values	Default	Mandatory
minPlayerCount	Integer	1	❌

Example

minPlayerCount: 1

---

maxPlayerCount

Sets the minimum player count required to start a dungeon.

Key	Values	Default	Mandatory
maxPlayerCount	Integer	5	❌

Example

maxPlayerCount: 5

---

dungeonObjectives

Sets list of dungeon objectives required for the dungeon to be considered completed.

Key	Values	Default	Mandatory
dungeonObjectives	String List	none	✅

Examples

There are currently two dungeon objective types:

• Kill target: filename=boss.yml:amount=X
• Kill percentage of dungeon: clearpercentage=X.Y

dungeonObjectives:
- filename=dungeon_final_boss.yml
- filename=dungeon_miniboss_one.yml
- filename=dungeon_miniboss_two.yml

dungeonObjectives: 
- clearpercentage=0.8

---

difficulties

Sets list of difficulties in the instanced dungeon.

Mandatory for instanced dungeons!

Key	Values	Default	Mandatory
difficulties	Special [1]	none	❌

Examples

difficulties:
- levelSync: 25
  id: 0
  name: normal
- levelSync: 20
  id: 1
  name: hard
- levelSync: 15
  id: 2
  name: mythic

Special [1]

Expand Table

Setting instanced dungeon difficulties will automatically create different difficulty options when entering the dungeon.

The difficulty names set here will be the ones used in the custom bosses folder, where you are able to set which powers bosses have based on the difficulty.

Difficulties are in a list format which have the following fields:

Key	Description	Values	Mandatory
name	Name of the difficulty for players.	String	✅
id	ID of the difficulty, used in custom bosses and custom items for the difficulty-based feature.	String	✅
levelSync	Sets the level of the level sync, if any. Level sync makes all player gear max out at the set value, making it impossible for players to get over leveled for a dungeon and keeping it relevant for later runs. Based on the Final Fantasy 14 level sync system.	Integer	❌

Dynamic dungeons

Dynamic dungeons are an extension of instanced dungeons, but with one key difference: they allow the dungeon’s content to scale to the difficulty level chosen by the player. The level options available to the player are determined by the player’s unlocked Guild level.

When designing bosses and mobs for a dynamic dungeon, use the setting level: dynamic. Any loot in dynamic dungeons should be set with scalability: scalable.

The following values are needed for dynamic dungeons.
Since all dynamic dungeons are also instanced dungeons, they additionally use all values and settings from instanced dungeons.

---

contentType

Sets the type of dungeon. This must be set to DYNAMIC_DUNGEON.

Key	Values	Default	Mandatory
contentType	OPEN_DUNGEON / INSTANCED_DUNGEON / DYNAMIC_DUNGEON / HUB / META_PACKAGE	none	✅

Example

contentType: DYNAMIC_DUNGEON

---

contentLevel

Sets the content level the dungeon should display in the EM menu. This needs to be set to the value of -1 for the dungeon to be shown as a dynamic dungeon.

Key	Values	Default	Mandatory
contentLevel	Integer	none	✅

Example

contentLevel: -1

---

difficulties

Sets the available list of difficulties and level sync in the dynamic dungeon.

Mandatory for instanced dungeons!

Key	Values	Default	Mandatory
difficulties	Special [1]	none	✅

Examples

difficulties:
- levelSync: '+5'
  name: normal
  id: 0
- levelSync: '+0'
  name: hard
  id: 1
- levelSync: '-5'
  name: mythic
  id: 2

Special [1]

Expand Table

Setting instanced dungeon difficulties will automatically create different difficulty options when entering the dungeon.

The difficulty names set here will be the ones used in the custom bosses folder, where you are able to set which powers bosses have based on the difficulty.

Setting levelSync values to positive or negative numbers in quotation marks controls how the player’s equipment is synced inside the dungeon. These values do not affect the dungeon’s own level—dungeon content always syncs directly to the player’s level choice upon entry.

For example, if levelSync is set to "+0", the player’s equipment will be synced to match the dungeon’s content level exactly.
If set to "+5", the player’s equipment will be synced 5 levels above the dungeon’s content.
If set to "-5", their equipment will be synced 5 levels below the dungeon’s content.

Difficulties are in a list format which have the following fields:

Key	Description	Values	Mandatory
name	Name of the difficulty for players.	String	✅
id	ID of the difficulty, used in custom bosses and custom items for the difficulty-based feature.	String	✅
levelSync	Sets the level for player gear scaling. This determines how a player’s equipment level is adjusted relative to the dungeon content, allowing gear to be up to a few levels above or below the chosen dungeon difficulty. Based on the Final Fantasy 14 level sync system.
Integer	❌

---

Using the meta_pack.yml dungeon package file for large dungeons.

Sometimes, you may be working on a large dungeon that includes other, smaller dungeons within itself, allowing players to travel between them through the main dungeon world. A great example of this is the EliteMobs Adventure Dungeon Primis.

Primis features a vast world where players can explore and complete quests, but it also includes two instanced dungeons within its world—one of which serves as the final boss fight. In cases like this, there will be multiple dungeon package files, even though they all belong to the same overarching dungeon.

To manage this, we use a meta dungeon package file. This file acts as a central directory, specifying the primary dungeon and listing all additional dungeon content associated with it.

Let’s take a closer look at how the Primis meta dungeon package is structured:

isEnabled: true
name: '&2[000-020] The Primis Adventure!'
customInfo:
- The tutorial adventure for players
- new to EliteMobs!
downloadLinkV2: https://discord.gg/9f5QSka
dungeonSizeCategory: LAIR
environment: NORMAL
protect: true
contentType: META_PACKAGE
containedPackages:
- primis_adventure.yml
- primis_blood_temple_sanctum.yml
- primis_gladius_invasion_dungeon.yml
setupMenuDescription:
- '&2A soft tutorial adventure for players between levels 0-20!'
- '&2Adventures are massive maps with quests,'
- '&2many bosses and npcs, among other things!'
- '&2Also has custom models!'
dungeonVersion: 21 #added dungeon meta package file

As you can see, the meta dungeon package file is very similar to a regular dungeon package, with a few key differences. The contentType: is set to META_PACKAGE, and there is an additional setting called containedPackages:. This setting lists all the other dungeon packages that are part of the larger dungeon.

When creating your meta package, be sure to include the containedPackages: setting and list every dungeon package that is part of your larger dungeon. This ensures that everything is properly linked and organized within the overarching structure.

When versioning your dungeon, all versioning should be managed through the meta package. This is because the meta package serves as the primary package that determines the version of the entire dungeon and is also the package used to display information in the /em setup menu.

Keep in mind that individual dungeons listed in the meta package might still appear in the /em teleport menu. To prevent this, you’ll need to manually disable teleport options for each of those dungeons in their respective configuration files.

For example, in the case of the Primis dungeon:

Disable teleport entries in the menu for primis_blood_temple_sanctum.yml and primis_gladius_invasion_dungeon.yml. Leave teleport options enabled for primis_adventure.yml, as this serves as the main hub where players begin their journey and access the other dungeons. This setup ensures a smooth experience for players while maintaining proper structure and functionality for the dungeon system.

When naming the file we recommend the following naming convention:

your_dungeon_name_meta_pack.yml

---

Recommended Boss Values

Creating an average dungeon mob

We recommend leaving the setting normalizedCombat set to true. This setting normalizes all mobs to scale equally with health and damage, regardless of their entity type.

normalizedCombat: true
healthMultiplier: 1.0 #4 hits to slay 
damageMultiplier: 1.0 #1.5 hearts of dmg

Certainly, here's the revised version with clarity and formatting retained:

Note: Given that 1.0 is the default value for health and damage, you can simply omit defining healthMultiplier or damageMultiplier and set normalizedCombat to true.

Creating trash packs

Trash packs are numerous but not very dangerous:

normalizedCombat: true
healthMultiplier: 0.7 #3 hits to slay 
damageMultiplier: 0.5 #0.5 hearts of dmg

Creating reinforcements

Reinforcements should die very easily, but pose a danger damage-wise (these values are recommended for 4+ melee entities, actual use may vary):

normalizedCombat: true
healthMultiplier: 0.25 #1 hit to slay 
damageMultiplier: 0.6 #1 heart of dmg

Creating minibosses

Minibosses should hold their ground, and pose a mechanic challenge to players. It should be a test of skill that lasts for a little while, but not something extremely deadly:

normalizedCombat: true
healthMultiplier: 3.0 #10 hits to slay 
damageMultiplier: 1.2 #2 hearts of dmg

Creating bosses

Bosses are a real challenge, the conclusion of a buildup in a dungeon and a real test of skill with everything on the line. Encounters should be long and death should be a present threat.

normalizedCombat: true
healthMultiplier: 7.0 #23 hits to slay 
damageMultiplier: 1.4 #2.5 hearts of dmg

These recommended values are merely rough estimates, and the final values should be adjusted according to the specific encounters.

This is particularly crucial for final dungeon bosses; you may want to significantly exceed the recommended 7.0 value for healthMultiplier to give the last fight that epic feeling.

---

Packaging EliteMobs content for distribution

Finally, you will probably want to package your dungeon either for storage or for distribution.

EliteMobs has an import system which allows admins to quickly import, install and uninstall content. You can see how it works here.

Distributing Dungeon Resource Packs

As of EliteMobs 9.6.0, dungeons can be packaged and distributed with their own resource packs! This allows you to do cool things like using custom textures or models for loot dropped in the dungeon, or adding custom sounds—like we did in our dungeon The Hallowed Haunt.

To distribute a resource pack with your dungeon, create it like any standard resource pack. If you want a template, you can reference the EliteMobs default resource pack. The resource pack must be distributed unzipped, so create a folder named after your dungeon, for example: my_cool_dungeon_rsp. Place all the resource pack files that would normally go into the zip inside this folder. Then, place this folder inside a new folder called resource_pack—this is the same folder that EliteMobs uses to store its default resource pack.

After organizing your files, the directory structure should look like this:

resource_pack
└── my_cool_dungeon_rsp
    └── [resource pack files]

Once complete, your dungeon resource pack should import successfully when the dungeon is installed.

Trimming Worlds

Sometimes, you may need to reduce the size of your Minecraft world to make it lighter and, consequently, easier to distribute. This can be achieved through the use of the WorldBorder plugin. Despite the plugin being listed as only supporting MineCraft up to version 1.19, it functions seamlessly on the latest MineCraft version as of January 25, 2024.

Details

Tip

If you are doing this for the first time it might be a good idea to create a backup of your world just in case something goes wrong.

Once the plugin is installed, navigate to the middle of the world or the specific area you wish to trim. Then, execute the command /wb set x, where x represents the approximate radius size you want for your area.

Details

Tip

If /wb is not working for you, try /worldborder:wb.

After executing this command, fly to the edges of your world to verify that the world border has been properly set and covers the intended size. You will recognize reaching the world border edge when you are pushed back, accompanied by a message in the chat.

In the image above, we aim to trim the world around the purple blocks, leaving only a few chunks around them. To achieve this, we stand in the middle of the purple area on the red squares and execute /wb set 50, setting the world border just beyond the purple area.

Next, we use the /wb trim [freq] [pad] command, with the frequency set to 200 and the pad to 20. The pad determines how many chunks should be left around the world border (the purple area), and the frequency determines how many chunks should be processed per second. After running /wb trim 200 20, we will be prompted to confirm by executing /wb trim confirm. We confirm the action, and after some time, our world will be trimmed, reducing its size and making it more convenient for distribution.

You can now remove the world border using /wb clear all or just leave it if you wish.

Trimming the world folder

There are several files and folders located in your world folder that we can discard since the plugins do not use all of them. This will cut down the size of your world and make it easier to distribute.

For a NORMAL world Environment:

To prepare your world, keep the following files and folders:

1. region folder
2. raids.dat from within the data folder (ensure it's placed inside the data folder when copying)
3. level.dat file

You can safely delete all other files and folders located in the world folder. This will set up your world correctly for the NORMAL environment.

For NETHER and THE_END world Environments:

To prepare your world, keep the following files and folders:

1. region folder inside the DIM-1 folder (ensure it's placed inside the DIM-1 folder when copying)
2. raids.dat from within the data folder (ensure it's placed inside the data folder when copying)
3. level.dat file

You can safely delete all other files and folders located in the world folder. This will set up your world correctly for the NETHER and THE_END environments.

Running the package command

EliteMobs has the /em package <dungeonName> <version> command. This command goes through all the configuration folders of EliteMobs and automatically packages all content in folders that match the dungeonName into a zipped file and a normal folder in the exports folder of EliteMobs.

For this reason, it is highly recommended you keep the content you want to package in folders with the same name as the name of your package. Otherwise, you will have to manually gather and package the files into the file structure for distribution.

Adding the dungeon package file

If you are creating a dungeon, you will need to manually add the dungeon package file into the freshly generated folder in the exports folder. Your dungeon package configuration file should follow the format described above and be placed in a folder called content_packages. Check file structure for more on that..

Make sure you zip your dungeon once done!

File structure

If you did everything correctly, the file structure should be similar to this example, where we called the dungeon my_cool_dungeon:

my_cool_dungeon File Structure Example

• my_cool_dungeon.zip
  • content_packages
    • my_cool_dungeon.yml <- This is where your dungeon package configuration file goes
  • worldcontainer
    • [Your world folders go here]
  • wormholes
    • my_cool_dungeon
      • [Your wormholes go here]
  • npcs
    • my_cool_dungeon
      • [Your NPCs go here]
  • customtreasurechests
    • my_cool_dungeon
      • [Your treasure chests go here]
  • customquests
    • my_cool_dungeon
      • [Your quests go here]
  • customitems
    • my_cool_dungeon
      • [Your custom items go here]
  • custombosses
    • my_cool_dungeon
      • [Your custom bosses go here]
  • customarenas
    • my_cool_dungeon
      • [Your custom arenas go here]
  • powers
    • my_cool_dungeon
      • [Your custom powers go here]
  • world_blueprints
    • my_cool_dungeon
      • [Your world folder goes here, used for instanced dungeons]
  • customevents
    • my_cool_dungeon
      • [Your custom events go here]
  • customspawns
    • my_cool_dungeon
      • [Your custom spawns go here]
  • models
    • [Your ModelEngine bbmodel format models go here, accepts folders]
  • resource_pack
    • my_cool_dungeon_rsp
      • [Your resource pack files go here]

This allows most users to drag and drop files directly on to their server and have it working immediately.

Important: when packaging for distribution, make sure you UNINSTALL THE MINIDUNGEON FIRST! You don't want to distribute installed minidungeons, you want admins to set them up on their servers!

Sharing Dungeon Packages you've created with the community

Discord contains a #community_dungeons section where people can share their Minidungeon creations. Feel free to contribute!