Dungeon Config

Every dungeon has its own unique config file that lets you further customize the dungeon's behaviour when played. This includes entry requirements, blocking certain potential out-of-bounds abuse (enderpearls, chorus fruit, etc), and reward cooldowns.

You can also modify the default-config.yml in the maps folder to change the default settings of a brand new dungeon.

An in-game editor for this config is planned for the future, but for now, you'll have to manually edit the config file.

NOTE: Gamerules are stored on the map itself and can be changed in-game with the standard /gamerule command while in edit mode.


How the config file is created and updated

A dungeon's config.yml is copied once from plugins/MythicDungeons/maps/default-config.yml, the first time the dungeon is loaded without one. It is never re-synced afterwards, so updating the plugin does not add new keys to existing dungeons. default-config.yml itself is only written when it is missing, so a plugin update does not refresh it either. Delete it and restart if you want the current one back on disk.

When a key is missing from a dungeon's config.yml, the plugin uses a built-in default instead. Four of those built-in defaults differ from what default-config.yml ships, so an old dungeon can behave differently from a freshly created one:

Key default-config.yml Built-in default when the key is missing
General.Lobby.Enabled false true
General.Gamemode SURVIVAL ADVENTURE
General.MaxInstances 5 0 (unlimited)
Rules.PreventExplosionBlockDamage false true

To pick up new options on an existing dungeon, copy the missing keys out of the current default-config.yml by hand.

Gamerules are not part of this file. They are stored in gamerules.yml next to it, written from the edit world when the dungeon is saved and re-applied every time an instance loads. Its keys are listed under The gamerules.yml file further down this page.


The default config file

Here is the default-config.yml provided by the plugin for your reference. It MAY contain features exclusive to dev builds, so check back here for new dungeon options!

One block has been moved in the listing below. The queue and ready-check overrides belong at the root of the file, not inside General:, so they are shown at the bottom here. See the warning under the block.

General:
  # Do not change! Used to track the config version when major updates happen.
  Version: 1
  DungeonType: CLASSIC
  # The generator to use for chunks in this dungeon. These can also be provided by other plugins.
  # natural = Default superflat.
  # mythicdungeons:void = Classic void generator, provided by Mythic Dungeons.
  # mythicdungeons:block.[BLOCKTYPE] = Generates entire chunks of a specific block. (For example, mythicdungeons:block.STONE would generate chunks at full height of all stone.)
  ChunkGenerator: natural
  # The pretty name of this dungeon that'll appear when it's finished and started.
  DisplayName: "&bA Dungeon"
  # Whether to show the display name above in a title message to the players when the dungeon begins.
  ShowTitleOnStart: false
  Lobby:
    Enabled: false
  # Where the player appears after leaving the dungeon via the "Finish Dungeon" function. (Use the /md setexit <dungeon> command.)
  ExitLocation: null
  # Whether to use the exit location for any time the player leaves instead of just when they finish the dungeon.
  AlwaysUseExit: false
  # What game mode the players will be in while in the dungeon.
  Gamemode: SURVIVAL
  # How many times the player can die before being unable to respawn. 0 will give the player infinite lives.
  PlayerLives: 0
  # Should players be shown minecraft's death screen when they die?
  InstantRespawnPlayers: false
  # Whether players who lose all their lives get put into spectator. If this is set to false, the player will instead be kicked from the dungeon.
  # NOTE: Spectators cannot use the spectator menu to exit the dungeon.
  DeadPlayersSpectate: true
  # Whether to close the dungeon when all players are spectating. If this is set to false, the dungeon will remain open until all players have left.
  # If set to false, players must use /md leave to exit the dungeon.
  # NOTE: This option only works if DeadPlayersSpectate is set to true.
  CloseDungeonWhenAllSpectating: true
  # Whether players keep their inventory upon entering the dungeon.
  KeepInventoryOnEnter: true
  # Whether players keep their current health upon entering the dungeon.
  # (Otherwise,they will be restored to full health upon entry, and set back to their previous health upon exit.)
  KeepHealthOnEnter: false
  # Whether players keep their current food level upon entering the dungeon.
  # (Otherwise, they will be restored to full food upon entry, and set back to their previous food level upon exit.)
  KeepFoodOnEnter: false
  # Whether players keep their current potion effects upon entering the dungeon.
  # (Otherwise, they will have all potion effects cleared upon entry.)
  KeepPotionEffectsOnEnter: false
  # Whether players keep their current EXP and level upon entering the dungeon.
  KeepExpOnEnter: true
  # Whether to kick players who disconnect during the dungeon.
  KickOfflinePlayers: true
  # How long to wait in seconds after a disconnect before kicking the player from the dungeon.
  KickOfflinePlayersDelay: 300
  # When a disconnected player rejoins, teleport them to their team's latest checkpoint so they
  # aren't stranded behind doors the group already passed. Only applies once a checkpoint is reached.
  ReturnToCheckpointOnRejoin: true
  # Charge a life when a player disconnects shortly after taking damage, so logging out mid-fight
  # isn't a free way to dodge a death. Only applies when PlayerLives is enabled.
  CombatLogPenalty: false
  # How many seconds after taking damage a disconnect still counts as combat-logging.
  CombatLogSeconds: 10
  # The maximum number of backups the plugin will save before deleting old backups.
  MaxBackups: 7
  # The maximum number of instances there can be of this dungeon at a time.
  MaxInstances: 5
  # How long in minutes until the dungeon is automatically ended and the players are kicked out. 0 will disable the time limit.
  TimeLimit: 0
  # How long in ticks to wait before cleaning up a dungeon when all players have left it. 0 will clean up the dungeon instantly.
  CleanupDelay: 0
  # The maximum number of players that can be in this dungeon. Used by the CONTINUOUS dungeon type.
  MaxPlayers: 0

  # When set to 'true', when players take items from reward functions, they'll be put in a rewards list.
  # Upon finishing the dungeon, the players will be given the rewards.
  GiveLootAfterCompletion: false
  # Loot Cooldown makes it so that players can't loot chests they've already looted recently.
  # Reward functions can be configured individually, or use the default values provided in this section.
  LootCooldown:
    Enabled: false
    # When true, each reward function tracks its own cooldown (per-chest).
    # When false, looting any reward starts a single dungeon-wide cooldown that blocks
    # all reward functions in this dungeon until it resets.
    PerReward: true
    # Setting this to TIMER will make it so the player can't get loot again until their cooldown is up.
    # Options like HOURLY, DAILY, WEEKLY, and MONTHLY will let you configure a set time for loot to be reset.
    CooldownType: DAILY
    # If type is set to TIMER, this is how many minutes until the player can acquire loot again.
    # Otherwise, this is the time of day when the reset occurs in hours.
    CooldownTime: 0
    # If type is set to WEEKLY, ResetDay determines what numbered day of the week the reset occurs.
    # "Sunday" would be 1, "Monday" is 2, "Tuesday" is 3, etc.
    # If type is set to MONTHLY, ResetDay determines what day of the month the reset occurs.
    # Doesn't do anything if CooldownType is set to "TIMER"
    ResetDay: 1

  # Access cooldown is used to limit how quickly a player can play this dungeon again after playing it.
  # NOTE: Be wary using this, as this can result in players being unable to play with each other if one of them has already run the dungeon recently!
  #    The "LootCooldown" section should be used instead to avoid this.
  AccessCooldown:
    Enabled: false
    # Whether to apply the cooldown when the player finishes the dungeon (via a "Finish Dungeon" function.)
    CooldownOnFinish: true
    # Whether to apply the cooldown when the player leaves the dungeon by any means.
    CooldownOnLeave: false
    # Whether to apply the cooldown when the player loses all their lives.
    CooldownOnLoseLives: false
    # Whether to apply the cooldown when the player starts the dungeon. If you have a lobby enabled, it won't apply the cooldown until a Start Dungeon function is activated.
    CooldownOnStart: false
    # Setting this to TIMER will make it so the player can't get run this dungeon again until their cooldown is up.
    # Options like HOURLY, DAILY, WEEKLY, and MONTHLY will let you configure a set time for access to be reset.
    CooldownType: DAILY
    # If type is set to TIMER, this is how many minutes until the player can player the dungeon again.
    # Otherwise, this is the time of day when the reset occurs in hours.
    CooldownTime: 0
    # If type is set to WEEKLY, ResetDay determines what numbered day of the week the reset occurs.
    # "Sunday" would be 1, "Monday" is 2, "Tuesday" is 3, etc.
    # If type is set to MONTHLY, ResetDay determines what day of the month the reset occurs.
    ResetDay: 1

