Room Modding Tutorial

Getting Started
This is a basic tutorial that gets you started in creating rooms for the game. There are a few best practices that you should follow in order to have a working room and to create rooms fast and with good quality. Lets get started with the basic idea how room files are structured and what they're made up of:

All .room and .tile files are saved in the ADVR folder where you find the .exe file under Ancient dungeon VR Beta_Data/gamedata/DUNGEON_TYPE/

After you have gone through this tutorial and do not know what to create or want inspiration, all rooms and tiles that are currently in the game can be opened by the editor for you to explore.

Building Blocks
Building blocks are the smallest piece that is put in a room, for example: pots, crates, pillars, etc.

Tiles
Tiles are made up of building blocks with a size of 4x4 and are used as a quick way to store different looking constellations in the rooms.

Rooms
Rooms are made up of individual tiles, that are arranged in a grid-like fashion. For each position in a room, there is at least one tile that will spawn at that position. It is also possible to specify more than one tile for a certain position, which then gets chosen randomly.

So, as you can see, the general workflow in creating a room is to build it out of .tile tiles that are already there and then add some additional extra objects. That's the basic workflow. There are a lot of things you can do additionally that we'll cover later.

Creating your first Room
There are two options that you can choose from: New Room and New Room (VR MODE). It is recommended to build your room in the Flat version and to refine and improve it with the VR version, as it is typically faster to build on flatscreen

  First, we want to select a size for our room that fits. Its possible to create rooms with a size of up to 8x8, but note: Due to how the world generator works, big rooms are less likely to occur than small rooms, so keep that in mind when designing rooms. It is advised to keep rooms at a size of around 18 tiles or smaller (so 4x4, 5x3, 6x3, etc). For this example, lets create a room with a size of 3x3. In order to do that, move the SizeX and SizeY Slider to 3. Then click New Room.

You should now see the room overview.

Setting up the room correctly
Before you start working on the room design, you should at first configure your room correctly. In order to do so, look to the bottom right of your screen at the Room Settings.


 * Add Flag: We want our room to be able to spawn chests, have pots, and crates. So we select Add Flag --> Crates, Add Flag --> Pots, Add Flag --> Chests. This adds room flags to the room, that allow it to spawn certain kinds of decoration and props randomly. Click Regenerate to see the changes.


 * Ceiling Height: There are two different room heights that a room can have. You can select between low and high ceiling. For this tutorial, we'll just leave it at high ceiling


 * Probability: When the world generator selects a room, it takes a random one of the valid rooms that are in the game. A probability of 100% does not mean that the room will spawn every run, it just means that if the room gets rolled, it will spawn. If you reduce the probability, an additional roll gets done once the room gets rolled that determines if it will spawn or not. For this tutorial, we just leave this at 100%. If you want to build a rare or special room, feel free to lower the value.


 * Allow Duplicates: Most rooms are allowed to spawn multiple times in the same dungeon, for example challenge rooms or normal enemy rooms. If you have a special room (or a shop, etc.) that should only appear once in the dungeon, set it to off.


 * Room Type:  Here you can select what type of room you're creating. Most of them are self explanatory but a few of them require special attention. If you're creating a basic room with enemies or items, just leave it at default. If you want to create another room type, look at the advanced tutorials that describe how to do them, because they require special attention and a few extra tweaks.


 * Room Theme:  We want to create a room for the overgrown dungeon, so we just leave it as it is. If you want to create a room for another theme, change it.



 

Now that we have set up our basic room. We can start to place tiles in it.

Selecting tiles in the room
To select which tile will spawn on which position, select the middle of the room by clicking on it. You should see a green selection box appear on the tile you selected. On the right, the Tile Settings panel should pop up and give you a few different options.


 * Ground Type: Used for setting the type of ground that this tile has. Default is stone, but there are others that you can just try out.
 * Ceiling Type: Same as ground type but for the ceiling.
 * is Door: Can corridors connect to this tile? Only use this on places where you want corridors to connect to.
 * door type: Type of the door object that spawns. If left to default it will just be a normal hole like most rooms have.

