Wave Function Collapse for Defold

I have been always interested in procedural generation of terrain, vegetation and all other things natural. This probably stems from my early days with the C64 and mandelbrots, and bifurcation trees :slight_smile:

I ran into this pretty awesome algo - Wave Function Collapse earlier this year while watching some discussions of coding on youtube:

There is alot of detail in here, so I’ll kind of summarize. The idea is to take a source image (for overlapped model) and it gets broken down into patterns based on parameters you supply. These patterns become ‘actions’ that the model determines are core baseline operations, then it can regenerate a new image (with other parameters) from a numeric seed (not currently exposed in the gui, I will add this). The end result is an image that follows the image structure “rules” as provided by the source image.

Example outputs:
3Bricks 50312382
Village 39802682

The simple tiled model is a little more complex. The model is supplied with a “tile set” and its action functions are based of rules of allowed connectivity between each tile, that you define in the data.xml file. This can then generate output tilemaps that are consistent with the tiles rules.

Example outputs:

FloorPlan 31859730

I decided to port this awesome code base to Defold and build an app around it. The project is available here:

And some screenies:

Note this screenshot is important. If you decide to make width and height big or you tweak some values which creates longer run times, the button you press to run the model will go red, and stay that way until the process is complete. Big complex ones can take quite some time.

I’ll add some notes in the readme and update it intermittently. Its MIT license (source code and project) but the sample images are all CC 2.0. Please do not use them in commercial projects unless you use the appropriate license process. I will be replacing the samples over time to publicly free ones. That may take some time though.

Feel free to use as you want either as a library or expand the tool. Has been another fun little tool to build.


Little update below is a little list of things to know/watch out for:

  • The system is built around mxgmn’s work, and as such uses samples.xml and data.xmls for alot of the configuration. Please refer to his github for more details about it. Building data.xmls for tilemaps is not so trivial :slight_smile:
  • You can crash this a little too easily. Im putting some trapping in to try to make it a little more stable when you put in nasty params and files.
  • I need to add an “exit” button or something similar when processing goes on too long - putting in a big width or height, or setting some parameters poorly can do this.
  • Ideally Id like to be able to resize the picture without nasty filter blurs - will attempt to get this sorted.

To make a new sample/tilemap setup, examine the original source image for overlapping model files, look at the settings in samples.xml and copy/modify. For tilemaps, find a tilemap that is similar, copy the folder, and then slowly work through the neighbors list. If neighbor params are missing, when you run the project there will be errors explaining this.

Note on running the project in Defold - always run with Ctrl+B (non debug). The Debug build can be really slow. Recommended only for debugging. < doh >

If you have any questions. feel free to post here or on discord.


Fantastic! This is really cool. One neat thing would be if it was possible to generate a tilesource and tilemap from the input data.


Definitely. The generation of the output bitmap is from a set of tile ids, so it should be possible to push that into a tilesource file.