Requirements:
  # A list of permissions the player must have.
  Permissions: []
  MinPartySize: 1
  MaxPartySize: 4
  # The maximum distance (in blocks) a party member may be from the party leader to be pulled
  # into the dungeon when the party enters. 0 disables the check. Members who are farther than
  # this (or in another world) are left behind in the lobby instead of entering.
  MaxPartyDistance: 0
  # When a member is left behind by MaxPartyDistance, whether to also remove them from the party
  # (true) or keep them in the party (false).
  KickDistantMembers: true
  # A list of dungeons the player must have completed. Note: "Finished" means the "Finish Dungeon" function was used in the required dungeon.
  DungeonsComplete: []
  # The minimum level needed to play this dungeon.
  # 0 disables the check.
  PlayerLevel: 0
  # What PlayerLevel measures: VANILLA (Minecraft experience level) or MYTHICRPG (active archetype level in MythicRPGGroup).
  # If MythicRPG is not installed, the check reads level 0 and everyone fails it.
  PlayerLevelType: VANILLA
  # The MythicRPG archetype group read when PlayerLevelType is MYTHICRPG.
  MythicRPGGroup: class
  # If a Vault-based economy is installed, it costs this much to play the dungeon.
  Cost: 0
  # Set to "true" if you only want to consume the above cost from the party leader.
  LeaderOnlyCost: false
  # A Mythic skill cast at the joining player to gate dungeon entry.
  # The skill controls its own conditions, messages, sounds, etc. To block
  # entry, the skill must call the 'denyjoin' mechanic. Cast per player, so
  # every party member is checked individually.
  #
  # Example skill (define in your MythicMobs/Skills/*.yml):
  #   Dungeon1_Gate:
  #     Conditions:
  #     - archetype{group=Class;equals=Warrior} false
  #     - archetypelevel{group=Class;min=20} false
  #     Skills:
  #     - message{m="<red>Warrior level 20+ only."} @Self
  #     - denyjoin @Self
  #
  # Then set:
  #JoinSkill: Dungeon1_Gate
  # Optional fallback message shown when the skill calls denyjoin without
  # sending its own message. Leave unset to use the default
  # 'instance.requirements.join-denied' lang entry. Supports color codes.
  #JoinDenyMessage: "&cYou don't meet this dungeon's entry requirements."
AccessKeys:
  # Whether to consume keys when players enter the dungeon using the key.
  Consume: true
  # Set to "true" if you only want to consume the key from the party leader.
  LeaderOnly: false
  # A list of itemstacks that are valid key items. NOTE: It is not recommended adding keys from here. Use the `/md addkey <dungeon>` command instead.
  # Mythic items are supported and will default to the latest version of the Mythic item (based on its namespace).
  KeyItems: []

