Skip to content

About

2D Wave Function Collapse as Blender Plugin

Topics

Resources

Stars

41 stars

Watchers

1 watching

Forks

Repository files navigation

WFC Tile Grid

A Blender 4.5+ extension for 2D Wave Function Collapse. It learns overlapping color patterns from an image, solves a grid, and fills that grid with tile meshes you can edit. The solver is plain Python and Geometry Nodes places the tiles. It needs no external packages or services.

The original 2019 add-on (Blender 2.80) lives on the archive/pre-ai branch, untouched. Everything on master after it was written with AI assistance. The two are not compatible. The old image-only Collapse and Module Instancer operators are gone, and old scene settings are not migrated. Objects generated by the old version stay in saved scenes as ordinary Blender data.

Install

Build an extension ZIP from the add-on directory:

mkdir -p dist
blender --background --command extension build --source-dir . --output-dir dist

In Blender, open Edit → Preferences → Get Extensions → Install from Disk, pick dist/wfc_tile_grid-1.3.0.zip and enable it. You can also drop this directory into your add-ons path. Restart Blender after replacing an installed version.

Generate a grid

  1. Open a small source image with Image → Open in the Image Editor. In the 3D View sidebar, go to the WFC tab and pick it as Pattern Source.

  2. Set Pattern X/Y (2×2 or 3×3 works well), Output X/Y, and optional rotation and flips. The image must be at least as large as the pattern in each direction.

  3. Seed makes a result repeatable. Attempts is how many times the solver retries after a contradiction.

  4. Pick Tiles.

    • By Color makes one tile per color.
    • By Neighbors makes one tile per color plus the colors of its left, right, upper and lower neighbors, so edges, ends and junctions each get their own tile.
    • By Neighbors + Corners adds the four diagonals.

    Cells on the output border count as having no neighbor on that side. The tile count grows fast, and more than 256 tile types is rejected. Click Generate Tile Grid.

  5. The new WFC Grid object has a Geometry Nodes modifier and an integer point attribute wfc_tile_id. The WFC Tiles collection holds one mesh per tile, named Tile 000, Tile 001 and so on. Edit or swap their mesh data and the grid follows. Each tile keeps its identity in the wfc_tile_key custom property. Tile Scale in the modifier changes tile size. Grid spacing stays at one Blender unit.

  6. With the grid selected, Regenerate Selected Grid solves again with the current settings and keeps your tile edits. A tile is reused whenever its wfc_tile_key comes up again. Tiles the new result does not use stay at the end of the collection, including after you switch Tiles mode. With nothing selected, Generate makes a separate output.

Relations view

Click Show Tile Relations with the grid selected. The WFC Relations object lays out every distinct neighborhood found in the solved grid, one block each. A block has a centre tile and up to one neighbor per side (right is +X, up is +Y). A side outside the grid has no tile. A neighborhood that repeats appears once, and rows group blocks by source color.

Each tile in a block is a real object in the WFC Relations Tiles collection, and it shares the mesh of its tile in WFC Tiles. Tab into any of them and change the geometry. Every other block and the grid update. Only mesh data is shared, so modifiers or material overrides on one object stay on that object.

The modifier has Tile Scale, Neighbour Scale, Distance, Block Spacing and Line Radius, and the tile objects follow them through drivers. If you move or rotate a tile object by hand, the next refresh puts it back. Regenerating the grid refreshes the view too.

Labels and outlines

Both node groups have Show Labels, Show Source Relation, Label Size, Label Offset and Label Extrude. Labels show source.variant (zero-based color and variant ids) or the tile id, and Geometry Nodes generates them, so they never end up in the tile meshes. Set font and outline colors under Tile Appearance before you generate or regenerate. The grid also stores wfc_source_id and wfc_variant_id on its points.

Notes

The solver wraps the source image at its edges when it learns rules. The output grid does not wrap. Colors are compared to four decimal places, and each output cell takes its color from the origin of the pattern solved there. The palette index is an instance index, not a material selection.

Large patterns and noisy images create many unique rules, which makes solving slow or contradictory. If every attempt fails, use a smaller or cleaner image, or change the seed.

Original WFC concept: Maxim Gumin's WaveFunctionCollapse. Original Blender implementation by Benjamin Kleinert, inspired by Victor Le's Python version. MIT license.

About

2D Wave Function Collapse as Blender Plugin

Topics

Resources

Stars

41 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages