119 lines
4.3 KiB
Markdown
119 lines
4.3 KiB
Markdown
# multimaze
|
|
|
|
> A collection of maze generation programs
|
|
|
|
Ported back in 2015 (and since adapted) from an algorithm of my own design that was originally implemented in Python.
|
|
|
|
Now has a 3d mode!
|
|
|
|
Current blog posts about this project:
|
|
|
|
- [Language Review: Lua](https://starbeamrainbowlabs.com/blog/article.php?article=posts/070-Language-Review-Lua.html) (2D maze generator)
|
|
- [3D mazes with Lua, OpenSCAD, and Blender](#coming-soon) (https://starbeamrainbowlabs.com/blog/article.php?article=posts/429-lua-blender-mazes.html)
|
|
|
|
|
|
|
|
## Installation
|
|
|
|
### System Requirements
|
|
- **Required**
|
|
- [Lua](https://lua.org/)
|
|
- **Optional**
|
|
- [OpenSCAD](http://www.openscad.org/): for creating STL files and viewing generated .scad files
|
|
- [Blender](https://www.blender.org/): a great tool for importing generated STL files and having some fun rendering them
|
|
|
|
### Setup
|
|
Clone this repository:
|
|
|
|
```bash
|
|
git clone https://git.starbeamrainbowlabs.com/sbrl/multimaze.git
|
|
cd multimaze.lua
|
|
```
|
|
|
|
|
|
## Usage
|
|
See the usage information for the program by calling `main.lua` like so:
|
|
|
|
```
|
|
lua main.lua help
|
|
```
|
|
|
|
Operating modes:
|
|
|
|
Mode | Description
|
|
--------------------|----------------------
|
|
`help` | Displays the help text
|
|
`maze` | Generates 2D mazes and writes them to stdout
|
|
`maze3d` | Generates 3D mazes and writes them in layers to stdout
|
|
`maze3d_openscad` | Generates 3D mazes and writes an OpenSCAD file to the specified location
|
|
|
|
To render a 2D maze as ASCII, do this:
|
|
|
|
```bash
|
|
lua main.lua maze --width 25 --height 25
|
|
# Alternatively, in shorthand:
|
|
lua main.lua maze -w 25 -h 25
|
|
```
|
|
|
|
To render a 3D maze as a .STL file, do this:
|
|
|
|
```bash
|
|
# Generate the OpenSCAD file
|
|
lua main.lua maze3d_openscad -w 15 -h 15 -d 17 -f 15x15x17.scad
|
|
# Convert the OpenSCAD file to an STL
|
|
openscad -o 15x15x17.stl 15x15x17.scad
|
|
```
|
|
|
|
Users who have sh (Bash works too) installed can use the `maze` wrapper script instead:
|
|
|
|
```bash
|
|
./maze maze3d_openscad -w 15 -h 15 -d 17 -f 15x15x17.scad
|
|
./maze maze -w 25 -h 25
|
|
```
|
|
|
|
### Cookbook
|
|
|
|
#### Make an (almost) seamless texture
|
|
```
|
|
./maze maze_svg --scale 40 -w 31 -h 31 -f maze.svg
|
|
inkscape -o maze.png maze.svg
|
|
convert maze.png -crop 1080x1080+80+80 extract.png
|
|
```
|
|
|
|
The formula here for the crop is:
|
|
|
|
- **width:** w * scale - (scale * 4)
|
|
- **height:** h * scale - (scale * 4)
|
|
- **x offset:** scale * 2
|
|
- **y offset:** scale * 2
|
|
|
|
|
|
|
|
|
|
## Remarks and Observations
|
|
|
|
### Branching factor
|
|
Higher values reduce the number of attention switches the engine executes, leading to fewer branching paths in the resulting maze - this is implemented with a 1-in-N chance to shift the attention of the engine.
|
|
|
|
The value here that works best really depends on your maze. Larger mazes tend to benefit from higher branching factors than the default. 3D mazes tend to look better with slightly lower branching factors, but this is an area of ongoing observation (get in touch if you have anything to add here).
|
|
|
|
|
|
## Contributing
|
|
Contributions are very welcome - both issues and patches! Please mention in your pull request that you release your work under the MPL-2.0 (see below).
|
|
|
|
This guide looks good for how to create patch in git: [How To Create and Apply Git Patch Files](https://devconnected.com/how-to-create-and-apply-git-patch-files/)
|
|
|
|
If you find a bug, there are a number of different ways you can get in touch.
|
|
|
|
1. By commenting on any of the blog posts (see links above)
|
|
2. By getting in touch through any of the methods mentioned on [my main website](https://starbeamrainbowlabs.com/)
|
|
3. If you know me IRL, that works too
|
|
|
|
If this becomes a thing that people want to contribute to regularly, I will move it to GitHub to make that an easier process.
|
|
|
|
If you're feeling that way inclined, I have a [Liberapay profile](https://liberapay.com/sbrl) if you'd like to donate to say an extra thank you :-)
|
|
|
|
|
|
## License
|
|
The contents of this repository is released under the Mozilla Public License 2.0. The full license text is included in the [`LICENSE` file in this repository](https://git.starbeamrainbowlabs.com/sbrl/multimaze/src/branch/master/LICENSE). Tldr legal have a [great summary](https://tldrlegal.com/license/mozilla-public-license-2.0-(mpl-2)) of the license if you're interested.
|