For this tutorial, leave all this settings on normal for the center tile. In order to change the tile that spawns, select the tile that you want in the Tile ID selection screen. As you can see, you have now selected 2 tiles that can spawn at this position. Click regenerate a few times to see the tile changing between the two you have selected. In general, it is a good idea to always have a few tiles in your room that can spawn differently so you have more variety in your dungeons. To do this, we also select EMPTY as third tile that can spawn in the middle. Again, click regenerate to see the room change appearance.

Adding doors
Now that you have a general layout of the room finished, it is time to add doors. Without doors, your room can't connect to other rooms in the dungeon.  

For this room, we set 4 tiles as being a door. It will be the ones in between the corner tiles. So, we select each of those and set is Door in the tile settings to ON. Once you have done that, your room should look like this:

Small additions in the tile settings
The room should work now in the generator. To make the room a bit more interesting, we select a corner tile, and set the ground type to Pit. We then select another corner tile, and add a Highgrass tile to the possible tiles. Press regenerate a few times to see how many different appearances the room can have.

Adding even more stuff
At this stage, your room is basically finished (only missing enemies). Depending on what room you're planning to do, it may be useful to add building blocks in the room directly without a tile associated to them. This can be done by enabling Extra Objects Mode in the top bar.

There you can place all kinds of stuff in the room to create a truly unique experience. For this room, we do not need to do it, but more advanced rooms will require you to place some extra stuff, like railings, pillars, tables, items etc.  

Placing enemies
In order to place enemies, enable Extra Objects Mode and select MOBS. You will see the ENEMY_SPAWN object. Click it and place it in the room.

You should now see a small purple cube that says "empty". Now, right click the cube to open the enemy selection panel.

In the enemy selection panel you can select all enemies that can spawn there. For example, we can select: Homing Plant and 4x Plant and the object should update the names accordingly. This spawn will now choose between the two enemies you have chosen randomly when the player approaches it in game. You can select how many you like.

Saving and testing the room
Now that you have finished your room. You can save it with a useful name and save it under Ancient dungeon VR Beta_Data/gamedata/overgrown_dungeon/rooms/ folder.

Please try to name the room according to the naming convention to make it easier to tell them apart.

DUNGEON TYPE (2 letters) _ YOUR NAME _ ROOM TYPE/THEME/IDEA

So for the room we just created, we name it:

There are two types of checking out your room and testing it. The first is to open the room editor in VR MODE and just fly through it and look at it. The other way is to go into the game (experimental beta 0.5), open the console with 'c' and type the following command:

Hit enter and you should be teleported into the room you have built. You don't need to write down the whole room name, for example you can also just write part of your room name, but it must be unique so that no other room might match the pattern.

Once your room file is in the gamedata folder, it will also generate naturally during your runs.

Once you're satisfied with the room. Send me the room file over discord in the  channel! If they're good and fit the theme of the dungeon, they will be put in the official game.

Creating a room in VR Mode
Please make sure you know how to create rooms in flatscreen before attempting to do it in VR as it is almost the same procedure.

Placing enemies is not yet supported in VR Mode, but it will be soon.

The best way to create rooms in VR mode is to have the Desktop view in SteamVR open to interact with the Start UI. Once you have created the room you can close it and work in VR.

The workflow is the same as in the Flat version, but with different controls:


 * Grip Button Right: Switches between UI interaction and world interaction. So if you want to select something in the UI you need to press and hold the grab button on your right controller (the selection ray should become green).
 * Trigger Right: Selects the current tile/object/ui button depending on which mode you're in or places the building block down
 * Left Menu Button: When you're in extra object mode and have a building block selected, you can rotate it by 90 degrees with this button (same as R in flat mode)
 * Trigger Left: When you're in extra object mode and have the select ray over a building block, clones the object
 * Right Menu Button: When you're in extra object mode and have a building block selected you enter the (really clunky) hand rotation mode
 * Right Thumbstick: When you're highlighting the UI can be used to scroll down dropdowns, etc. Otherwise its used for movement
 * Left Thumbstick: When you're in extra object mode, same as using the scrollwheel to move up/down objects.

