What are Modular Dungeons?
Modular dungeons are a dungeon system introduced in BetterStructures 2.0.0 and later. Instead of spawning as one fixed schematic, modular dungeons are dynamically assembled from smaller, handcrafted modules. This approach allows for large, multi-floor dungeons that feel unique in every world while still fitting seamlessly into vanilla Minecraft.
How are modular dungeons generated
-
Modules Each module is typically built at a configurable size (default 16x16x16 blocks, though some content packs use 32x16x32 or other dimensions). Modules are designed with standardized connection points using a border tag system so they can attach to other modules without gaps or overlaps. The dimensions for a dungeon are set using the
moduleSizeXZandmoduleSizeYconfiguration options in the module generator config. Modules can contain corridors, rooms, staircases, or special encounter spaces. -
Generation process When a modular dungeon generates in a new chunk, BetterStructures uses a Wave Function Collapse (WFC) algorithm to procedurally assemble modules from the available pool. The system randomly selects compatible modules based on border tag matching and "stitches" them together into a complete dungeon. Generation time varies based on server performance, dungeon size (radius), vertical range, module count, and constraint complexity. The system uses workload distribution to prevent server lag during generation.
-
Dungeon size Dungeons can be configured to generate at various sizes using the radius parameter. Larger radius values create significantly bigger dungeons that can span hundreds of blocks. Most dungeons include multiple floors, linked through stair modules or vertical shafts. Vertical connections between floors are achieved through the
up/downentries of a module'sbordersborder-tag map: a module's top face joins to a neighbour above it when their opposing border tags match.
Variety and pack integration
-
Free Pack The Dungeoneering Modules Free Pack includes 15 modules. This functions as a fully playable dungeon on its own.
-
Premium Pack The Dungeoneering Modules Premium Pack adds 38 additional modules. When combined with the Free Pack, both sets intertwine into a single dungeon system with a much larger module pool. This reduces repetition and increases variety in the generated layouts.
-
Props integration If you also install the BetterStructures Prop Pack (via FreeMinecraftModels), modular dungeons will display custom model props throughout the builds, as shown in our showcase screenshots. Without the prop pack, the dungeons will still function normally, but without the decorative models.
EliteMobs Integration
While most of the dungeon relies only on BetterStructures and vanilla MineCraft mobs, some dungeons feature boss encounters:
- If EliteMobs and FreeMinecraftModels are both installed → full custom boss fight with model.
- If only FreeMinecraftModels is installed → boss model appears as a decorative prop.
- If neither is installed → boss room will simply be empty.
The system uses a sign-based spawn system with special tags to place entities and containers in designated areas. Boss levels scale based on distance from the dungeon center, providing appropriate challenge throughout the structure.
Module Sign Types
| Sign Tag | Line 1 | Additional Lines | Description |
|---|---|---|---|
[spawn] | [spawn] | Entity type on line 2 | Spawns a vanilla entity at the sign location |
[pool: poolname] | [pool: poolname] | — | Spawns a random boss from the named spawn pool |
[chest] | [chest] | — | Places a chest at the sign location |
[trapped_chest] | [trapped_chest] | — | Places a trapped chest at the sign location |
[barrel] | [barrel] | — | Places a barrel at the sign location |
[exit] | [exit] | Elevator schematic filenames on lines 2-3 | Marks an exit point with up/down elevator schematics |
If EliteMobs is not installed but a content pack requires it, administrators will receive a warning message.
This design keeps modular dungeons compatible with vanilla-style setups, while still offering deeper integration for users with additional plugins.
Spawn Pools
[pool: poolname] signs read from spawn pool configuration files in the spawn_pools/ folder. Each spawn pool file is a small YAML config with these fields:
| Field | Default | Description |
|---|---|---|
isEnabled | true | Whether this spawn pool is enabled |
poolStrings | [] | List of EliteMobs boss filenames eligible for this pool |
minLevel | -1 | Minimum level for instanced bosses spawned from this pool (-1 = unspecified) |
maxLevel | -1 | Maximum level for instanced bosses spawned from this pool (-1 = unspecified) |
When a [pool: poolname] sign is processed, BetterStructures looks for poolname.yml (optionally with the generator's spawnPoolSuffix appended) and picks a random boss from the pool's poolStrings. For instanced bosses, the spawn level scales between minLevel and maxLevel based on the boss's distance from the dungeon center.
MythicMobs Integration
BetterStructures also supports MythicMobs integration for custom mob encounters within modular dungeons.
When MythicMobs is installed, structure packs can spawn custom MythicMobs as part of dungeon generation. This allows for more sophisticated mob encounters and boss fights beyond what vanilla Minecraft or EliteMobs provide.
If MythicMobs is not installed, the plugin will notify administrators with appropriate permissions and provide a download link.
FMM Integration
Modular dungeons can also take advantage of FreeMinecraftModels (FMM) props during creation.
- If FMM is installed, any props placed by the module creator or builder will appear in the generated dungeon.
- Props are purely decorative and do not affect gameplay, but they enhance the visual fidelity and immersion of the environment.
- If FMM is not installed, the dungeon will still generate normally, but these custom props will not be displayed.
This ensures that creators can design dungeons with extra detail while maintaining compatibility for players who do not have FMM installed.
Module Dimensions
Important: Module size is configurable, not fixed.
Each module generator defines its standard module size using:
moduleSizeXZ: Width and depth in blocks (default: 16)moduleSizeY: Height in blocks (default: 16)
Default size: 16×16×16 blocks Common alternative: 32×16×32 blocks (used in some content packs)
For module creators:
- Check your generator config for
moduleSizeXZandmoduleSizeYvalues - Build ALL modules for that generator to match these exact dimensions
- Mismatched sizes will cause connection failures
Setting custom dimensions: In your module generator config file:
moduleSizeXZ: 32 # Width and depth
moduleSizeY: 16 # Height
Note: All modules in a generator must use the same dimensions. You cannot mix 16×16×16 and 32×16×32 modules in the same dungeon system.
Module Generator Config Fields
Beyond moduleSizeXZ and moduleSizeY, the module generator config supports the following fields:
| Field | Default | Description |
|---|---|---|
radius | 1 | Dungeon radius in chunks |
edges | false | Whether edge modules are generated |
startModule | — | List of starting module(s) for generation |
minChunkY | 0 | Minimum vertical chunk bound |
maxChunkY | 0 | Maximum vertical chunk bound |
moduleSizeXZ | 16 | Width and depth of modules in blocks |
moduleSizeY | 16 | Height of modules in blocks |
debug | false | Enables debug mode for generation troubleshooting |
useGradientLevels | false | Enables gradient-based level scaling for spawned entities |
spawnPoolSuffix | — | Suffix appended to spawn pool names for this generator |
isWorldGeneration | false | Whether this generator is used for world generation |
treasureFile | — | Treasure configuration file for chests in this dungeon |
generateLootInBarrels | true | Whether barrels in modules should be filled with loot |
barrelTreasureFilename | treasure_barrel_food.yml | Treasure configuration file used to fill barrels in this dungeon |
validWorlds | empty (all worlds) | List of valid world names where the dungeon can generate |
validWorldEnvironments | empty (all environments) | List of valid world environments (NORMAL, NETHER, THE_END, CUSTOM). The shipped dungeoneering generator explicitly ships with [NORMAL, CUSTOM], so out of the box dungeons only generate in overworld-type worlds. See the note below for what happens when the key is missing. |
centerModuleAltitude | 0 | Altitude for the center module |
Note on missing keys: the "Default" column above lists the value BetterStructures writes into a generated generator file. If you hand-write a module generator file and leave a key out entirely, the value actually used for that session comes from the Java field rather than from this column - which is 0 for radius, moduleSizeXZ and moduleSizeY, and "no restriction at all" for validWorlds and validWorldEnvironments. A missing validWorldEnvironments therefore does not restrict the generator to NORMAL/CUSTOM; it lets the dungeon generate in every environment. Always write the keys out explicitly instead of relying on omission, and let the plugin generate a file for you first if you are unsure.
Per-Module Config Fields
Each individual module can define the following configuration fields:
| Field | Default | Description |
|---|---|---|
isEnabled | true | Whether this module is enabled |
weight | 100 | Selection weight for this module during generation |
repetitionPenalty | 0 | Penalty applied when this module is selected multiple times |
noRepeat | false | Prevents this module from repeating |
enforceVerticalRotation | false | Enforces vertical rotation constraints |
enforceHorizontalRotation | false | Enforces horizontal rotation constraints |
minY | -4 | Minimum Y level for this module |
maxY | 20 | Maximum Y level for this module |
biome | default | Biome requirement for this module |
minecraftBiome | null | Minecraft biome requirement for this module |
treasureFile | — | Treasure configuration file for chests in this module |
generateLootInBarrels | true | Whether barrels in this module should be filled with loot |
barrelTreasureFilename | treasure_barrel_food.yml | Treasure configuration file used to fill barrels in this module |
borders | — | Border tag map defining connection compatibility |
cloneConfig | — | Clone settings from another module config file |
compoundModule | — | Links this module as part of a compound (multi-part) module |
isAutomaticallyPlaced | true | Whether the module is automatically placed during generation |
Note: Which faces of a module can connect to neighbours is controlled entirely by the borders border-tag map. Two modules join on a face when their opposing border tags match.
Note on cloneConfig: point it at another module's .yml filename and this module reads every cloned setting from that file instead of its own. When the clone target resolves, BetterStructures deletes the now-redundant keys from this module's file on disk - treasureFile, barrelTreasureFilename, generateLootInBarrels, borders, minY, maxY, weight, repetitionPenalty, the two rotation toggles, noRepeat, the six *IsPassable keys and isAutomaticallyPlaced. Only isEnabled, biome, minecraftBiome, cloneConfig and compoundModule stay local. If the named file does not exist the clone setting is ignored with a warning and the module keeps its own values.
You will also see northIsPassable, southIsPassable, eastIsPassable, westIsPassable, upIsPassable and downIsPassable written into generated module configs. They default to true and nothing in the generator reads them - changing them has no effect. Use borders instead.
Generating a dungeon manually with /bs generateModules
/bs generateModules <ModuleGeneratorsConfigFile.yml> runs a module generator on demand instead of waiting for one to appear during world generation. Tab completion lists every loaded module generator file.
What happens depends on the generator's isWorldGeneration setting:
isWorldGeneration: true- BetterStructures creates a brand new world for the dungeon. The world is named after the generator file with_0,_1,_2... appended, picking the first suffix whose folder does not already exist, so repeated runs never overwrite an earlier result. It is a flat void world withNORMALenvironment, spawn chunks not kept in memory and autosave disabled, and the player who ran the command is put into spectator mode.isWorldGeneration: false- generation happens in the world you are standing in.
A boss bar tracks progress while the lattice collapses and modules paste. If the generator has no usable startModule entries, the command reports that you need to install or build modules first and stops.
The command is refused while a content reload is running.
Where module files live
Modules go in plugins/BetterStructures/modules, which is scanned recursively - a content pack can keep its .schem files in subfolders and the matching .yml configs are generated alongside them.
Module schematic filenames must be unique across the whole modules tree. Two .schem files with the same name in different folders make config lookup ambiguous, and BetterStructures refuses to start rather than pick one. An enabled module config whose .schem cannot be read is also treated as fatal, so a broken module pack fails loudly instead of quietly generating dungeons with holes in them.