Difficulty:
  # Whether or not to enable difficulty levels for dungeons.
  EnableDifficultyLevels: false
  # Whether or not to show a difficulty selection menu to the player when playing. Requires the above to ALSO be true.
  EnableDifficultyMenu: false
  # A list of difficulty options and how they affect the dungeon. You can name them whatever you want and have as many as you like!
  # Useful in combination with the "Dungeon Difficulty" condition.
  Levels:
    HARD: # EXAMPLE
      # An icon item that will represent this difficulty in the difficulty menu
      Icon:
        Material: DIAMOND
        #CustomModelData: 1
        Display: "&cHard"
        Lore:
          - "&cOnly for the truest gamers."
      # How much to increase the mobs health by (1.2 would be +20%)
      MobHealth: 1.5
      # How much to increase the amount of mobs coming from spawner functions (1.2 would be +20%)
      MobAmounts: 1.5
      # How much to increase the amount of damage mobs do by (1.2 would be +20%)
      MobDamage: 1.25
      # How much to increase all Mythic Mobs' levels by
      BonusMythicLevels: 1
      # A range of how much bonus loot to add to loot table and random rewards functions.
      # WARNING: Only works on Mythic Dungeons loot tables and 'random rewards' functions!
      # Mythic Mobs drop tables do not get bonus drops. Instead, use the `dungeondifficulty` mythic condition in your mythic drop table!
      BonusLoot: 1-3
      # Optional per-difficulty overrides for selected General settings. Any key omitted falls
      # back to the dungeon's base value above. Supported keys:
      #   TimeLimit, PlayerLives, MaxPlayers, KeepInventoryOnEnter, InstantRespawnPlayers
      #Overrides:
      #  TimeLimit: 15
      #  PlayerLives: 1
      #  KeepInventoryOnEnter: false
      # Optional per-mob overrides. Keys match the spawner's Mob field (MythicMob ID or
      # vanilla EntityType name). Any sub-key omitted falls back to the difficulty defaults
      # above (MobAmounts / MobHealth / MobDamage / BonusMythicLevels). Mobs not listed here
      # are scaled by those defaults as before.
      #   Count           - absolute spawn count (wins over CountMultiplier and MobAmounts)
      #   CountMultiplier - per-mob count multiplier (replaces MobAmounts for this mob)
      #   Health          - HP multiplier (replaces MobHealth for this mob)
      #   Damage          - damage multiplier (replaces MobDamage for this mob)
      #   BonusLevel      - additive level bonus (replaces BonusMythicLevels for this mob)
      #MobOverrides:
      #  BigBoss:
      #    Count: 1
      #    Health: 2.0
      #    Damage: 1.5
      #    BonusLevel: 5
      #  TrashMob:
      #    CountMultiplier: 2.5
      #    Health: 1.0
      #  zombie:
      #    CountMultiplier: 3.0

# Allows configuring a "map" item the players can get that displays the surrounding dungeon area.
Map:
  # Gives the players the map when they join. Effectively enables use of the map.
  GiveOnJoin: false
  # How fast the blocks on the map should fade out as the player rises higher.
  MaxRenderDepth: 10
  # Displays a floor label in the corner of the map based on the Y value the player is at. Useful for procedural dungeons.
  DisplayFloors: false
  # How many blocks along the Y axis the player must travel before we consider the player to be on a different floor.
  FloorDepth: 3
  # Whether to show icons for other players on the map instead of just the player holding the map.
  ShowAllPlayers: true

Rules:
  SpawnMobs: false
  SpawnAnimals: false
  SpawnMonsters: false
  AllowBreakBlocks: false
  AllowPlaceBlocks: false
  AllowSpawnEggs: true
  AllowEnderpearl: false
  AllowChorusFruit: false
  AllowBucket: false
  # Limits placing things that don't count as blocks like boats.
  AllowPlaceEntities: false
  # Whether players can drop items on the ground while playing the dungeon.
  # Key and dungeon items can never be dropped either way.
  AllowDropItems: true
  # Effectively sets RandomTickSpeed to 0 inside the dungeon, preventing blocks from spreading, plants from growing, ice from melting, etc.
  DisableRandomTick: true
  PreventPlantGrowth: true
  PreventExplosionBlockDamage: false
  PvP: false
  HideDeathMessages: false
  # Prevents players outside the dungeon from teleporting in. Admins can bypass with the `dungeons.bypassjoin` permission. (Or `dungeons.bypassjoin.[dungeon_name]`)
  PreventTeleportIn: false
  # Whether to allow all commands in the dungeon.
  AllowCommands: false
  # A list of commands that can still be used, even when "AllowCommands" is set to false.
  AllowedCommands:
    - party
    - dparty
    - p
    - dungeon leave
    - md leave
    - leave
  # A list of commands that CAN'T be used, even when "AllowCommands" is set to true.
  DisallowedCommands: []
  # Vanilla Minecraft item materials to ban. (Must be a valid Spigot material.)
  BannedItems: []
  # A list of more detailed items to ban from the dungeon. (Recommended to use the /md banitem command instead of modifying this directly.)
  CustomBannedItems: []
  # Toggles whether banned items can be picked up if they are on the ground in the dungeon.
  AllowPickupBannedItems: false
  # Toggles whether banned items can be crafted while inside the dungeon.
  AllowCraftBannedItems: false
  # Toggles whether banned items can be placed in or removed from storage in the dungeon.
  AllowStorageBannedItems: false
  # A list of blocks that are allowed to be PLACED in this dungeon, regardless of the "AllowPlaceBlocks" rule.
  # Remove the [] and add the blocks like a list as show in the comments.
  BlockPlaceWhitelist: []
  # - DIAMOND_ORE
  # - GOLD_ORE
  # A list of blocks that are allowed to be BROKEN in this dungeon, regardless of the "AllowBreakBlocks" rule.
  BlockBreakWhitelist: []
  # A list of blocks that are NOT allowed to be PLACED in this dungeon, regardless of the "AllowPlaceBlocks" rule.
  BlockPlaceBlacklist: []
  # A list of blocks that are NOT allowed to be BROKEN in this dungeon, regardless of the "AllowBreakBlocks" rule.
  BlockBreakBlacklist: []
  # Whether to let players break any blocks they've placed in this dungeon. Useful when "AllowPlaceBlocks" is true, but "AllowBreakBlocks" is false.
  # OVERRIDES THE ABOVE RULES!!
  AllowBreakPlacedBlocks: false
  # A list of Spigot entities that cannot be damaged.
  DamageProtectedEntities: []
  # A list of Spigot entities that cannot be interacted with. Useful for protecting Item Frames and Armor Stands.
  InteractProtectedEntities: []
  # A list of block-interaction categories to disable in this dungeon.
  # Available categories: DOORS, TRAPDOORS, BUTTONS, LEVERS, PRESSURE_PLATES, FENCE_GATES
  DisabledInteractions: []
  # When set to true, prevents armor, weapons and/or tools from losing durability while in the dungeon
  PreventDurabilityLoss:
    Armor: false
    Weapons: false
    Tools: false