Best Practices for creating a room
These best practices are very important when creating a room so please follow them.


 * Doors: Be sure to add enough doors so that the generator can easily connect corridors to your room. It is possible to create rooms with less doors or doors that only go North and South but it should make sense for the room you're creating.
 * Difficulty: Be sure to test the room for appropriate difficulty. Don't spawn too many enemies at the player and place enemies at positions that make sense.
 * Room Size: Be aware, that large rooms can spawn less often than small rooms.
 * Chests / Pots / Torches / Deco: Please only place pots, chests, torches and decoration if you think it is really needed. The generator takes care of that itself, for example you do not need to place chests in the rooms (use the 'chests' flag for that). There can be instances where it is a good idea to always have a chest spawn at the same place (e.g. a secret room, some special room that benefits from it), but in general the generator places chests and decoration automatically. Keep in mind that if you place a chest manually, the generator does not count that as a spawned chest, which means there are now more chests on the floor, which can break balancing if done too excessively.
 * Room Design: Its a good idea to have one or two tiles in your room that spawn different tiles (e.g. highgrass or ground) to have your room have more variety. Important: Do not overdo it, rooms should still look coherent and have a style that fits.
 * Performance: While it may look awesome placing tons of grass and vines, these models have a lot vertices and can impact performance of your room, especially on Quest. So please keep vertex/triangle count and light sources to a minimum. The exact amount of verts still needs to be tested, once that is clear a vert counter will be put in the room builder.

Creating a Start Room
Start rooms are created the same way as you would create another room. There are just a few small things you need to do additionally.


 * The red arrow that you can see in the builder corresponds to the direction the dungeon spawns. The start room will spawn South and the Boss room will spawn north. So ensure that the door of the start room faces in the correct direction.
 * Only use doors that are on the north part of the room. If you have a door on the southern part, nothing will happen because that part is on the bottom edge of the dungeon map.
 * You must place a SPECIAL -> SPAWN_ENTRANCE_DUNGEON object. This is where the player will spawn once the dungeon has generated.
 * Don't put enemies in the start room and try to shield the player from enemies that can spawn close.

After that you're good to go.

