Introduction to the Dungeon Graph Generator sample

About the sample

The Dungeon Graph Generator sample showcases how to use Unity Graph Toolkit’s API for procedurally generating a graph for a dungeon level in a simple roguelike dungeon crawler.

This sample is a simple tool that takes a set of specifications for creating a dungeon, then randomly creates a DungeonGraph asset from these specifications. The DungeonGraph asset is an editor-only asset and is not usable at runtime. For an example of how to convert a graph into a custom runtime object, check out the Visual Novel Director sample.

There are many ways you could use this tool. For example:

As a level designer to quickly generate dungeon variants and then fine tune them directly using the Dungeon Graph tool.
As a programmer to visualize the kinds of graphs that get produced by your procedural generation algorithm and have a better understanding of how to adjust your algorithm.
As a game designer to visualize how dungeon parameters impact your generated dungeons and help you choose which parameters your game should use and what should be their corresponding values.

Note

This sample is intended as a learning resource and is not designed to function as a fully-featured roguelike dungeon crawler game. Certain architectural decisions were made to keep the sample simple and focused on demonstrating key concepts.

About the Dungeon Graph Generator tool

The Dungeon Graph Generator has two main functionalities:

A dungeon graph tool for creating and editing graph assets meant to represent the structure and level design of a dungeon.
A dungeon graph asset generator (you can use it by clicking on the Generate button on a Dungeon Graph Generation Sheet).

A dungeon graph has six instantiable types of custom nodes:

Start node (StartNode) - Represents the first room of the dungeon.
Encounter context node (EncounterNode) - Represents a room in which an enemy encounter takes place. Contains block nodes that each represent an enemy character. Also takes as input an event that will take place after the encounter.
Enemy block nodes (EnemyBlockNode) - Contains a reference to an enemy prefab asset.
Reward node (RewardNode) - Represents an event where the player receives a reward.
Merchant node (MerchantNode) - Represents an event where the player may purchase wares from a merchant.
End node (EndNode) - Represents the last room of the dungeon.

The expected structure of the graph is that it always begins on a start node and finishes on an end node such that any path taken from the start node must eventually lead to the end node. There should only be one start node and one end node per dungeon graph. All in between nodes on the path from the start to the end nodes are encounter context nodes. Encounters are expected to be organised in depths. The start node connects to every encounter on the first depth. Then each encounter on the first depth must connect to at least one encounter on the second depth. Every node on the second depth must be connected to at least one node on the first depth and must connect to at least one node in the next depth. This pattern is repeated until the end node is reached. Every encounter node in the last depth must connect to the end node.

An encounter should have at least one enemy and is expected to have an event. Although there is no runtime implementation for it, the intended game design is that defeating all the enemies in an encounter triggers its respective event.

The generator always creates graphs that follow the structure described above. However, it also adds variability each time you generate a graph by randomizing values you set in the Dungeon Graph Generation Sheet. A generation sheet contains the following fields:

Start Room: A GameObject that loads the first room of the dungeon.
End Room: A GameObject that loads the last room of the dungeon.
Enemy Types: A list of GameObjects that correspond to enemies that can be encountered in the dungeon.
Reward Types: A list of GameObjects that correspond to rewards that can be obtained after successfully completing an encounter in the dungeon.
Merchant Wares: A list of GameObjects that correspond to items that the player may purchase from a merchant.
Depth: The number of room depths between the start room and the end room. For example, a depth of one means the generated graph will have one start room that connects to a number of encounters, and all those encounters will connect to the end room. Must have a value greater than zero.
Max Rooms Per Depth: The maximum number of encounter rooms in a depth. Must have a value greater than zero.
Max Enemies Per Encounter: The maximum number of enemies per encounter. Must have a value greater than zero.
Merchant Chance Rate: The probability that an event will be a merchant room. Must have a value between 0.0f and 1.0f inclusively.
Dungeon Graph Name: The name of the generated dungeon graph asset.

Each encounter is individually randomized. The number of enemies within an encounter is chosen randomly between 1 and Max Enemies Per Encounter inclusively. The type of each enemy is picked at random from the list of Enemy Types. The number of rooms of each depth is independently randomly selected with a value between 1 and Max Rooms Per Depth inclusively. The generator ensures that all rooms of each depth connect to at least one room of the previous depth and to at least one room of the following depth. The event type of each encounter is picked according to the Merchant Chance Rate; if an event is not a merchant room, then it is a reward room. The generator always attributes an event to an encounter room, however this is not an enforced rule and a manually edited graph may have encounter rooms with no attached event.

The sample includes the example Dungeon Graph Generation Sheet Assets/Graph Toolkit/<installed package version>/Dungeon Graph Generator Sample/Scriptable Objects/CryptGenerationSheet. GameObject fields in the sheet are filled with empty dummy prefabs found in the Dummy Prefabs folder. These prefabs allow to demonstrate the randomization of values done by the generator, but are otherwise unusable as they are outside the context of this sample.

In the case of enemy prefabs and reward prefabs, the generator does not directly inject these prefabs in the graph. It instead creates blackboard variables that hold references to these prefabs. This offers the benefits of manipulating a reference instead of a value when you manually edit a generated graph. For example, if you wish to modify which prefab an Enemy Type points to, you can simply update the reference held by the according blackboard variable instead of individually editing each prefab value in your graph.