DunGen  1.1
Dungeongenerator library for Irrlicht
DunGen 1.1 API documentation

Introduction

Welcome to the DunGen API documentation. Here you'll find any information you'll need to develop applications with the DunGen library.
You can get the newest versions of DunGen at dungen.squarefox.net.

DunGen allows you to procedurally generate dungeons for your Irrlicht application.

A dungeon is created in several steps:

  1. create a L-system
  2. create a voxel cave from it
  3. erode the voxel cave, if wished
  4. place rooms
  5. create corridors
  6. filter the voxel cave, if wished
  7. create a mesh cave from the voxel cave
  8. assemble the dungeon and add it to your scene

L-Systems

A L-system (Lindenmayer system) is a grammar based mechanism, to describe fractal structures. It was originally developed by Lindenmayer to generate plants, but many L-systems drawn with a radius are suitable for some nice caves.

A L-system generates turtle graphics drawing instructions and has some parameters.
In DunGen these parameters are: angleYaw, anglePitch, angleRoll, radiusStart, radiusFactor, radiusDecrementor.
There are several instructions, which the turtle can perform. In DunGen, these are:

'F' - draw forward
'!' - decrease drawing radius, the formula is: newRadius = radiusFactor * oldRadius - radiusDecrement
'[' - push actual position, direction and radius on stack
']' - pop position, direction and radius from stack
'+' - rotate around the Up axis by angleYaw
'-' - rotate around the Up axis by -angleYaw
'u' - rotate around the Left axis by anglePitch
'o' - rotate around the Left axis by -anglePitch
'z' - rotate around the Front axis by angleRoll
'g' - rotate around the Front axis by -angleRoll
'|' - rotate around the Up axis by 180 degrees
'$' - orient turtle in the XZ-plane

Generating Caves

Caves are first created as voxel caves from L-systems. The L-system is adapted in size, so it fits exactly the voxelspace. The drawing radius of the L-system remains unchanged. The voxel cave can be eroded an arbitrary amount of times. Eroding removes random cave surface voxels with a specified likelihood (maybe you'll reach the border of the voxelspace on some parts of the cave - there nothing is eroded anymore). Sometimes some voxels in the cave are floating around (e.g. through erosion, or the nature of the L-system). You can remove them by filtering the cave.

Roompatterns

You can provide your own room patterns for DunGen. These patterns have to be .irr (Irrlicht scene) files and can be used as templates for rooms in the dungeon.

Each pattern has to fulfil some requirements, for being suitable:
If corridors shall be to connectable to the rooms, they have to have docking sites. Each docking site is a 2-dimensional mesh, with exact one boundary curve. Docking site mesh nodes in the .irr-file have to be named "dockingsite_xxx", where xxx is a increasing number, beginning with 000, 001, ... . You can have up to 1000 docking sites for each roompattern.

Docking Corridors

Corridors can be connected to rooms and the cave. If you connect them to rooms, you specify the room and docking site to connect to. If you connect them to caves, you specify a vector of minVoxels and maxVoxels. Those voxels define, in which region the cave is connected. The connection is done after a search for a possible cave section. There are 4 different search directions: X-positive, X-negative, Z-positive, Z-negative. Assume you search in positive X-direction. Then minVox would specify the start of the search. The Y and Z coordinates of minVoxels and maxVoxels specify the profile (a rectangle) of the created cave docking site (the docking site for the cave is created automatically). The difference between the X coordinates is additionally carved into the cave.

Detailobjects

It's possible to place detailobjects (e.g. torches) within corridors. They can be placed in random distances, if wished. Please refer to SDetailobjectParameters for possible options.