Creating a Boss Room
Boss rooms are created the same way as you would create another room. There are just a few small things you need to do additionally.


 * The exit of the dungeon needs to face north (red arrow) because the boss room always spawns at the northern end of the dungeon
 * Set the room size to the desired size but with +1 in the y direction in order to place the exit.
 * The boss entrance door should be on the southern side of the room.
 * It is only possible to create wave boss rooms at the moment (also there aren't other bosses other than the plant which will get reworked at some point)
 * Place SPECIAL -> BOSS_WAVE_SPAWN in the room where you want the monsters to appear. At the moment each one of these spawns will spawn 3 waves of monsters, so the more wave spawn objects you have the more enemies will also spawn.
 * Place the SPECIAL -> BOSS_WAVES_ACTIVATOR object in the boss room. If the player collides with it, it will start the wave spawning procedure. That's why you need to build the room in a way that the player can't run around it. Also, place it a bit away from the boss door, so the player does not trigger it too early.  You can check the provided boss room for an example.
 * Select a tile in the northern part of the dungeon and set it to the FLOORCOMPLETEHANDLER tile.

After that you're good to go.

Creating a Challenge Room
Challenge rooms are created the same way as normal rooms with a few additional settings:


 * Set all doors to door type: challenge.
 * Place a SPECIAL -> CHALLENGE_SPAWN in the middle of the room

After that you're good to go.

Challenge Spawning will be reworked a bit in the future to allow more customization.

Creating a Corridor Variator
Corridor variators are tiles that will spawn randomly instead of a normal corridor part. For example the high grass parts in the corridors, or the bridge with the pit. Corridor variators help giving the corridors more stuff to do and place enemies etc.

There are two types of corridor variators: directional and uniform corridor variators.

Directional corridor variators are only placed in places where the northern and southern side have corridors connected to it (e.g. the bridge variator).

Uniform variators can be placed everywhere in the corridor and have no direction associated with them.

''NOTE: Corridor variators are not really treated as tiles in the generator. That's why you can't select a tile for the variator, only extra objects, ground type and ceiling type. Please leave the tile to GROUND.''

Creating a uniform variator
To create a uniform variator, create a room with a size of 1x1, set the ceiling height to low and room type to corridor_var_uniform.


 * Place the objects in the variator that you want and save it.
 * NOTE: The tile for the room is of size 4m x 4m, but corridors have their walls inset by 0.5m. That means depending on how the corridors spawn, it is possible that the corridor is only 3m x 4m (for example in a straight line). Please ensure that you don't have objects that are too close to the walls.

Creating a directional variator
To create a directional variator, create a room with size 1x1, set the ceiling height to low and room type to corridor_var_directional


 * Check the floor for the red arrow. That is the direction of the corridor. Keep that in mind.
 * NOTE: Keep in mind that the variator will be only 3m wide instead of 4m because of the wall inset.

The corridor variator creation process will be improved in the future.

Creating a Secret Room
Secret rooms are rooms that can spawn next to already existing rooms or corridors, mostly with a door between them.

The door type can be freely chosen. For example the hidden shop has a door type of secret. But also the 1x1 rooms that are behind a closed cell are treated as "secret rooms". So there are many different types but they all work the same.

''Note: Bigger secret rooms have a much lower chance of generating because of the limited space around the rooms. Keep rooms at a maximum of 2x2 or 2x1. If you want bigger secret rooms check further below.''


 * Create a room and set the room type to secret.
 * Set at least one tile as is Door and select the door type. For example, if your room does not have extremely rare stuff, you can select barricades.
 * The room will be connected to the other room/corridor at the southern side (check the red arrow in the room view it points north), so keep that in mind when designing the room.

Increasing Secret Room size
If you want to create a bigger secret room, create it but don't set the room type to "secret". Keep it at "default" and reduce the probability.


 * ONLY have one door to the room and set this door type to something you want. Having only one door ensures that it is not possible for the generator to generate a path through the secret room, making it mandatory to cross. If the player can't access the secret room, he would get softlocked during his run. Having only one entrance avoids that because the generator has to work around the restriction.

Creating a Tile
To get started, open the ADVRModder.exe and select: New Tile


 * There is a small hint window that shows you the basic controls in the top left
 * Snap Value: Snaps the building blocks in certain intervals, e.g 1/4 snaps every 25cm
 * Environment Light: Can be toggled on or off to give you a bit more light to work with
 * Open / Save: Open .tile files and save .tile file
 * Tile Name: How do you want to name the tile?
 * Regenerate: Regenerates the tile (not really useful at the moment)

For this tutorial, we are going to create a tile that has an item podest and a few crates. To do so, check the building blocks tab on the right and click on ITEMS --> ITEM_PODEST. You can then move your mouse over the ground tile in your view and place it down in the middle of it.

Now, we are going to add a few crates next to the podest. In order to do so, select: PROPS --> PROP_CRATE and place them next to the podest.

Once you're finished, you should end up with something like the image in the thumbnail. Now let's give our tile a name in the Tile Name panel on the right. After that, click Save and save it to Ancient dungeon VR Beta_Data/gamedata/overgrown_dungeon/tiles/

It should now show up in the room creator.

Now that we have a new tile, we can put into a room.