Repolode
Submit
mxgmn

mxgmn/WaveFunctionCollapse

A C# program that generates bitmaps and tilemaps locally similar to a single input example, using the Wave Function Collapse algorithm.

View on GitHub
Stars
25,410
Forks
1,368
Open issues
10
Last commit
4 days ago

What is it?

WaveFunctionCollapse generates new bitmaps or tilemaps from a single sample image or a set of tiles. Its outputs only contain NxN pixel patterns that appear in the input, so the result looks locally similar to the example while forming new global layouts. The name comes from the idea of a superposition of possible states collapsing into a definite one, though the algorithm uses real-valued coefficients rather than actual quantum mechanics.

The algorithm repeatedly picks the least-entropy unobserved region, collapses it to a definite state according to pattern frequencies in the input, and propagates the resulting constraints across the output. If every option for some cell is eliminated, the run hits a contradiction and fails, which the project notes is rare in practice. The repository includes both an overlapping model for pixel-based samples and a simple tiled model for tilesets with adjacency rules, plus a symmetry system to shorten tile adjacency lists.

The project is a console application built on .NET, configured through samples.xml, and writes output to an output folder. It is widely used for procedural level and texture generation in games and pixel art, and it has many ports in other languages.

Key features

  • 01Generates output bitmaps that contain only NxN patterns present in a single input image.
  • 02Supports an overlapping model for pixel samples and a simple tiled model for tilesets.
  • 03Uses minimal-entropy selection to choose which region to collapse next.
  • 04Includes a tile symmetry system to reduce the size of adjacency lists.
  • 05Runs as a .NET console application configured through samples.xml.

Use cases

  • Generating game levels or dungeon layouts from hand-made tilesets.
  • Creating pixel-art maps or textures that resemble a sample image.
  • Prototyping procedural generation with constraints placed by a designer.
  • Studying or teaching the Wave Function Collapse algorithm.

Topics

#procedural-generation#wfc#gamedev#algorithm#tilemap#pixel-art#constraint-satisfaction#csharp#machine-learning

FAQ

What is WaveFunctionCollapse?
A C# program that generates bitmaps and tilemaps locally similar to a single input example, using the Wave Function Collapse algorithm. WaveFunctionCollapse generates new bitmaps or tilemaps from a single sample image or a set of tiles. Its outputs only contain NxN pixel patterns that appear in the input, so the result looks locally similar to the example while forming new global layouts. The name comes from the idea of a superposition of possible states collapsing into a definite one, though the algorithm uses real-valued coefficients rather than actual quantum mechanics.
Is WaveFunctionCollapse free to use? What license does it have?
WaveFunctionCollapse is open source under the Other license. Check the license terms before using it in commercial products.
Is WaveFunctionCollapse still maintained?
Actively maintained. The last commit to WaveFunctionCollapse was on Oct 15, 2026.
What can I use WaveFunctionCollapse for?
Generating game levels or dungeon layouts from hand-made tilesets. Creating pixel-art maps or textures that resemble a sample image. Prototyping procedural generation with constraints placed by a designer. Studying or teaching the Wave Function Collapse algorithm.
Where can I get WaveFunctionCollapse?
The source code and installation instructions are on GitHub: https://github.com/mxgmn/WaveFunctionCollapse

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects