Generator - hpf3/dungeon-generator-release GitHub Wiki

Generator Controls
Generator Status

Overview

The Generator is the primary function of the program. It uses the currently selected pack to generate a dungeon layout, which you can then save as an image or store as a layout file for future re-use.

Controls

All of the generator’s settings appear on the left side of the screen. You can modify most of these at any time—changes take effect immediately, even if generation is in progress. Below is an overview of each control:

1. Save/Load Layout

  • Save Layout
    • Saves the exact arrangement (which cards were placed and how they’re connected) to a layout file.
  • Load Layout
    • Loads a previously saved layout, restoring the placement of cards and their connections.

Note: Layout files reference connection index positions in each card’s connection list—not the actual side/offset values. If you edit a card’s connections in the Asset Editor, older layouts may no longer line up properly.

2. Save Image

  • Opens a save dialog where you can choose the image format (e.g., WebP, PNG, JPG) and pick a location to store the final dungeon map.
  • Different formats may have different capabilities (e.g., transparency, compression settings).
  • Keep in mind there is a maximum size limit for images in Godot.

3. Image Quality

  • Adjusts the compression quality only at the time of saving the image (for formats that support it).
  • It does not affect how the map looks on-screen in the “Image Render” view.

4. Card Size

  • A slider that effectively changes the resolution of the final output by scaling the entire dungeon.
  • Because it alters positions of cards, it’s ignored while the generator is placing them. You can adjust it any time, but the effect is only visible when the generator isn’t actively adding cards.

5. Pixel Collision Detection

  • Adds an extra step to check for overlapping non-transparent pixels when placing a new card, preventing collisions where the images visually overlap.
  • This can slow down generation because it requires GPU-based checks.

6. Goal Uses Farthest

  • If enabled, the Generator tries to place the “end” (or “goal”) card at the location farthest from the start card.
  • Otherwise, it picks a valid ending point randomly.

7. Expand From Farthest

  • If the Generator runs out of open connections before reaching the minimum card count, it decides which connection to expand from next.
  • Enabling this tries to pick the connection farthest from the start.

8. Allow Looping

  • Lets the Generator form loops (i.e., cards connecting back to existing cards).
  • This adds another collision check step, so it may slow down generation a bit.

cards that are perfect squares with centered connections are vastly more likely to form loops since it means they are more likely to actually align with an existing card

9. Dynamic Card Weight

  • Dynamically adjusts card selection weights based on factors like:
    • Distance from the “average center” of the dungeon
    • How many cards have been placed vs. desired total
    • The type of the parent/last card (corridor, T-junction, cross, etc.)

10. Limit TPS

  • The Generator places cards in “cycles.” If Limit TPS is off, the program tries to skip extra steps (like rendering) for faster placement, measured in “TPS” (placements per second).
  • It still does a “normal” cycle about once per second to avoid total lock-up.

11. Min Maze Size

  • The minimum number of cards you want in your dungeon.
  • The Generator continues placing cards until there are no more valid connections, which can exceed this minimum.

12. Expansion Attempt Limit

  • The maximum number of times the Generator tries to expand the dungeon before giving up on meeting the minimum card count.
  • Long dungeons may have many dead-ends that produce no further expansions.
  • You can disable this limit (making it infinite) via the toggle next to the numeric input.

13. Show Sizing Aid

  • Displays two reference squares:
    • A blue grid (70px cells by default) intended for VTTs like Roll20.
    • A red outline representing Godot’s maximum image size limit.
  • This is useful for estimating whether your final image is getting too large.

14. Show Image Render

  • Toggles the live “in-engine” render of your dungeon.
  • Helpful for previewing how small you can make the Card Size before the image becomes too blurry or low-quality.
  • If the dungeon exceeds the max size, this option is disabled.

15. Other Buttons

  • Back
    • Returns you to the pack selection (Asset Manager), resetting the Generator’s progress.
  • Halt Generation
    • Stops card placement immediately, leaving any open connections as-is.
  • Reset
    • Clears the current dungeon and restarts generation from the beginning.
  • Spacebar (keyboard key)
    • Re-centers the camera on the root card (useful for if you get "lost").

Info Display

On the right side, you’ll see a panel showing generator status:

  • Cards Placed / Minimum Card Count
  • Open Connections (connections that don’t yet have a card)
  • Tries / Max Tries
  • Time (since generation started)
  • TPS (card placement attempts per second)
  • FPS (frame rate)
  • Done/Not Done (whether the Generator is still running)

The Generator Cycle

The Generator proceeds in iterative “cycles,” as follows:

  1. Choose Card
    • Pick a random card that has at least one open connection.
    • If no cards are found, proceed to finalization (below) and end the cycle.
  2. Pick Side (Existing Card)
    • Randomly pick one of that card’s open sides.
  3. Pick New Card
    • Choose a card from the General List, excluding any already tried on this side.
  4. Pick Side (New Card)
    • Randomly pick one of the new card’s connections.
  5. Position New Card
    • Align the newly selected connection with the open side of the existing card.
  6. Check Overlap
    • Identify other cards whose bounding box overlaps with this placement.
  7. Collision Detection
    • a. Loop Check: If Allow Loops is on, see if this would form a valid loop.
    • b. Pixel Check: If Pixel Collision Detection is on, run an extra transparency-based overlap check.
    • c. Fail & Remove: If a collision is still detected, remove the new card, mark it as tried, and skip it this round.
  8. Retry If TPS Not Limited
    • If the new card was removed and Limit TPS is off, and less than one second has passed since the last frame, go back to step 3.
  9. Next Card
    • If Limit TPS is off and less than a second has passed, go back to step 1.
  10. Update UI
  • Once per “normal” cycle, update the UI and render a frame.

Finalization

When the Generator has no open connections left (i.e., step 1 finds no valid card):

  1. Check whether the Min Maze Size is satisfied.
    • If not, and if you still have tries left, pick a dead-end according to Expand From Farthest, remove it, increment the tries counter, and return to doing cycles.
  2. If the maze is large enough (or expansion fails/ends), pick a dead-end based on Goal Uses Farthest and attempt to place an End card there.
    • If collision checks fail for that dead-end, restore it and move on to the next.
    • Continue until a goal is placed or no dead-ends remain.
  3. If no goal can be placed, the Generator finishes without placing an End card.

Once finalization is complete, your dungeon is fully generated. You can then Save Image, Save Layout, or tweak settings to generate again.

That’s it for the Generator! Once your dungeon is complete, feel free to save it as an image, or store its layout for later editing. If you need to tweak card connections or weights, head back to the Asset Editor.