# Per-dungeon overrides for the global queue/ready-check toggles in config.yml.
# These seven keys live at the ROOT of the file, NOT under General:.
# Uncomment any key to override the global value for this dungeon only. Omit a key to inherit the global.
#LeaderOnlyQueue: true
#ReadyCheckOnCommand: true
#ReadyCheckInQueue: true
#ReadyCheckTime: 45
#StartWithoutUnreadyPlayers: false
#ReadyCheckRequireLeader: true
# When 'true', this dungeon ignores the party system entirely on entry: a partied
# player enters alone (no group queue, no leader-only gating, no MinPartySize check
# against the party, no party-members-added-to-instance). Useful for CONTINUOUS
# dungeons where each player should enter independently.
#IgnoreParties: false

Careful: in the default-config.yml shipped today, that last block sits in the middle of the General: section. If you uncomment a line where it stands, the file stops being valid YAML and the dungeon will not load (Dungeon config has invalid YAML! in the console). Move the key you want to the bottom of the file, at column 0, instead.

Three comments in that file do not match what the code does:

  • Version is not read by anything. It does not drive any migration, and changing it does nothing.
  • KeepHealthOnEnter and KeepFoodOnEnter say the player is "set back to their previous health/food upon exit". That only happens when KeepInventoryOnEnter is false. With the shipped KeepInventoryOnEnter: true, health and food are never restored.
  • BannedItems is not limited to vanilla materials. MythicMobs item IDs work in the same list.

Dungeon types

General.DungeonType decides which dungeon class runs the dungeon. It is matched case-insensitively, and each type has extra aliases. See Dungeon Types for what each one does.

Type Also accepts
CLASSIC DEFAULT
CONTINUOUS ONGOING
PROCEDURAL GENERATED, ROOM

An unrecognised type stops the dungeon from loading without an error message in the console: the dungeon simply never appears in /md status. Check your spelling first if a dungeon goes missing after an edit. (Typing a bad type into /md create or /md import does print No dungeon type by name ... found!, but a hand-edited config does not.)

Keys that do nothing in certain dungeons

Where Key What happens
Procedural General.Lobby.Enabled Forced to false no matter what the config says. Procedural dungeons have no lobby.
Classic, Procedural General.MaxPlayers Only the CONTINUOUS type reads it, to decide whether a running instance still has room.
Classic, Procedural ContinuousDungeons.LoadAtStart Only the CONTINUOUS type reads it.
One-world mode General.ChunkGenerator Ignored. Every instance lives in the shared container world, which uses its own generator.
One-world mode Rules.DisableRandomTick Ignored. The shared world's random tick speed comes from Experimental.OneWorldDungeonsWorld.Gamerule.randomTickSpeed in the plugin config.yml instead, which ships as 0.
One-world mode Rules.SpawnMobs, Rules.SpawnAnimals, Rules.SpawnMonsters Partly ignored. The world-level spawn throttling is skipped, but natural and reinforcement spawns inside the dungeon's own area are still cancelled.
One-world mode The dungeon's gamerules (gamerules.yml) Mostly ignored, since one world cannot hold per-dungeon gamerules. Seventeen of them are re-created by the plugin instead (fifteen per instance, including doImmediateRespawn, plus doDaylightCycle and doWeatherCycle sent to each player individually). The rest are listed in the console as ignored, the first time an instance of that dungeon is created. Set those under Experimental.OneWorldDungeonsWorld.Gamerule in the plugin config.yml to apply them to every dungeon at once.

One-world mode is not a dungeon type. It is the server-wide Experimental.OneWorldDungeons switch in the plugin config.yml. See One World Dungeons.

Procedural dungeons keep their generation settings in a separate generation.yml file, not here. See Default generation.yml.


General

