Core Concepts: Doorways

What is a Doorway?

Doorways are the fundamental mechanism DunGen uses to connect your Tiles together. They act as designated attachment points on your Tile prefabs. When generating a dungeon, DunGen attempts to align Doorways from adjacent Tiles to form connections and build the layout.

You define potential connection points by adding Doorway components to your Tile prefabs, as initially covered in the Getting Started guide.

Creating a Doorway

Inside your Tile prefab, create an empty GameObject where you want a potential connection to form.
Add the Doorway component (Add Component > DunGen > Doorway) to this empty GameObject.
Position this empty GameObject precisely (see Placement Rules below).
Ensure this Doorway GameObject is a child of your main Tile prefab's root object.

Placement Rules

Correct Doorway placement is crucial for DunGen to function properly.

Edge of Bounds: The Doorway's position must lie on the edge of the Tile's calculated Axis-Aligned Bounding Box (AABB). If a doorway lies inside the bounds, the bounding box will be shrunk to match its position (potentially causing some geometry to protrude outside the bounding box).

Concave Shapes

Doorways cannot be placed on concave sections of a Tile's boundary. They must be accessible from outside the Tile's AABB. See the Limitations page for more details.

Orientation (Z-Axis): The Doorway GameObject's local forward (Z) axis (the blue arrow in the Scene view gizmo) must point directly outwards, away from the Tile's interior. This defines the connection direction.
Orientation (Y-Axis): By default, the doorway's up axis will point towards positive Y. This is the usual up-vector for 3D scenes, but if you're working in 2D, ensure the Doorway's orientation matches your project's "up" direction so connections form correctly in the 2D plane.

The Doorway Component

The Doorway component holds all the information DunGen needs about this specific connection point:

Socket: This is perhaps the most important setting for controlling connections. It assigns a Doorway Socket asset to this doorway. See the dedicated Doorway Sockets section below for details.
Hide Conditional Objects?: If checked, connector and blocker scene objects will be hidden to reduce clutter in-editor. This setting has no effect at runtime

Connectors & Blockers

These sections control what appears at the Doorway's location depending on whether it gets used in the final layout:

Connectors: Objects placed here are enabled or spawned when this Doorway successfully connects to another Doorway on an adjacent Tile.
- Use Case: Door frames, open doorways, dynamic Door objects, visual connection flourishes.
- Priority: If both connecting doorways try to spawn a Connector prefab, the one with the higher priority value wins and its prefab is spawned. If priorities are equal, one is chosen randomly.
Blockers: Objects placed here are enabled or spawned when this Doorway remains unused (is not connected to another Tile).
- Use Case: Walls, closed doors, rubble piles, bookcases - anything to block the unused opening.

Both Connectors and Blockers share these configuration options:

Random Prefab: A list where you can assign prefabs to be potentially spawned at the Doorway's position and orientation. The prefab instance will be attached to the Doorway GameObject.
- Weights: Each prefab has a Weight controlling its relative chance of being chosen if multiple prefabs are listed. Only one prefab is chosen per connected doorway pair.
- Avoid Rotation?: If checked, the spawned prefab will retain its own prefab rotation instead of inheriting the Doorway's rotation. Useful for props that shouldn't rotate with the doorway.
Note

For Connectors, one prefab per connected doorway pair will be spawned. For Blockers, one prefab per Doorway component will be spawned.
Scene Objects: A list of GameObjects already present within the Tile prefab itself (as children somewhere) that should be enabled/disabled based on the Doorway's connection state.
- Unlike prefabs, all GameObjects listed here are affected (enabled if the condition is met, disabled otherwise).

Ensuring Correct Placement of Doorway Prefabs

If you're using Connector or Blocker Prefabs (as opposed to Scene Objects), getting the position and rotation right is critical. Since the instantiated prefab will be parented to the Doorway GameObject, it will inherit its position and rotation.

While there are options for Position Offset and Rotation Offset, it's better to just create the prefab with the appropriate offsets built-in. Here's a solid process for doing this:

Find an existing Doorway in one of your Tiles.
Create a new GameObject and name it appropriately (e.g., "Standard Doorway Blocker").
Parent the empty GameObject to your Doorway and reset its transform (in the inspector, right-click on Transform and choose Reset).
Add the geometry you want to the new GameObject. Move and rotate only the child objects, not the root GameObject. This will ensure that all the geometry will be in the correct place when the prefab is instantiated later.
When done, drag the root GameObject into the project view to turn it into a prefab. We don't need it in the scene hierarchy any more so feel free to delete it.
Assign the new prefab to one of the lists as described earlier.

Doorway Sockets

Purpose

Doorway Sockets are identifier assets used to filter potential connections. By default, DunGen will only connect two Doorways if they both share the exact same Socket asset.

This is essential for:

Different Sizes: Preventing a small doorway from connecting to a large one. Create separate Socket assets like "Small Archway Socket" and "Large Archway Socket" and assign them accordingly.
Different Styles: Ensuring a "Cave Mouth" doorway only connects to another "Cave Mouth", not a "Castle Door".
Special Connections: Defining unique sockets for specific connection types, like ladders or teleporters, that shouldn't connect to standard doorways.

Default Socket

DunGen includes a "Default" socket. If all your doorways are identical in size and type, you can simply use this default socket for all of them.

Creating Custom Sockets

If you need different types of connections:

Right-click in the Project view.
Navigate to Create > DunGen > Doorway Socket.
Give the new Socket asset a descriptive name.
Assign this new Socket asset to the Socket Group field on the relevant Doorway components in your Tile prefabs.

Overriding Matching Behaviour

While default behaviour requires sockets to match exactly, you can implement more complex logic using Code-Based Connection Rules.

Doorways, combined with Sockets and their Connector/Blocker configurations, are the core elements that allow DunGen to intelligently piece together your pre-designed Tiles into coherent and varied dungeon layouts.