mxgmn/WaveFunctionCollapse: bitmap and tilemap generation from one example

What mxgmn/WaveFunctionCollapse actually generates

The program generates bitmaps that are locally similar to the input bitmap. Local similarity is defined by the README as two conditions: the output should contain only those NxN patterns of pixels present in the input (C1), and the distribution of NxN patterns over a sufficiently large number of outputs should be close to the density of those patterns in the input (weak C2). A typical value of N in the examples is 3.

The audience is narrow. This is not a level editor or a game engine plugin. It is a C# program that reads a sample bitmap and writes generated bitmaps. The README lists the engines and languages that have adopted the idea separately: Unity, Unreal Engine 5, Godot 4 and Houdini adaptations exist, and ports exist in C++, Python, Rust, Go, JavaScript and others. If you are working in one of those ecosystems, the reference implementation is useful mainly as the definition of the algorithm, not as the thing you ship.

The repository layout matches that reading. The top level holds Program.cs, Model.cs, OverlappingModel.cs, SimpleTiledModel.cs, Helper.cs, WaveFunctionCollapse.csproj, samples.xml, and the samples/ and tilesets/ directories. There is no library project, no NuGet packaging metadata visible at the top level, and no public API surface described in the README.

The observation and propagation cycle, and where it breaks

The README describes the mechanism in five numbered steps. First, read the input bitmap and count NxN patterns, optionally augmenting the pattern data with rotations and reflections. Second, create an array with the dimensions of the output, called the wave in the source, where each element is a state of an NxN region: a superposition of input patterns with boolean coefficients. False means the pattern is forbidden, true means it is not yet forbidden. Third, initialize the wave with all coefficients true.

Then the cycle runs. On an observation step, the program finds the wave element with the minimal nonzero entropy and collapses it into a definite state according to its coefficients and the distribution of NxN patterns in the input. On a propagation step, information gained from that collapse spreads through the output. The README notes that the coefficients in these superpositions are real numbers, not complex numbers, so the program does not do actual quantum mechanics; it was inspired by quantum mechanics.

The failure mode is explicit. It may happen that during propagation all the coefficients for a certain pixel become zero, meaning the algorithm has run into a contradiction and cannot continue. The README states that determining whether a bitmap allows other nontrivial bitmaps satisfying condition (C1) is NP-hard, so no fast solution can always finish. In practice, the README says, contradictions are surprisingly rare. Rare is not never, and there is no repair step: the run ends without returning output.

There is also a degenerate exit. Step 4.1.1 breaks the cycle if no wave element has nonzero, defined entropy, and step 5 then returns the output only if every element is fully observed. Otherwise the work finishes without returning anything. Neither branch is a partial result you can patch up.

Building the C# program and running a first sample

The README points to a how-to-build section for building from source and to the releases page for an official Windows release. The repository is a .NET project file, WaveFunctionCollapse.csproj, and the README's build section is the place to look for the exact build command; it is not reproduced here because the README does not print it in the text available.

The samples directory contains the input bitmaps the program is normally run against, including samples/Cat.png, samples/Cave.png, samples/City.png, samples/Dungeon.png, samples/Forest.png, samples/Knot.png and samples/Maze.png. The samples.xml file at the top level is the sample list the program reads. A typical entry names a sample and the model to use, and the README's algorithm section maps onto the two model classes in the repository, OverlappingModel.cs and SimpleTiledModel.cs. The README does not print a full samples.xml entry, so read the file itself before editing it; do not copy a guessed schema.

For tilemap generation, the README describes the simple tiled model as the case where the algorithm stores probabilities of colors or tiles rather than of pixel patterns, and the propagation phase is just adjacency constraint propagation. It says this model is convenient to initialize with a list of tiles and their adjacency data. The tilesets directory is where those inputs live. The README does not give the command-line flags for selecting a model or an output size, so check Program.cs for the argument parsing before you script anything.

