Awesome

Introduction

This project is a Unity plugin for procedural generation of 2D dungeons (and platformers) and aims to give game designers a complete control over generated levels. It combines graph-based approach to procedural generation with handmade room templates to generate levels with a feeling of consistency. Under the hood, the plugin uses Edgar for .NET.

Graph-based approach

You decide exactly how many rooms you want in a level and how they should be connected, and the generator produces levels that follow exactly that structure. Do you want a boss room at the end of each level? Or da shop room halfway through the level? Everything is possible with a graph-based approach.

Handmade room templates

The appearance of individual rooms is controlled with so-called room templates. These are pre-authored building blocks from which the algorithm chooses when generating a level. They are created with Unity tilemaps, but they can also contain additional game objects such as lights, enemies or chests with loot. You can also assign different room templates to different types of rooms. For example, a spawn room should probably look different than a boss room.

Key features

• Procedural dungeon generator
• Describe the structure of levels with a graph of rooms and connections
• Control the appearance of rooms with handmade room templates
• Connect rooms either directly with doors or with short corridors
• Easy to customize with custom post-processing logic
• Supports Unity 2018.4 and newer
• Currently works only in 2D but may support 3D in future
• Comprehensive documentation
• Multiple example scenes included

PRO version

There are two versions of this asset - free version and PRO version. The free version contains the core functions of the generator and should be fine for simple procedural dungeons. The PRO version can be bought on the Unity Asset Store and contains some additional features. As of now, the PRO version contains features like platformer generator or isometric levels and also two advanced example scenes. If you like this asset, please consider buying the PRO version to support the development.

• Coroutines - Call the generator as a coroutine so that the game does not freeze when generating a level (docs)
• Custom rooms - It is possible to add additional fields to rooms and connections in a level graph (docs)
• Platformers - Generator that is able to produce platformer levels (docs, example)
• Isometric - Simple example of isometric levels (example)
• Dead Cells - Tutorial on how to generate levels that are similar to Dead Cells (docs)
• Enter the Gungeon - Tutorial on how to generate levels that are similar to Enter the Gungeon (docs)
• Custom input - Modify a level graph before it is used in the generator (e.g. add a random secret room) (docs)
• Fog of War - Hide rooms in a fog until they are explored by the player (docs)
• Minimap support (docs)
• Door sockets - Use door sockets to specify which doors are compatible (docs)
• Directed level graphs - Use directed level graphs together with entrance-only and exit-only doors to have better control over generated levels (docs)

Limitations

• Still in alpha version - there may be some breaking changes in the API
• Some level graphs may be too hard for the generator - see the guidelines
• The graph-based approach is not suitable for large levels - we recommend less than 30 rooms
• Not everything can be configured via editor - some programming knowledge is needed for more advanced setups

Getting started

Install the asset (instructions are below) and head to the documentation. The documentation describes all the basics and also multiple example scenes that should help you get started.

Installation

There are several ways of installing the plugin:

via .unitypackage

Go to Releases and download the unitypackage that's included in every release. Then import the package to Unity project (Assets -> Import package -> Custom package).

How to update

In order to be able to download a new version of the plugin, we recommend to not change anything inside the Assets/ProceduralLevelGenerator folder. At this stage of the project, files are often moved, renamed or deleted, and Unity does not handle that very well.

The safest way to update to the new version is to completely remove the old version (Assets/ProceduralLevelGenerator directory) and then import the new version. (Make sure to backup your project before deleting anything.)

via Package Manager

Add the following line to the packages/manifest.json file under the dependencies section (you must have git installed):

 "com.ondrejnepozitek.edgar.unity": "https://github.com/OndrejNepozitek/Edgar-Unity.git#upm"

To try the examples, go to the Package Manager, find this plugin in the list of installed assets and import examples.

Note: When importing the package, I've got some weird "DirectoryNotFoundException: Could not find a part of the path" errors even though all the files are there. If that happens to you, just ignore that.

How to update

After installing the package, Unity adds something like this to your manifest.json:

  "lock": {
    "com.ondrejnepozitek.edgar.unity": {
      "hash": "fc2e2ea5a50ec4d1d23806e30b87d13cf74af04e",
      "revision": "upm"
    }
  }

Remove it to let Unity download a new version of the plugin.

Do not clone the repository

When installing the plugin, use the two methods described above. If you clone the repository directly, you will probably get an error related to some tests and missing types/namespaces. This error is caused by the fact that the plugin is developed with Unity 2018.4 (for better compatibility), but the assembly definition format was changed in newer versions (a reference to the Edgar .NET assembly is missing).

Workflow

1. Draw rooms and corridors

2. Prepare the structure of the level

3. Generate levels

Examples

Get in touch

If you have any questions or want to show off what you created with Edgar, come chat with us in our discord server. Or if you want to contact me personally, use my email ondra-at-nepozitek.cz or send me a message on Twitter at @OndrejNepozitek.

Terms of use

The plugin can be used in both commercial and non-commercial projects, but cannot be redistributed or resold. If you want to include this plugin in your own asset, please contact me, and we will figure that out.