Godot DTL (Dungeon Template Library)

Godot DTL is a GDExtension for Godot 4.x that wraps the C++ DTL (Dungeon Template Library). It provides a convenient interface to generate various types of 2D map data (islands, mazes, roguelike dungeons, and more) in Godot.

Table of Contents

• Godot DTL (Dungeon Template Library)
  • Table of Contents
  • Installation
    • 1. Install from the Godot Addons Browser
    • 1. Manual Installation
  • Usage
    • GDScript Example
  • DTL Class Reference
    • Description
  • Methods
    • CellularAutomatonIsland
    • CellularAutomatonMixIsland
    • ClusteringMaze
    • DiamondSquareAverageCornerIsland
    • DiamondSquareAverageIsland
    • FractalIsland
    • FractalLoopIsland
    • MazeBar
    • MazeDig
    • PerlinIsland
    • PerlinLoopIsland
    • PerlinSolitaryIsland
    • RogueLike
    • SimpleRogueLike
    • SimpleVoronoiIsland
  • Contributing
  • License

Installation

There are two ways to install Godot DTL:

1. Install from the Godot Addons Browser

OR

1. Manual Installation

1. Clone or download this repository.
2. Open the project in Godot.
3. You’re good to go!

Usage

GDScript Example

# Suppose you have a script attached to a node where you want to generate a map:

extends Node

func _ready() -> void:
    var dtl = DTL.new()
    
    # Generate a simple roguelike dungeon
    var dungeon_array = dtl.SimpleRogueLike(
        width = 64,
        height = 64,
        division_min = 3,
        division_max = 4,
        room_min_x = 5,
        room_max_x = 6,
        room_min_y = 7,
        room_max_y = 8
    )
    
    # Now do something with 'dungeon_array'.
    # For example, you can iterate over it and create tiles:
    # (The exact usage depends on your project’s tilemap setup.)
    #
    # var map_size = Vector2(64, 64)
    # var tilemap = $TileMap
    # for y in range(map_size.y):
    #     for x in range(map_size.x):
    #         var cell_value = dungeon_array[y * map_size.x + x]
    #         tilemap.set_cell(0, Vector2(x, y), cell_value)

DTL Class Reference

Description

The DTL class serves as a wrapper to the Dungeon Template Library (DTL), allowing you to generate various procedural 2D maps. The generated arrays are typically 1D arrays with dimensions [width * height] that you can map to tiles, terrain, or other game elements.

Methods

CellularAutomatonIsland(width: int, height: int, iterations: int = 5, probability: float = 0.4)

Generates an “island” by starting with random noise (based on probability) and applying a cellular automaton smoothing over several iterations. Useful for organic landmass shapes.

CellularAutomatonMixIsland(width: int, height: int, iterations: int = 5, land_values: int = 5)

Similar to CellularAutomatonIsland, but it incorporates multiple “land values” (cells) instead of a simple binary map. Creates a blend of different terrain zones.

ClusteringMaze(width: int, height: int)

Generates a maze-like structure by clustering cells. This can be used to create cave-like or labyrinthine environments.

DiamondSquareAverageCornerIsland(width: int, height: int, min_value: int = 20, altitude: int = 80, add_altitude: int = 60)

Uses a variation of the Diamond-Square algorithm that averages corner values first. Produces height-map style islands where higher values often form the center regions.

• min_value: The lowest possible height value.
• altitude: The mid-range height level.
• add_altitude: The maximum offset added during the diamond-square steps.

DiamondSquareAverageIsland(width: int, height: int, min_value: int = 0, altitude: int = 80, add_altitude: int = 60)

A Diamond-Square island generator without the corner averaging step. It can create more varied or rough edges compared to the corner-averaging variant.

FractalIsland(width: int, height: int, min_value: int = 10, altitude: int = 150, add_altitude: int = 75)

Generates an island using fractal noise-based operations. Useful when you want more chaotic coastline and terrain features.

FractalLoopIsland(width: int, height: int, min_value: int = 10, altitude: int = 150, add_altitude: int = 70)

Similar to FractalIsland but attempts a “loop” approach that can result in more continuous or wrapped edges, depending on how you use the data.

MazeBar(width: int, height: int)

Creates a maze by generating “bar-like” corridors. Often results in straight or rectangular corridors for a grid-based, blocky feel.

MazeDig(width: int, height: int)

A maze generator that “digs” through solid space, leaving a path behind. Results in winding tunnels similar to a mining or digging operation.

PerlinIsland(width: int, height: int, frequency: float = 10.0, octaves: int = 6, max_height: int = 200, min_height: int = 200)

Generates an island height-map using Perlin noise. Adjusting frequency and octaves will change the map’s “roughness,” and max_height / min_height determine altitude ranges.

PerlinLoopIsland(width: int, height: int, frequency: float = 10.0, octaves: int = 6, max_height: int = 200, min_height: int = 200)

Similar to PerlinIsland, but wraps the edges in both x and y directions, creating a “looped” or “toroidal” effect. Great if you need seamless transitions at map edges.

PerlinSolitaryIsland(width: int, height: int, truncated_proportion_: float = 0.5, mountain_proportion_: float = 0.45, frequency: float = 6.0, octaves: int = 6, max_height: int = 200, min_height: int = 200)

Generates a solitary island shape by combining Perlin noise and threshold values (truncated_proportion_ and mountain_proportion_) to emphasize island coastlines and mountainous interiors.

RogueLike(width: int, height: int, max_ways: int = 20, min_room_width: int = 3, max_room_width: int = 3, min_room_height: int = 4, max_room_height: int = 4, min_way_horizontal: int = 3, max_way_horizontal: int = 4, min_way_vertical: int = 3, max_way_vertical: int = 4)

Generates a traditional “roguelike” dungeon layout with rooms connected by corridors. Various parameters allow you to tweak room sizes, corridor lengths, and the total number of passages.

SimpleRogueLike(width: int, height: int, division_min: int = 3, division_max: int = 4, room_min_x: int = 5, room_max_x: int = 6, room_min_y: int = 7, room_max_y: int = 8)

A simpler roguelike generator using fewer parameters. It automatically divides the map into regions and places rooms with random dimensions within those divisions.

SimpleVoronoiIsland(width: int, height: int, voronoi_num: float = 40.0, probability: float = 0.5)

Generates an island-like shape using Voronoi diagrams. voronoi_num controls how many sites are used, and probability influences random fill patterns.

Contributing

Pull requests are welcome! If you have suggestions for new features, performance improvements, or bug fixes, feel free to open an issue or submit a PR. Also, if you’d like to enhance the method descriptions or provide more examples, contributions are gladly accepted.

License

This project is licensed under the MIT License.
See LICENSE for details.

Happy map-making with Godot DTL!