Documentation by Kel and Catastrophe. Thank you Kel!

Implementing custom rooms is a job that requires two steps:

• Actually building the new rooms!
• Editing the config to include your new work.

Explaining the config changes first will also help explain how the mod works.

Config Settings

All configs related to custom rooms are in the located in the common config. The name of this file will be dimdungeons-common-r174.toml (or whatever the latest version is) and it will be found in the same /config folder as the client config.

Room Sets

This config has separate sections corresponding to the dungeon types. The two tiers of dungeons are referred to in the config as basic and advanced. These are defined with the [roomsTier1] and [roomsTier2] selectors. Each selector has a list of room types and the valid rooms that can spawn in them. (Which you will build with structure blocks.) The format is as follows:

roomSelector = [assetlocation:roomName1], [assetlocation:hardRoom1, assetlocation:hardRoom2], [assetlocation:loot1](/AllenSeitz/DimDungeons/wiki/assetlocation:roomName1],-[assetlocation:hardRoom1,-assetlocation:hardRoom2],-[assetlocation:loot1)

The config expects a list of list items. The room selected when spawning a new room will be somewhat randomized between the outer lists, then a random room from the inner list is selected. This is important for determining the weight or frequency of a room. For example consider these two similar looking examples:

Example A: 66% chance of entrance_1 basicEntrances = [dimdungeons:entrance_1, dimdungeons:entrance_1, dimdungeons:entrance_2](/AllenSeitz/DimDungeons/wiki/dimdungeons:entrance_1,-dimdungeons:entrance_1,-dimdungeons:entrance_2)

Example B: 75% chance of entrance_1 basicEntrances = [dimdungeons:entrance_1], [dimdungeons:entrance_1, dimdungeons:entrance_2](/AllenSeitz/DimDungeons/wiki/dimdungeons:entrance_1],-[dimdungeons:entrance_1,-dimdungeons:entrance_2)

In Example A there is a single list with 3 items so the odds of any item being picked is 1/3. In Example B there are two lists. So first a coin is flipped to pick one of the lists, then a random item from the chosen list is picked.

Back to the room sets themselves. The selectors for the basic and advanced dungeons are:

• basicEntrances: There is one of these at the start of each dungeon.
• basicFourways: Connectors between 4 rooms.
• basicThreeways: Connectors between 3 rooms.
• basicHallways: Straight connectors between 2 rooms.
• basicCorners: Corner connectors between 2 rooms.
• basicEnds: Rooms that have no exits other than the way a player enters.
• advanced (Entrances/Fourways/Threeways/Hallways/Corners/Ends): Same as above.
• advancedLarge: a larger room that only spawns in advanced dungeons.

If you want your custom rooms to appear in the basic or advanced dungeons then you should add or remove rooms from the [roomsTier1] or [roomsTier2] selectors. Be mindful of how the rooms are weighted. Otherwise if you are making an entirely custom dungeon then you will want to make a new theme. (It is possible to completely customize the basic and advanced dungeons by replacing every default room too!)

Enemy Sets

This section determines which enemies will spawn in a given tier of dungeon. (Theme enemy sets are declared with the section for that theme.) This works similar to the room sets except that it is just a single list. For example:

basicEnemySet1 = ["minecraft:zombie", "minecraft:husk", "minecraft:drowned", "minecraft:spider"]

Very simple. Each dungeon and theme has two enemy sets. By default the first enemy set is slower, easier enemies. While the second enemy set is harder enemies with ranged attacks. But you can change these to be whatever you want.

The enemies in Dimensional Dungeons are spawned with data blocks, similar to Shulkers in vanilla End Cities. Data blocks named "SummonEnemy1" and "SummonEnemy2" will be replaced with a random monster from the given list when the room is built.

There are also config settings to scale the HP and damage of any enemy spawned by this method. Be aware that scaling the damage doesn't quite work for every mob. Skeletons and Pillagers only deal damage based off their bows, and Blazes with extra damage will only have their melee attack boosted.

Finally there is one other important variable for the number of themes used. numberOfThemes = 3 This variable is out of place in this section, sorry. But it is very important for knowing which themes are used and which are unused, since the config leaves room for up to 99 themes.

Theme Sets