Contradictions, retries, and what the README does not cover

The honest limitation is the contradiction. A run either returns a fully observed output or finishes without returning anything. There is no documented backtracking, no partial output, and no rollback procedure in the README. If your generator must always produce a level, you have to wrap the run in a retry loop yourself, and you have to accept that a retry is a new run from the initial unobserved state, not a repair of the failed one.

The README is also silent on several things an adopter will want. It does not document a configuration file format beyond the existence of samples.xml. It does not state memory or time behaviour as a function of output size. It does not describe a stable public API, so code that calls into Model.cs or OverlappingModel.cs is coupled to internal structure. The release history supports that reading: the most recent release is v1.00 from 2022-07-21, even though the repository has received commits since then, with the last push on 2026-03-22.

Where it is the wrong tool: if you need guaranteed termination, a supported library with semantic versioning, or generation that respects global gameplay constraints such as reachability or difficulty curves, this program does not offer them. It satisfies local constraints derived from the sample. Global structure emerges from the sample's statistics, not from anything you specify.

How the ports differ from the reference implementation

The README's own alternative list is the ports. The difference in approach is mostly the host language and its runtime, not the algorithm. The C++ port at math-fehr/fast-wfc is presented as a performance-oriented reimplementation; the Python port at ikarth/wfc_2019f trades speed for readability and integration with Python tooling; the Rust port at Elwqnn/wfc and the Go port at shawnridgeway/wfc give you a compiled binary in a different ecosystem. The JavaScript port at kchapelier/wavefunctioncollapse is the one behind the browser demo the README links, and it is the practical choice if you want the overlapping model running client-side.

Engine integrations are a different kind of alternative. The Unity adaptation, the Unreal Engine 5 Blueprint nodes and the Godot 4 port are not ports of this codebase so much as reimplementations that expose generation inside an editor workflow. If your target is a game engine, adopting mxgmn/WaveFunctionCollapse means writing the bridge yourself.

One caveat applies to all of them. The README says WFC generates levels in Bad North, Caves of Qud, Dead Static Drive, Townscaper and Matrix Awakens, and that it led to new research. Those are references to the algorithm's use, not endorsements of this C# program as the implementation those projects shipped.

Licence and maintenance cost of the reference codebase

The repository's licence is reported as NOASSERTION, which means the licence file could not be matched to a standard identifier. The top level contains a LICENSE file, so read that file directly before you reuse any code. This is not legal advice, and the practical point is narrow: do not assume a permissive licence from the GitHub label when the label says NOASSERTION.

Upgrade cost is low in one sense and high in another. Low, because the codebase is a handful of C# files and the algorithm does not change; there is nothing to upgrade between v1.00 and the current tree in the way a library with frequent releases would demand. High, because there is no compatibility promise. If you copy Model.cs or OverlappingModel.cs into your project, future commits to those files are your problem to reconcile. If you build against the csproj, you are building a program, not linking a library.

The maintenance signal is mixed. The repository is not archived, and the last push was on 2026-03-22, so it is not abandoned. But the last tagged release is v1.00 from 2022-07-21, and the README does not describe a release process or a supported version. Treat the source tree as the reference and pin whatever commit you use.

Editorial conclusion

Adopt mxgmn/WaveFunctionCollapse if you want the reference implementation to read, port or study, and if a failed run is acceptable because you can retry. Do not adopt it if you need a supported library with a stable API, a documented rollback path, or a packaged release for your platform: the repository is a C# console program, the last release is v1.00 from 2022-07-21, and the README does not document any configuration of the algorithm beyond the sample list. Before you build anything on it, check whether the output size and pattern size you need are exposed in Program.cs or samples.xml, and confirm that a contradiction simply ends the run so your own code has to retry.

Frequently asked questions

Official sources

1. Issues
2. mxgmn/WaveFunctionCollapse on GitHub
3. README
4. Releases