Key Default Values and behaviour
Version 1 Nothing reads this key. Changing or removing it has no effect.
DungeonType CLASSIC See the dungeon types section above.
ChunkGenerator natural natural (default superflat), mythicdungeons:void, mythicdungeons:block.[MATERIAL], or a generator provided by another plugin. Ignored in one-world mode.
DisplayName "&bA Dungeon" Colour codes supported. Falls back to the dungeon's world name in red if the key is missing.
ShowTitleOnStart false Shows DisplayName as a title to everyone when the dungeon begins.
Lobby.Enabled false (built-in default true) Forced off for procedural dungeons.
Lobby.Location not in the shipped file Written by /md setlobby while in edit mode. Stored without a world name.
StartLocation not in the shipped file Written by /md setspawn while in edit mode.
ExitLocation null Written by /md setexit <dungeon>. If the world it points at is not loaded when the dungeon loads, the plugin logs an error and clears it.
AlwaysUseExit false true sends players to ExitLocation every time they leave, not only when they finish the dungeon.
Gamemode SURVIVAL (built-in default ADVENTURE) Any Bukkit game mode name (SURVIVAL, CREATIVE, ADVENTURE, SPECTATOR), case-insensitive. An unrecognised value logs an error on entry and uses ADVENTURE.
PlayerLives 0 How many times a player can die before they can no longer respawn. 0 is infinite. Accepts placeholders. Can be overridden per difficulty.
InstantRespawnPlayers false Skips Minecraft's death screen. Can be overridden per difficulty.
DeadPlayersSpectate true false kicks players out of the dungeon when they run out of lives instead of putting them in spectator.
CloseDungeonWhenAllSpectating true Only has an effect while DeadPlayersSpectate is true.
KeepInventoryOnEnter true Also controls whether health, food and the saved inventory are put back on exit. Can be overridden per difficulty.
KeepHealthOnEnter false false heals the player to their max health on entry. The old health is only restored on exit when KeepInventoryOnEnter is also false.
KeepFoodOnEnter false false fills the player's food bar on entry, with the same restore condition as KeepHealthOnEnter.
KeepPotionEffectsOnEnter false false clears every potion effect on entry. Effects are never given back on exit.
KeepExpOnEnter true false sets exp and level to 0 on entry and restores the saved values on exit.
KickOfflinePlayers true Whether a disconnected player is eventually removed from the dungeon.
KickOfflinePlayersDelay 300 Seconds to wait after a disconnect before kicking. Accepts placeholders.
ReturnToCheckpointOnRejoin true A rejoining player is teleported to their team's latest checkpoint two ticks after they log back in. Only applies to players who are still alive, and only once a checkpoint has been reached.
CombatLogPenalty false Charges a life when a player disconnects shortly after taking damage. Only does anything when PlayerLives is enabled.
CombatLogSeconds 10 How many seconds after taking damage a disconnect still counts as combat logging.
MaxBackups 7 How many backup zips of this dungeon to keep before the oldest are deleted.
MaxInstances 5 (built-in default 0) Maximum instances of this dungeon at once. 0 is unlimited. The server-wide General.MaxInstances in the plugin config.yml (default 10) still applies on top of this.
TimeLimit 0 Minutes until the dungeon ends automatically. 0 disables it. Players are warned at 10 minutes, 5 minutes and 1 minute remaining. Accepts placeholders. Can be overridden per difficulty.
CleanupDelay 0 Ticks to wait before unloading an instance once the last player leaves. 0 or lower cleans up immediately. Edit instances and a plugin shutdown ignore it. Accepts placeholders.
MaxPlayers 0 How many players may share one CONTINUOUS instance. 0 or lower means no limit. Accepts placeholders. Can be overridden per difficulty.
GiveLootAfterCompletion false Rewards taken from reward functions are held in a list and handed over when the dungeon is finished.
Dimension not in the shipped file (built-in default NORMAL) NORMAL, NETHER or THE_END, uppercase. Written by /md create and /md import. Read case-sensitively with no error handling, so a lowercase or misspelled value stops the dungeon from loading.
Regions not in the shipped file A list of "x,z" region coordinates used by one-world dungeons. Managed with /md addregion and /md removeregion. An empty list makes the plugin copy every region file it can find and warns about it in the console.
DungeonItemInheritance not in the shipped file (built-in default true) When a player leaves, true hands their dungeon items to a player who is still inside. false simply removes them. Access keys are always inherited either way.

General.LootCooldown

Stops players from looting the same rewards again too soon. Individual reward functions can override these values.

Key Default Values and behaviour
Enabled false While this is false, no loot cooldown is ever applied.
PerReward true true gives every reward function its own cooldown. false makes looting any reward start one dungeon-wide cooldown that blocks all of them.
CooldownType DAILY TIMER, HOURLY, DAILY, WEEKLY or MONTHLY. Surrounding spaces and letter case are ignored. Anything else logs an error and falls back to DAILY.
CooldownTime 0 With TIMER, the number of minutes until loot is available again. With any other type, the hour of the day the reset happens.
ResetDay 1 With WEEKLY, the day of the week (Sunday is 1). With MONTHLY, the day of the month. Ignored by the other types.

General.AccessCooldown

Limits how soon a player can play this dungeon again.

Key Default Values and behaviour
Enabled false While this is false, no access cooldown is ever applied.
CooldownOnFinish true Applies the cooldown when the dungeon is completed, through either the "Finish Dungeon" function or the dungeoncomplete Mythic mechanic.
CooldownOnLeave false Applies the cooldown when the player leaves by any means.
CooldownOnLoseLives false Applies the cooldown when the player runs out of lives.
CooldownOnStart false Applies the cooldown when the dungeon starts.
CooldownType DAILY Same values and fallback as the loot cooldown above.
CooldownTime 0 Same meaning as the loot cooldown above.
ResetDay 1 Same meaning as the loot cooldown above.

Players with dungeons.bypasscooldown (or dungeons.bypasscooldown.<dungeon>) skip the check entirely, which is the usual reason an access cooldown appears not to work when an admin tests it.


