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.

### Room Structure

#### 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

*`Note: VR Mode is still a bit clunky, as well as the Flat version so it can happen that some features are not working in one version or are not implemented yet.`*

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.

*`Hint: If you look at the red arrow in the room view, it shows a direction. This is only needed if you're creating rooms other than shop and default. It will be explained in advanced tutorials.`*

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.

*`Hint: Its important that your room has enough doors! Rooms should have multiple doors (preferably at least one on each side so N,W,S,E) so the generator can connect the corridors to the room without generating around everything. NOT all doors will have a corridor connected to them, they will just look like a closed wall instead. So please place more doors than you want to have entries.`*

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.

*`Hint: Sometimes other tiles are in the way when placing stuff. Press the Space key while placing to ignore the static layer and only place on the ground`*

#### 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.

`*Hint: Each enemy type that you choose has the same probability of spawning, that's why you should only select rare enemies like SLIME\_GOLDEN, WIGHT\_CHAMPION, GOLDEN\_POT, etc if you want them to always spawn at that position. Those enemies will naturally spawn with their correct probability if you select the standard enemies.*`

`*For example: SLIME\_ALL has an equal probability to spawn Bullet Slimes, Big Slimes and small Slimes. But it also has a 3% chance to spawn a golden slime. The same logic applies to WIGHT\_CHAMPION and all other rare monsters.*`

#### 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: `od_*yourname*_enemies_1`

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: `generator test_od YOUR_ROOM_NAME`

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 `#modding-creations` 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.

## Advanced Room Tutorials

### 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

`Please note: In order to keep the amount of different tiles that are in the room builder to a minimum, only tiles that are useful will be added to the official game. That means, if you build a room that uses a tile that is not officially in it, it may not be put in the game. If you only need something once for a room, don't create a tile, just build it in the room itself.`

`For this tutorial, it is not advised to build a tile, as rooms with custom tiles will only be supported if the custom tiles will also be put into the modder officially. IF YOU DO NOT INTEND TO BUILD A ROOM JUST FOR YOURSELF SKIP THIS PART`

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.