There are a maximum of 99 themes available which are pre-defined in the config file. Themes 4 through 99 are blank and are free for use by pack devs. If you want to replace an existing theme be aware that theme #2 (the desert) has hardcoded properties and will not behave like the others. It is recommended to only create new themes.

Translation strings for theme numbers beyond 4 can be added to Minecraft's lang files as usual.

The theme selectors are the same as the selectors from the tiered dungeons, just with different naming schemes. There is an additional variable to change, themeDungeonSizeN, where N is the theme number. This defines how many rooms the theme dungeon should generate, not including the entrance. So, a room size of 0 will just be a single entrance room. The dungeon will always generate an entrance, so one is always needed. (In fact, if there is no valid entrance for the dungeon to make, it will just not generate at all.)

Changes made to the config require a full restart to take effect!

Changes made to a structure only require a /reload command to take effect!

Designing New Rooms

The dungeon logic makes several assumptions about the room structures that you must obey for your room to work correctly. First and foremost all rooms (except large rooms) must be exactly 16x16 blocks. (And they will be built chunk aligned.) It used to be required for the rooms to be exactly 13 blocks tall but now rooms can be any height as long as the doorways are 5 blocks up from the bottom. Many rooms are still 13 blocks tall.

If you are building a custom theme then you can be flexible about the doorway requirements as long as you are consistent with every room in your entire room set. Remember that rooms can be rotated.

Generic Rules and the basic_template

The best way to convey the requirements of room building is through pictures and an example room. The base rooms provided by DimDungeons have an unused template room for exactly this purpose: dimdungeons:basic_template. It is recommended that you create a new superflat world and load this structure as your first step towards building new rooms.

To use KubeJS, the following file-path is required:

.minecraft/kubejs/data/nameofpackage/nameofstruct.nbt -> nameofpackage:nameofstruct

Template Room: Doors should remain where they are placed here, which is in the center of the chunk. To make other room shapes besides a 4-way intersection these doors can be walled off. The map on the roof is made out of red concrete and is visible if the player uses a vanilla blank map!

Entrance Rooms

Entrance rooms have extra specific requirements. First, there must be a return portal and it must be at a very specific position in the structure. This is to ensure there is a return portal available for the player so they do not get stuck in the dimension. The portal location is relative to the structure block location as seen in the image.

The return portal should be built of 6 data blocks in exactly that spot and have "ReturnPortal" defined in the data field. (You can change a structure block to a data block by holding alt when clicking the load/save/corner button).

Example image of changing a structure block into a data block.

Additionally, the roof should have the entrance marked with a fancy arrow. (Again - for the map.) All of these requirements can be met automatically by using dimdungeons:entrance_1 as your template instead. Just load that room, break and rebuild anything that isn't the roof or the return portal, and re-save it.

Example of an entrance room with only the blocks you should leave unbroken.

Fourway Room

There's not much to say about these rooms. They can still be rotated, though, so plan on that. A good example room is dimdungeons:combat_3.

Room combat_3.

For reference, what these rooms look like on the outside. This is my building world.

Threeway Room

The one missing door should be the north one. West, east, and south form a 'T'. This is important for when the room is rotated!

The room dimdungeons:hiddenpath_3 a good example of a threeway room that you can use as a base for your creations. It highlights two other design principles that haven't been covered yet:

• Do not allow redstone to touch the outside of the room. (When possible.) You never know when another room, also with redstone on the edges, could form an accidental connection. Some of my oldest rooms break this rule.
• When implementing hidden passages you must ensure that the passage is passable from both sides. You can't assume which direction the player is coming from. (Such as if it is rotated.) dimdungeons:hiddenpath_3. Coincidentally the red concrete on the roof matches the red carpet on the floor!

Hallway Room

Hallways must be saved facing north and south. For an example try dimdungeons:hallway_6. It's not one of my proudest rooms. In fact it's one of my oldest. But it is very simple.

Corner Room

Corners must be saved while connecting north and east. I tend to build simple corners like dimdungeons:longcorner_3 but MagpieMaydin built an elaborate corner with dimdungeons:skullcorner_1.

Dead End

The one single door must be on the south side of the room. In addition, the roof's red concrete is a little different. Look at dimdungeons:magicpuzzle_1 or dimdungeons:spawner_1 for an example.

The spawner room in particular intentionally changes the typical roof concrete patterns in order to place extra information on the map!