Queue, ready check and party options

These seven keys are read from the root of the dungeon config, not from inside General:. Putting them under General: means nothing reads them. Each one is optional: leave a key out and the dungeon uses the server-wide value from the plugin config.yml.

Key Inherited from config.yml Value when set nowhere
LeaderOnlyQueue General.LeaderOnlyQueue true
ReadyCheckOnCommand General.ReadyCheckOnCommand true
ReadyCheckInQueue General.ReadyCheckInQueue true
ReadyCheckTime General.ReadyCheckTime 45 seconds. Accepts placeholders.
StartWithoutUnreadyPlayers General.StartWithoutUnreadyPlayers false
ReadyCheckRequireLeader General.ReadyCheckRequireLeader true
IgnoreParties nothing, this one is per-dungeon only false

IgnoreParties: true makes the dungeon ignore the party system on entry: a partied player enters alone, with no group queue, no leader-only gating, no MinPartySize check against the party, and no party members pulled into the instance. It is mainly useful for CONTINUOUS dungeons where everyone should enter independently.


Requirements

Checked when a player tries to play the dungeon.

Key Default Values and behaviour
Permissions [] The player must hold every permission in the list.
MinPartySize 1 Accepts placeholders.
MaxPartySize 4 Accepts placeholders.
MaxPartyDistance 0 Maximum distance in blocks between a party member and the party anchor (the leader while they are online, otherwise the player who started the entry). Members farther away are left behind instead of entering, and a member in another world or an unloaded world always counts as too far. 0 disables the check. Accepts placeholders.
KickDistantMembers true Whether a member left behind by MaxPartyDistance is also removed from the party.
DungeonsComplete [] Dungeons the player must have finished with a "Finish Dungeon" function. Entries that do not match a loaded dungeon are skipped.
PlayerLevel 0 Minimum level to play. 0 disables the check. Accepts placeholders.
PlayerLevelType VANILLA VANILLA (Minecraft experience level) or MYTHICRPG (archetype level in MythicRPGGroup). Case-insensitive, and anything that is not MYTHICRPG behaves as VANILLA. With MYTHICRPG and MythicRPG missing, the check reads level 0 and everyone fails it.
MythicRPGGroup class The MythicRPG archetype group read when PlayerLevelType is MYTHICRPG.
Cost 0 Requires a Vault-compatible economy. Accepts placeholders.
LeaderOnlyCost false Charge only the party leader.
JoinSkill unset A Mythic skill cast at every joining player, individually. To block entry the skill must call the denyjoin mechanic. The whole check is skipped when MythicMobs is not installed.
JoinDenyMessage unset Shown when JoinSkill denies entry without sending its own message. Defaults to the instance.requirements.join-denied lang entry. Colour codes supported.
ClassLevel not in the shipped file (built-in default 1) Nothing enforces this. It only feeds the %md_dungeon_<dungeon>_min_class_level% placeholder. Use PlayerLevel for a real level gate.

AccessKeys

Key Default Values and behaviour
Consume true Whether entering takes the key away.
LeaderOnly false Only take the key from the party leader.
KeyItems [] The list of items that work as keys. Use /md addkey <dungeon> rather than editing this by hand. Mythic items are matched by their namespace when MythicMobs is installed, otherwise items are compared for similarity.

The stack size stored on the key item is how many keys a player needs. Store a key item with an amount of 2, and a player carrying a single key does not have enough to enter on their own.


Difficulty

Difficulty levels scale mobs spawned by Mob Spawner functions and can override a handful of General settings. Pair them with the "Dungeon Difficulty" condition.

Key Default Values and behaviour
EnableDifficultyLevels false Nothing under Levels is parsed while this is false.
EnableDifficultyMenu false Shows a difficulty picker when playing. Requires EnableDifficultyLevels as well.
Levels.<NAME>.Icon.Material DIAMOND Any valid Spigot material. STICK is used only when the key is omitted entirely. An invalid material name logs Difficulty level <name> has an invalid icon! and leaves the icon unset, which throws a NullPointerException the moment the difficulty menu is opened. Fix the material name; there is no fallback.
Levels.<NAME>.Icon.CustomModelData unset Skipped when left out.
Levels.<NAME>.Icon.Display the example uses "&cHard" Defaults to the level's own name. Colour codes supported.
Levels.<NAME>.Icon.Lore the example has one line Defaults to an empty list.
Levels.<NAME>.MobHealth 0 when the key is left out Health multiplier for mobs from spawner functions (1.2 is +20%). Accepts placeholders.
Levels.<NAME>.MobAmounts 0 when the key is left out Multiplier for how many mobs a spawner function produces. Accepts placeholders.
Levels.<NAME>.MobDamage 0 when the key is left out Damage multiplier. Accepts placeholders.
Levels.<NAME>.BonusMythicLevels 0 when the key is left out Added to the level of every Mythic mob. Accepts placeholders.
Levels.<NAME>.BonusLoot "0" when the key is left out A range such as 1-3 of extra loot rolls. Only affects Mythic Dungeons loot tables and "Random Rewards" functions, not MythicMobs drop tables. Accepts placeholders.
Levels.<NAME>.BonusLootChances not in the shipped file Parsed but never used. It has no effect.
Levels.<NAME>.Overrides.<key> base value Only TimeLimit, PlayerLives, MaxPlayers, KeepInventoryOnEnter and InstantRespawnPlayers are honoured. Any other key here is read and then silently ignored.
Levels.<NAME>.MobOverrides.<mob>.Count none Absolute spawn count, which wins over CountMultiplier and MobAmounts. Accepts placeholders.
Levels.<NAME>.MobOverrides.<mob>.CountMultiplier none Replaces MobAmounts for this mob. Accepts placeholders.
Levels.<NAME>.MobOverrides.<mob>.Health none Replaces MobHealth for this mob. Accepts placeholders.
Levels.<NAME>.MobOverrides.<mob>.Damage none Replaces MobDamage for this mob. Accepts placeholders.
Levels.<NAME>.MobOverrides.<mob>.BonusLevel none Replaces BonusMythicLevels for this mob. Accepts placeholders.

