WaveFunctionCollapse - Deployment and Usage Guide

Prerequisites

• Runtime: .NET 6.0 or later
• IDE: Visual Studio 2022 or JetBrains Rider (optional)
• Build Tools: MSBuild or dotnet CLI
• Image Processing: SixLabors.ImageSharp library (included via NuGet)
• XML Processing: System.Xml.Linq (included in .NET)

Installation

1. Clone the repository:

   git clone https://github.com/mxgmn/WaveFunctionCollapse.git
   cd WaveFunctionCollapse
   

2. Restore NuGet packages:

   dotnet restore
   

3. Build the project:

   dotnet build
   

Configuration

Sample Configuration

The application uses an XML configuration file samples.xml located in the project root. This file defines the input samples and generation parameters.

Key Configuration Options

For Overlapping Models:

• name: Name of the sample (corresponds to PNG file in samples/ folder)
• N: Pattern size (default: 3)
• width: Output width (default: 48)
• height: Output height (default: 48)
• periodicInput: Whether input is periodic (default: true)
• periodic: Whether output is periodic (default: false)
• symmetry: Symmetry options (default: 8)
• ground: Ground constraint (default: false)
• heuristic: Heuristic type (Entropy/MRV/Scanline)

For Simple Tiled Models:

• name: Name of the tileset (corresponds to XML file in tilesets/ folder)
• subset: Optional subset name
• width: Output width (default: 24)
• height: Output height (default: 24)
• periodic: Whether output is periodic (default: false)
• blackBackground: Whether to use black background (default: false)
• heuristic: Heuristic type (Entropy/MRV/Scanline)

Environment Variables

No specific environment variables are required for basic operation.

Build & Run

Running Locally (Development)

1. Run with default samples:

   dotnet run
   

2. Run with specific configuration:

   dotnet run -- -c path/to/custom/samples.xml
   

3. Generate specific sample: Edit samples.xml to include your desired sample configuration, then run:

   dotnet run
   

Output

Generated images will be saved in the output/ folder. The application will automatically clean this folder on each run.

Production Build

dotnet publish -c Release -r win-x64 --self-contained

This creates a self-contained executable for Windows x64 architecture.

Deployment

Platform Options

Windows Desktop Application:

• Publish as self-contained executable
• Distribute the output folder with generated images

Web Application:

• Use one of the JavaScript ports for browser deployment
• Consider the p5js or vanilla JavaScript implementations

Unity Integration:

• Use the Unity port for game development
• Import the WFC asset into your Unity project

Game Engine Integration:

• Unreal Engine 5 has built-in WFC support
• Houdini has WFC integration for procedural generation

Recommended Deployment Platforms

1. Desktop: Windows executable (self-contained)
2. Web: Static hosting (Vercel, Netlify) for JavaScript ports
3. Game Development: Unity/Unreal Engine projects
4. Research/Prototyping: Local development with sample configurations

Troubleshooting

Common Issues

1. Missing Sample Files

ERROR: subset {subsetName} is not found

• Ensure the specified subset exists in the tileset XML
• Check that the sample PNG file exists in the samples/ folder

2. Compilation Errors

• Ensure .NET 6.0 or later is installed
• Run dotnet restore to fetch NuGet packages
• Check for missing using statements in source files

3. Image Loading Issues

• Verify PNG files are in the correct format
• Ensure image files are not corrupted
• Check that the image dimensions match expected patterns

4. Algorithm Contradiction

• The algorithm may fail if no valid configuration exists
• Try increasing the output size or changing the heuristic
• Use a different sample image with more diverse patterns

5. Performance Issues

• Large pattern sizes (N > 5) significantly increase computation time
• Consider using the MRV heuristic for better performance
• Reduce output dimensions for faster generation

Debug Mode

Add debug logging by modifying the Program.cs file to output intermediate states during wave function collapse.

Validation

• Check that generated images maintain local similarity to the input
• Verify that all NxN patterns in output exist in the input sample
• Ensure the distribution of patterns matches the input distribution

Performance Optimization

• Use smaller pattern sizes (N=2 or N=3) for faster generation
• Enable periodic input for seamless tiling
• Choose appropriate heuristics based on your use case