Wave Function Collapse JavaScript: Procedural Tile Maps for Game Levels

You’ve probably thought about giving your agent the ability to create a tile-based world. Great, he made you a dungeon you could play in. Awesome. Wait…isn’t that dungeon the same one from last time? Exactly the same rooms in the exact same order? You can’t unsee it now.

WFC (Wave Function Collapse) is a scientific algorithm developed by Maxim Gumin in C# originally. Since then, it has been ported to virtually every language. There’s a longstanding JS port by Kevin Chapelier available on npm for years, and it’s been quietly working away under the radar, licensed under the MIT license. I had need of random maps for a browser game and found it to be a perfect solution.

This package provides you with two models. OverlappingModel allows you to train on a sample image to learn local patterns that are then translated across the generated output, placing similarities at different points. SimpleTiledModel lets you set up tiles and define which edges can be connected to which other edges. The result is a map that has tiles fitting within the constraints you provide. SimpleTiledModel is good for dungeon floorplans and room-based maps.

1How to add it to your project

It’s as simple as running a single command, creating an ImageData on a canvas, feeding that into the model and calling generate() to get the pixel data back out for drawing on a canvas.

npm install wavefunctioncollapse --production

2How OverlappingModel works

Feed it some sample image data, like a portion of a tilemap or a hand drawn map. It traverses through the NxN block, learning what combinations can go together and fills an empty canvas by collapsing down the options on a cell by cell basis, much like sudoku. In the animated demo here, you can watch it build out the maps in real time. It’s actually hypnotic.

3Using SimpleTiledModel for dungeon maps

For SimpleTiledModel, you provide a JSON object detailing the tiles you want to use and their edge restrictions. You tell the algorithm which sides can be connected to which other sides, and it lays out tiles so they adhere to the rules you defined. Nothing in the middle of the wall, no dead ends on the road, etc. Constraints are constraints.

4What to tell your agent

If you want, you can simply tell your agent what package name to use and the kind of model you’re looking for. If your agent is familiar with WFC, it may be able to access wavefunctioncollapse right on npm and get started. Check out one of the 3 interactive demos on the project site to get a feel for what’s possible and communicate that to your agent.