MobOverrides keys must match the spawner function's Mob field exactly, and all scaling only happens while EnableDifficultyLevels is true and the instance actually has a difficulty.

Set MobHealth, MobAmounts and MobDamage on every level you define. A scale left out of a level is read as 0, not 1, so a level that only sets MobHealth gets a mob count multiplier of zero and its spawner functions produce nothing.


Map

Configures a map item that draws the dungeon around the player.

Key Default Values and behaviour
GiveOnJoin false Gives every player the map when they join, which is what enables the map at all.
MaxRenderDepth 10 How many blocks below the player the map still draws.
DisplayFloors false Shows a floor label in the corner of the map, based on the player's Y value. Useful in procedural dungeons.
FloorDepth 3 How many blocks of Y travel count as one floor.
ShowAllPlayers true Draw icons for the whole group instead of only the map holder.

The map is tagged as a dungeon item, so it follows General.DungeonItemInheritance and is stripped from players when they leave.


Rules

Key Default Values and behaviour
SpawnMobs false Allows natural mob spawning in the dungeon. Partly ignored in one-world mode.
SpawnAnimals false Allows natural animal spawning. Partly ignored in one-world mode.
SpawnMonsters false Allows natural monster spawning. Partly ignored in one-world mode.
AllowBreakBlocks false Allows breaking blocks.
AllowPlaceBlocks false Allows placing blocks.
AllowSpawnEggs true Allows using spawn eggs. Only right-clicking a block with the egg is checked.
AllowEnderpearl false Allows the ender pearl teleport. While false the pearl can still be thrown, but the teleport itself is cancelled.
AllowChorusFruit false Allows the chorus fruit teleport, the same way as AllowEnderpearl.
AllowBucket false Covers both filling and emptying buckets.
AllowPlaceEntities false Placing things that are entities rather than blocks, such as boats.
AllowDropItems true Whether players can drop items while playing. Keys and dungeon items can never be dropped either way, and edit mode is not affected.
DisableRandomTick true Sets the dungeon world's random tick speed to 0, so blocks do not spread, plants do not grow and ice does not melt. Ignored in one-world mode.
PreventPlantGrowth true Blocks block growth and block spread events.
PreventExplosionBlockDamage false (built-in default true) Stops explosions from breaking blocks.
PvP false Covers both melee and projectile damage between players.
HideDeathMessages false Hides the vanilla death message when a player dies in the dungeon.
PreventTeleportIn false Stops players outside the dungeon from teleporting in. Bypassed by dungeons.bypassjoin or dungeons.bypassjoin.<dungeon>.
AllowCommands false Allows all commands in the dungeon. Bypassed entirely by dungeons.admin.
AllowedCommands six entries (see the file above) Commands that still work while AllowCommands is false.
DisallowedCommands [] Commands that are blocked even while AllowCommands is true.
BannedItems [] Spigot material names and MythicMobs item IDs. /md banitem writes Mythic item types into this same list.
CustomBannedItems [] Full item stacks compared for similarity. Use /md banitem instead of editing this by hand.
AllowPickupBannedItems false While false, a banned item lying on the ground cannot be picked up and is removed.
AllowCraftBannedItems false Whether banned items can be crafted inside the dungeon.
AllowStorageBannedItems false Whether banned items can be put into or taken out of containers.
BlockPlaceWhitelist [] Materials that can always be placed, whatever AllowPlaceBlocks says.
BlockBreakWhitelist [] Materials that can always be broken, whatever AllowBreakBlocks says.
BlockPlaceBlacklist [] Materials that can never be placed.
BlockBreakBlacklist [] Materials that can never be broken.
AllowBreakPlacedBlocks false Lets players break blocks they placed themselves, overriding the rules above.
DamageProtectedEntities [] Spigot entity type names that cannot be damaged.
InteractProtectedEntities [] Spigot entity type names that cannot be interacted with. Useful for item frames and armor stands.
DisabledInteractions [] Categories of block interaction to switch off: DOORS, TRAPDOORS, BUTTONS, LEVERS, PRESSURE_PLATES, FENCE_GATES. Matched case-insensitively, and applied to right-clicks and to stepping on pressure plates.
PreventDurabilityLoss.Armor false Armor takes no durability damage in the dungeon.
PreventDurabilityLoss.Weapons false Weapons take no durability damage in the dungeon.
PreventDurabilityLoss.Tools false Tools take no durability damage in the dungeon.

A few details that are easy to get wrong:

  • SpawnAnimals and SpawnMonsters only matter while SpawnMobs is true. With SpawnMobs: false, nothing spawns naturally in the dungeon whatever the other two say.
  • AllowedCommands and DisallowedCommands ignore a leading slash on both sides and are matched case-insensitively. An entry matches the typed command exactly, or as the start of it followed by a space, so md leave matches /md leave but not /mdleave. Players with dungeons.admin skip the whole check.
  • An invalid material or entity name in the block lists and entity lists is logged in the console and skipped. It does not stop the dungeon from loading.

Options that are not in default-config.yml

These are read from a dungeon's config.yml but are not shipped in the default file. Add them by hand if you need them.

