Karcero

Random dungeon tile based map generator

Karcero is a 2d map generator library written in C# and can be used anywhere. It has a fluent API which lets you write generation code quickly and a more detailed API to let you tweak the parameters to get a map to your liking. It also supports constructing a 2d map out of your own cell classes by implementing the ab interface and calling the generator class with your implementation.

Quick Start

Here is an example for a generation call using the fluent API and receiving the result asynchronously:

            var generator = new DungeonGenerator<Cell>();
generator.GenerateA()
         .MediumDungeon()
         .ABitRandom()
         .SomewhatSparse()
         .WithMediumChanceToRemoveDeadEnds()
         .WithMediumSizeRooms()
         .WithLargeNumberOfRooms()
         .AndTellMeWhenItsDone(map =>
         {
            //Do stuff with map
         });
            
And an example for a map generated from that call:

Using a Custom Tile Class

The DungeonGenerator class is a generic class that builds a map of any type that implements the interface ICell. You can use the basic Cell implementation supplied with Karcero, inherit the Cell class or implement the ICell interface yourself.
The ICell interface contains three basic properties, all of which will be filled during the map creation process:

  • Row(Int): specifies the cell\s row in the map matrix.
  • Column(Int): specifies the cell's column in the map matrix.
  • Terrain(TerrainType): specifies the cell's terrain type.

Extending the Generation Process

The map is generated by creating a matrix of cells with TerrainType.Wall as their terrain, then running a series of map processors on it. If you would like to extend the map generation you can implement the IMapProcessor interface which contains a single ProcessMap method and adding it to the DungeonGenerator.
For example, let's say we want to place treasure as part of the map generation. Here's an implementation of a treasure placing processor:

            public class PlaceTreasureProcessor<T> :
            IMapProcessor<T> where T : class, ICell, new()
{
    public void ProcessMap(Map<T> map,
                           DungeonConfiguration configuration,
                           IRandomizer randomizer)
    {
        //Place treasure
    }
}
                
And now just add it before calling generate:
var generator = new DungeonGenerator<Cell>();
generator.AddMapProcessor(new PlaceTreasureProcessor<Cell>());
generator.Generate(configuration);
                

Controllable Parameters

There are many parameters that influence the map generation process. Following is a brief description of each one:

Parameter Description Type Range
Height/Width The map's size Int Larger than 0
Randomness Controls how many twists and turns the dungeon contains Double 0-1
Sparseness Controls how sparse the map is Double 0-1
Chance to remove dead-ends Controls how many dead ends will be left in the map Double 0-1
Room width (min/max) Room width size Int Larger than 0
Room height (min/max) Room height size Int Larger than 0
RoomCount Controls how many rooms should be generated Int 0 or larger

Installation

There are several ways to use Karcero:

  • Nuget package:
    PM> Install-Package Karcero
  • Download the code and add the Karcero.Engine project to your solution: TAR / ZIP
  • Download the assembly and add a reference to it: Assembly
Karcero has no external dependencies.

Issues & Collaboration

If you encounter any issues please post them to repository. If you would like to contribute or collaborate contact me here.

Benchmark

  • Results are in milliseconds.
  • Each configuration in the following tables was used to generate 10 maps, and the average value is stated.
  • Not all configurations are possible. When there is no room to add the number of rooms requested the value is '-'.
  • The map sizes used are:
    • Huge - 100 x 100
    • Large - 45 x 45
    • Medium - 33 x 33
  • The room sizes used are:
    • Large - (5-8 x 5-8)
    • Medium -(3-6 x 3-6)
    • Small - (2-3 x 2-3)
  • The maps were generated with the following values:
    • Randomness - 0.6
    • Sparseness - 0.6
    • Chance to remove dead ends - 0.5
  • The benchmark was run on an i7-3770 CPU @ 3.40GHz (8CPUs) with 16GB ram.
Huge Map 10 Rooms 15 Rooms 20 Rooms 25 Rooms 30 Rooms 35 Rooms 40 Rooms
Small Rooms 112 133 121 131 127 145 148
Medium Rooms 109 112 119 129 142 144 148
Large Rooms 118 127 114 123 142 141 149
Large Map 10 Rooms 15 Rooms 20 Rooms 25 Rooms 30 Rooms 35 Rooms 40 Rooms
Small Rooms 14 15 17 18 19 20 22
Medium Rooms 14 16 20 22 29 35 -
Large Rooms 16 19 - - - - -
Medium Map 10 Rooms 15 Rooms 20 Rooms 25 Rooms 30 Rooms 35 Rooms 40 Rooms
Small Rooms 7 8 8 10 11 12 16
Medium Rooms 8 11 - - - - -
Large Rooms - - - - - - -