1. General
Where is the FireMaze panel?
Open the 3D Viewport, press N to open the sidebar, and select the FireRat tab. If the tab is missing, ensure FireMaze is enabled in Edit → Preferences → Extensions.
How do I install FireMaze?
Zip the FireMaze/ subdirectory, then in Blender go to Edit → Preferences → Get Extensions, click the dropdown arrow (▼) in the top-right corner, choose Install from Disk..., select the ZIP, and enable it.
Does FireMaze work in Blender 3.x or 4.0?
No. FireMaze requires Blender 4.2+.
2. Maze Generation
"Width and Depth must be at least 3"
Rectangular grids require both dimensions ≥ 3. Increase Width and/or Depth in the Maze Settings panel.
"Rings must be at least 2"
Polar grids need at least 2 rings. Increase Rings (range 3–15) in the Maze Settings panel.
"Rings must be even when wall_mode='cube'"
Cube mode with a polar grid requires an even number of rings. If you see this warning, adjust the Rings spinner to an even value (4, 6, 8, …).
"All cells are blocked; cannot generate maze"
Every cell was excluded — usually because an image mask left zero walkable cells. Check your Mask Image and Invert settings. Try clearing the mask and generating again.
"All candidate entrance/exit cells were blocked by mask."
The mask left no valid cells on the boundary to place the entrance or exit. Adjust the mask or disable it.
"Failed to carve the requested count of {count} border openings on side {side}."
The maze has fewer boundary cells than the requested openings. Reduce Entrance/Exit Count or increase the grid size.
"Mask image ignored when Floors > 1"
Masking is not supported on multilevel mazes. Set Floors to 1 to use image masking.
Why does my maze keep looking the same?
Check whether Random Seed is set to a fixed value in the Advanced section. Set it to 0 (auto) for a different maze on each generation.
Why aren't my custom tiles appearing?
- Ensure you have assigned a Custom Collection in the Custom Tiles panel.
- For polar grids, set Polar Custom Alignment to Trapezoidal Scaling or Polar Bending (Warp) — Procedural Only mode ignores custom tiles.
- Make sure the collection contains valid mesh objects centered at the origin.
3. Interactive Editor
"No generated maze found to edit. Please generate a maze first."
Generate a maze before entering the interactive editor.
How do I enter/exit the interactive editor?
- Enter: Click Interactive Edit in the sidebar (or press the mapped key).
- Exit: Press Esc or Enter to exit edit mode.
How do I toggle walls?
Left-click on a wall to toggle it on/off. The wall reappears after the next rebuild.
How do I cycle meshes?
Shift + Left-click on a cell face to cycle through the meshes in your custom tile collection.
How do I place stairs?
Select the Toggle Stairs tool from the sidebar during edit mode (only shown when floors > 1). Left-click on a floor cell to place a stair or toggle an existing one. Shift+Left-click on an existing stair to rotate its orientation. Stairs cannot be placed on the top floor.
How do I set entrance/exit?
Entrances and exits are managed automatically — toggling a perimeter cell on floor 0 creates an entrance, toggling one on the top floor creates an exit. Switching to a different perimeter cell moves the entrance/exit. Toggling a perimeter cell back to wall removes it.
4. Multilevel Mazes
"Cannot place stair on the top floor"
Stairs must lead to a floor above. Place stairs on floors ≤ (Floors − 1).
"Cannot place entrance/exit on middle floors"
Entrances and exits are only valid on floor 0 (ground floor).
Stairs look disconnected or misaligned
Ensure stair Style matches your wall mode — use Stair for Thin mode, Ramp for Cube mode. Check the Footprint setting: 1×1, 1×2, or 2×2. Polar grids only support 1×1.
5. Polar (Circular) Grids
What do the three Polar Custom Alignment modes do?
| Mode | Behavior |
|---|---|
| Procedural Only | No custom tiles — uses native wedge/arc meshes |
| Trapezoidal Scaling | Stretches custom tiles into wedge shapes via bilinear interpolation |
| Polar Bending (Warp) | Warps custom tile vertices along circular arcs with subdivision for smooth curvature |
What does radial_bias control?
- 0.0 — tangential preference (corridors wrap around rings)
- 1.0 — radial preference (corridors run along spokes)
- 0.5 — balanced
Why is my custom tile distorted in polar mode?
Polar Bending and Trapezoidal Scaling both deform tile geometry. For best results, use a simple, axis-aligned mesh centered at the origin. Highly detailed meshes may perform poorly — subdivision cuts are automatically capped (max 2 for dense meshes) to prevent vertex explosion.
6. Vertex Painting & Post-Processing
The vertex colors don't look right
Check the Paint Mode:
| Mode | Formula |
|---|---|
| AO | 1 − (distance_to_closest_wall / max_dist) |
| Blend | (rx + ry + rz + cx + cy + cz) / 6 where (rx, ry, rz) = distance to cell walls and (cx, cy, cz) = world center falloff |
| Path | Distance from cell to guide path, inverted |
| Distance | Raw distance to entrance cell |
Run Post-Processing after painting to apply merge, dissolve, and collider steps.
Colliders are not visible in viewport
Colliders are generated as separate meshes with the _Collider suffix. Enable Viewport Display → Wireframe or Bounds on those objects. They are invisible in Solid/Viewport shading by default.
7. Props & Decors
Why are no props spawning?
- Ensure the Prop Collection is assigned in the Prop Spawner panel.
- Check Spawn Chance — if set to
0, nothing spawns. - Regenerate or rebuild the maze after assigning the collection.
Why did my props disappear after regenerating?
Rebuilding the maze clears all existing prop meshes (the prop sub-collection is deleted and recreated). Props are re-spawned from scratch using the seeded RNG, so the same seed will produce identical placements.
8. Sessions & Autosave
"No autosave file found"
There is no recovery file to restore. This can happen if you already discarded it or if no maze was generated in the previous session.
How do I restore after a crash?
- Open Blender and enable FireMaze.
- In the Session & Image Management panel, a yellow recovery box appears.
- Click Restore Session to recover the last generated maze.
- Click Discard to dismiss the recovery data permanently.
Can I move a maze between Blender files?
Yes — use Save Session to Disk to export a .json file, then Load Session from Disk in the other file. External mesh/collection/image references are matched by name — they must already exist in the target .blend.
"File not found" when loading a session
The .json file was moved, renamed, or deleted. Check the file path.
Why are my custom meshes missing after loading a session?
Session files store references by name (not by pointer). If the custom collection or mesh objects have different names in the target .blend, they won't re-link. Rename them to match the original names, or ensure they exist before loading.
9. Image Export & Masking
The exported PNG is all black or all white
- Check the Invert toggle.
- Ensure you have a valid maze layout. Generate or load a maze before exporting.
"Failed to save image file"
The destination path may be read-only or the disk may be full. Choose a different directory.
The mask image had no effect
- Verify the mask is assigned in the Masking & Image Export section.
- Masking only works with Floors = 1.
- Check Invert if the mask is using opposite luminance values.
- Masks use luminance threshold: pixels brighter than the threshold become walkable (or blocked when inverted).
10. Error & Warning Reference
| Message | Likely Cause | Solution |
|---|---|---|
Width and Depth must be at least 3 | Grid too small | Increase Width/Depth to ≥ 3 |
Rings must be at least 2 | Polar rings too low | Set Rings ≥ 2 |
Rings must be even when wall_mode='cube' | Odd rings + Cube mode | Use an even ring count |
All cells are blocked | Mask covers everything | Disable or adjust the mask |
No generated maze found | Nothing to edit | Generate a maze first |
Cannot place stair on top floor | Stair on last floor | Place on floor < Floors |
Cannot place entrance/exit on middle floors | Multilevel restriction | Use floor 0 only |
No autosave file found | No recovery data | Generate a new maze |
File not found | Session/mask path invalid | Verify the file exists and path is correct |
Failed to save image file | Disk/path issue | Use a different directory |
11. Getting Help
If your issue isn't listed here, open an issue on the GitHub tracker:
https://github.com/FireRat666/FireMaze/issues
Include:
- FireMaze version (from
__init__.py) - Blender version
- Steps to reproduce
- Full error message (from Blender's Window → Toggle System Console)