Large Rooms

TODO

Data Blocks

Several rooms use data blocks to spawn mobs or make changes to a structure after it is built. Surprisingly, this is a vanilla feature, even though only Mojang is able to fully utilize it without mods. For example, the treasure chests in Ocean Ruins and Shulkers in End Cities are placed with data blocks. You cannot define your own data blocks but you can use these data blocks that I have implemented for you.

• ReturnPortal - Must be used in entrance rooms. (And exclusively in entrance rooms.)
• BackToEntrance - Creates a teleporter that sends the player back to the entrance room just like a Homeward Pearl.
• FortuneTeller - Place above a Dispenser. First inserts a random written book into that Dispenser, then becomes stone_brick.
• ChestLoot1 - Place above a Chest. Sets the loot table to either chests/chestloot_basic_easy or chests/chestloot_advanced_easy.
• ChestLoot2 - Place above a Chest. Sets the loot table to either chests/chestloot_basic_hard or chests/chestloot_advanced_hard.
• • Use these data blocks for rooms that appear in both tier 1 and tier 2 dungeons to ensure they get the correct loot.
• • Otherwise you can place chests with whatever loot table you want directly set on the block entity NBT.
• ChestLootKit - Place above a Chest. Sets the loot table to chests/kit_random.
• ChestLootLucky - Place above a Chest. 30% chance to set the loot table to chests/chestloot_lucky. 70% chance to erase the chest instead.
• • In other words, you're lucky if you see this chest. It's meant to add a little variance to the chest positions.
• • The lucky chests by default roll from desirable vanilla loot tables. Advanced dungeons use chests/chestloot_crazy instead.
• PlaceL2Key - Place above a Portal Keyhole Block. Inserts a blank tier 2 key in that keyhole.
• SummonEnemy1 - Places an entity from the first entity list. (In the config.)
• SummonEnemy2 - Places an entity from the second entity list. (In the config.)
• SummonWitch - Places a Witch.
• SummonEnderman - Places an Enderman.
• SummonWaterEnemy - Places a Guardian.

Dimensional Dungeons Hacks

One-Room Dungeon

It is possible to use a larger structure as the only ‘room’ in a dungeon. The portal placement requirements still apply, and the room is expanded as below:

More space is added to the positive X and Z directions. The theme config needs to be defined as follows:

#Settings for Boss Theme [dungeonThemeN] themeEntrancesN = ["dimdungeons:roomair"](/AllenSeitz/DimDungeons/wiki/"dimdungeons:roomair") themeFourwaysN = ["dimdungeons:roomair"](/AllenSeitz/DimDungeons/wiki/"dimdungeons:roomair") themeThreewaysN = ["dimdungeons:roomair"](/AllenSeitz/DimDungeons/wiki/"dimdungeons:roomair") themeHallwaysN = ["dimdungeons:roomair"](/AllenSeitz/DimDungeons/wiki/"dimdungeons:roomair") themeCornersN = ["dimdungeons:roomair"](/AllenSeitz/DimDungeons/wiki/"dimdungeons:roomair") themeEndsN = ["dimdungeons:roomair"](/AllenSeitz/DimDungeons/wiki/"dimdungeons:roomair") themeEnemySet1_N = ["minecraft:skeleton"] themeEnemySet2_N = ["minecraft:skeleton"] themeEnemyHealthScalingN = 1.0 themeDungeonSizeN = 1

Where "dimdungeons:roomair" is a blank 0x0x0 structure. (It already exists in most versions of this mod.) It is recommended to place walls on the edge of the structure to prevent players from falling off into the void.

Notice how the door awkwardly appears in the middle of the room. I'm sorry, but the door cannot be moved. This is a limitation that you will have to work around. Someday I hope to have better support for large rooms and unusual entrances.

Here is a picture of how to save a large entrance, and how it looks in game.

Tall Rooms

Even in tiered dungeons where most rooms are 16x13x16, rooms can still be made "tall". Just make sure the doorways are still where they should be on "the lower floor".

Crafting and Looting Keys to Specific Themes

Theme keys are defined under the item ID: dimdungeons:item_blank_theme_key

When providing a new key to a player from a crafting recipe, the theme NBT value needs to be set to the desired theme number. It will then need to be activated as usual. It will always activate to the set theme.