General:
  # When a player leaves, hand their dungeon items to a player still inside instead of removing them.
  # Access keys are always inherited, regardless of this setting.
  DungeonItemInheritance: true

# Casts a Mythic skill at the dungeon's start location on a repeating timer while the dungeon runs.
# (If the dungeon has no start location, the world spawn is used.)
# The value is the interval in seconds and must be 1 or higher; anything else is skipped with an error.
Skills:
  Tick:
    MyAmbienceSkill: 30
    MyHazardSkill: 5

# CONTINUOUS dungeons only.
ContinuousDungeons:
  # Keeps an empty instance loaded and waiting, so players never wait on a world load.
  LoadAtStart: false

General.Dimension, General.Regions, General.Lobby.Location and General.StartLocation also live in this file, but they are written by /md create, /md import, /md setlobby, /md setspawn and /md addregion. Set them with those commands rather than by hand: General.Dimension in particular is read case-sensitively, and a bad value stops the dungeon from loading.


The gamerules.yml file

gamerules.yml sits next to config.yml in plugins/MythicDungeons/maps/<dungeon>/. The plugin writes it from the edit world every time an edit session is saved, and applies it to every instance world as that world loads. The normal way to change any of it is to open the dungeon in edit mode, use the vanilla /gamerule and /difficulty commands, and save.

Key What it holds
Version Which layout the file is in. Do not edit it by hand: it is what tells the plugin whether the file still needs migrating, so a wrong number either skips a migration you need or reruns one you do not.
Difficulty The edit world's difficulty name, re-applied to every instance world. Defaults to NORMAL when the key is missing.
WorldTime The edit world's time in ticks at save.
WorldWeather CLEAR or DOWNFALL, from whether the edit world was clear at save. Any other value is read as CLEAR.
Gamerule.<rule> One entry per gamerule the server knows about, written straight from the edit world.

WorldTime and WorldWeather are written for every dungeon but only read in one-world mode, where the shared world cannot hold a per-dungeon time or sky. There, a dungeon whose values differ from the Experimental.OneWorldDungeonsWorld baseline in the plugin config.yml gets them shown to its own players as a per-player override. In every other mode the instance world carries its own time and weather, and these two keys do nothing. See One World Dungeons.

Gamerule paths are version dependent

The path under Gamerule. is whatever name the running server uses for that rule:

  • Before 1.21.11, the flat legacy name, for example Gamerule.doFireTick or Gamerule.keepInventory.
  • On 1.21.11+ and 26.x, the namespaced registry key with the colon written as a dot, for example Gamerule.minecraft.keep_inventory.

Hand-editing the legacy path on a modern server writes a key nothing reads. Read the file first and match the paths already in it.

The migration

Nothing migrates on a server before 1.21.11: the legacy paths are still the right ones there, and Version is left alone. On 1.21.11+ the file is brought up to Version: 3 on load, in one of two ways depending on what it says now.

Version missing or 1. The console logs Gamerule config for dungeon '<name>' is out of date! Updating..., and every entry is moved off the legacy paths:

  • doFireTick and allowFireTicksAwayFromPlayer are resolved together into the single integer fire_spread_radius_around_player (0 for fire off, -1 for spread with no player nearby, 128 otherwise).
  • disableRaids, disableElytraMovementCheck and disablePlayerMovementCheck are renamed to their positive form and their values inverted.
  • Every other rule is moved to its new path unchanged. A name the server does not recognise logs Unknown gamerule: <name> and is dropped; spawnChunkRadius is dropped silently because the rule no longer exists.
  • A Gamerule section that is present but empty is treated as damaged: the console logs Gamerules file corrupted!! Open this dungeon in edit mode and save to fix it!. Doing exactly that rewrites the file from the world.

Version: 2. Written by an earlier build that moved those three disable* booleans across without inverting them. Only that is corrected, in place (Correcting inverted gamerules for dungeon '<name>'...).

Invalid YAML anywhere in the file stops the dungeon loading, with Gamerule config has invalid YAML! in the console.

A rule that is simply missing from the file (a dungeon saved before that rule existed, or no file at all) falls back to the server's vanilla default, and the console notes each one it fell back on.


Values that accept placeholders

These options accept a plain number, a MythicMobs placeholder, or a math expression mixing the two (for example 2 + <dungeon.party.size>, or 30 + <dungeon.party.size> * 5). Placeholders need MythicMobs installed, and math expressions need MythicMobs Premium. Without them, the option falls back to its default.

General.TimeLimit, General.PlayerLives, General.MaxPlayers, General.CleanupDelay, General.KickOfflinePlayersDelay, ReadyCheckTime, Requirements.MinPartySize, Requirements.MaxPartySize, Requirements.MaxPartyDistance, Requirements.PlayerLevel, Requirements.Cost, and every Difficulty scale (MobHealth, MobAmounts, MobDamage, BonusMythicLevels, BonusLoot and all MobOverrides values).

Note that the %md_dungeon_<dungeon>_lives% placeholder reads General.PlayerLives as a plain number, so a dungeon that sets it to a placeholder or an expression reads as 0 there and displays Infinite. See Placeholder API.


Permissions that bypass these options

See Commands and Permissions for the full list.

Option Bypass permission
General.AccessCooldown dungeons.bypasscooldown or dungeons.bypasscooldown.<dungeon>
Requirements.Cost dungeons.bypasscost or dungeons.bypasscost.<dungeon>
AccessKeys dungeons.bypasskeys or dungeons.bypasskeys.<dungeon>
Rules.PreventTeleportIn dungeons.bypassjoin or dungeons.bypassjoin.<dungeon>
Rules.AllowCommands dungeons.admin
Updated Aug 19, 2026