Easy Maze Builder Documentation
EASY MAZE BUILDER - DOCUMENTATION Version 2.0.0 | Unreal Engine 5.7 and 5.8 | Windows CelestiaDominance
PURPOSE Easy Maze Builder converts lines in an image into maze walls in the Unreal Editor. Use grid generation for block-shaped walls or path generation for traced centerlines. You supply the image, meshes and optional materials. The tool creates walls; it does not generate a maze puzzle, solve it, create a floor or add gameplay automatically.
CREATE YOUR FIRST MAZE 1. Open the editable level where you want the walls. 2. Open Tools > Easy Maze Builder, or its entry in the Window menu. 3. Browse to a maze image. A high-contrast PNG with dark walls on a light background is a good starting point. The file picker stores an absolute path. Existing relative paths are resolved against Unreal's process base directory, so use Browse if a moved project cannot find an image. 4. Select Grid-Based or Path-Based generation and the corresponding output mode. 5. Set the wall dimensions and placement. Leave the mesh selection empty to use the engine cube, or select your own wall mesh. 6. Click Generate. Image analysis runs in the background; actors and components are created in batches on the editor thread. The analysis stage may stay at its initial progress until the image has been processed. 7. Inspect the result and save the level. Add your own floor, lighting, navigation and gameplay as needed.
IMAGE INPUT PNG, JPG/JPEG, BMP and TGA are suitable standard image formats. The loader also accepts HDR/EXR where Unreal's image wrapper can convert them to 8-bit RGBA; PNG is preferable for predictable thresholding. Files are limited to 64 MB, 8192 pixels per side and 16,777,216 total pixels. These limits are checked before full image decoding. Transparent pixels are composited against white before wall detection. Dark Threshold selects pixels with brightness below the threshold; Invert Detection selects the opposite. Anti-aliased or compressed images may require threshold adjustment. Keep wall strokes and corridors clearly separated. The source image is an editor input file, not a required runtime texture. Moving it does not remove already saved geometry, but you must select its new location to generate again.
GRID-BASED GENERATION The image is sampled into a grid while retaining its aspect ratio. Target Grid Size controls the longest grid dimension. Each detected wall cell produces one mesh element. Grid Cell Size sets the cell spacing and base footprint. Wall Height sets the wall height. Mesh scale multipliers and rotation offsets customize the result. Grid size is controlled by Grid Cell Size, not the path Maze Scale or Wall Thickness settings.
Grid output choices: - Individual Static Meshes: one normal StaticMeshActor per occupied cell. Useful for selecting and editing walls separately. - Single Actor (Components): one MazeActor containing separate static mesh components. - Instanced Meshes (HISM): one MazeActor with hierarchical instances, grouped by mesh configuration. Useful for repeated geometry. This does not create a merged Static Mesh asset.
PATH-BASED GENERATION Centerline (Skeletonization) traces the wall strokes into paths. Closed loops, border lines and branches are preserved during tracing. Nearby parallel walls are not snapped together across corridors. Max Path Resolution limits the image resolution used for tracing; its default is 1024, with a supported range of 32-2048. Downscaling retains the intended overall path scale, but very thin features can disappear. Raise this limit or use a cleaner image if detail is lost. Path Detail Level controls simplification tolerance. Higher values preserve more image detail. It is not an exact output-segment count. Min Segment Length filters short segments after tracing; reduce it if small wall sections disappear. Maze Scale X/Y controls the spacing of image-derived path points, and Spawn Location places the result. Wall Height and Wall Thickness control the generated wall dimensions.
Path output choices: - Spline Meshes: one spline mesh component per segment. Custom meshes should run along their local X axis. Y/Z scale multipliers control thickness and height; Roll rotates the cross-section. The path supplies length and direction, so X scale and Pitch/Yaw offsets do not reposition spline endpoints. - Procedural Mesh (Single Component): straight box-shaped wall sections stored in one procedural component. The first mesh configuration's material override is used; selected mesh assets and their transforms are not used to construct this geometry. Sections are not welded into a seamless solid at junctions.
Smooth Curves and Smoothing Factor are available through the generation config and project defaults for spline interpolation. Smoothing is off by default to preserve the traced shape. Curved interpolation can change clearance in narrow corridors; inspect the generated result. Procedural walls remain straight sections. Legacy detection enum values remain readable for compatibility, but they use the same centerline extraction. The old overlap-merging setting is retained for compatibility and no longer joins nearby walls.
CUSTOM MESHES AND MATERIALS Add mesh configurations to supply alternatives. Positive Selection Weight values in the generation config or project mesh defaults control relative selection frequency. Random Seed makes selection repeatable when the image and other settings are unchanged. Straight, Corners and Curves flags control which path segment types may use a configuration. Grid cells use the Straight category. If no configuration permits the required type, generation reports the problem instead of choosing an unrelated entry. An empty mesh field uses the engine cube. An explicitly selected mesh that cannot be loaded reports an error. Materials are loaded when used, so overrides do not need to be open in the editor first. Custom meshes need suitable collision if you want solid walls. The generated components use blocking collision, but a collision profile cannot supply collision geometry missing from a custom mesh. Check material behavior, pivots and clearance with your own assets.
PERFORMANCE, CANCELLATION AND EDITING Max Output Elements defaults to 10,000 and can be set from 1 to 100,000. It limits occupied grid cells or retained path segments, not just actor count. Dense images can exceed the limit even with instancing. Lower image/grid detail first; raising the limit increases processing, memory and editor costs. Meshes Per Batch supports 1-100 elements; Async Batch Delay supports 0.01-1 second. Smaller batches improve responsiveness. Loading a new asset or finalizing a large procedural mesh can still cause a pause. Changing settings during generation affects the next job, not the active snapshot. Cancel stops the current operation and removes its partial output. Closing the tool drains its background work safely. Generation targets the current unlocked editor level. PIE/game worlds are rejected. If the world or current level changes during spawning, the operation stops and removes its partial output. Wait for generation to finish before moving, editing or undoing its generated actors. Generation records editor transactions per batch. Undo may therefore require multiple steps for a large maze. Delete Generated Maze removes the most recently completed result tracked by the current tool window in one transaction. Older generated mazes remain normal level actors that you can select and edit. Cancellation does not delete earlier completed mazes.
PROJECT DEFAULTS AND EDITOR AUTOMATION Project Settings > Plugins > Easy Maze Builder supplies default wall sizes, detection, mesh configurations and performance settings to new tool windows. The existing settings section is preserved when upgrading. Editor Utility Blueprints can get the Maze Builder Subsystem, bind the generation manager's progress/completion delegates, then call Start Maze Generation with a Maze Generation Config. Cancel Maze Generation requests cancellation. These are editor authoring APIs, not runtime gameplay generation nodes. For native editor integrations, depend on EasyMazeBuilderEditor and include MazeGenerationManager.h or MazeBuilderUtils.h. C++ can inspect manager progress and generated actors. Shared data types and MazeActor remain in the EasyMazeBuilder runtime module. Existing editor-class references have redirects, while /Script/EasyMazeBuilder.MazeActor retains its original class path.
SAVING AND PACKAGED GAMES Save your level after generation. Saved individual meshes, grouped components, instances, spline walls and procedural sections are supported in packaged Windows games. Keep this plugin enabled when using grouped MazeActors; its small runtime module preserves their class and component data. The editor generation UI and image analysis are not included as runtime gameplay functionality. The older claim that every output works without the plugin is not applicable to grouped MazeActors. Generation itself does not replicate over a network; multiplayer behavior and any runtime changes are your project's responsibility.
TROUBLESHOOTING - No walls found: check the image, threshold and inversion. Confirm the image contains wall strokes rather than only a maze background. - Too many elements: reduce Target Grid Size or path detail; only raise Max Output Elements when appropriate for the project. - Missing short walls: lower Min Segment Length or increase Max Path Resolution. - Distorted curves: disable smoothing, increase path detail and use a clean image with separated strokes. - No eligible mesh: allow the required Straight, Corners or Curves category on at least one configuration. - Image inaccessible: browse to the file again and check its size, format and permissions. - Walking through custom walls: check the source mesh's collision and the generated component's collision settings. - Falling below the maze: add a floor; the tool generates walls only.
CONTENTS AND SUPPORT 0 Blueprint assets. 12 production C++ classes, including editor UI, helpers, settings, generation management and the saved MazeActor. No third-party source libraries are bundled. ProceduralMeshComponent is an Unreal Engine plugin dependency.
Support: https://discord.gg/9Zc4wbwqG9