N-dimensional support: Works with 2D, 3D, 4D, and higher dimensions
Optimized performance: Efficient constraint propagation and entropy calculation
Flexible tile system: Support for weighted tiles and custom constraints
Third-party integration: Built-in support for JSON (RapidJSON), textures (STB), and 3D models (Assimp)
SDL2 graphics: Windowing and rendering capabilities for visualization
Comprehensive testing: Google Test integration for robust testing

Project Structure

nd-wfc/
├── CMakeLists.txt              # Main CMake configuration
├── cmake/
│   └── nd-wfc-config.cmake.in  # CMake package config
├── include/nd-wfc/            # Public headers
│   ├── types.hpp              # Core types and enums
│   ├── wfc.hpp                # Main WFC class
│   ├── grid.hpp               # N-dimensional grid
│   ├── wave.hpp               # Wave function representation
│   ├── propagator.hpp         # Constraint propagator
│   ├── entropy.hpp            # Entropy calculator
│   ├── constraint.hpp         # Constraint management
│   └── tile.hpp               # Tile system
├── src/                       # Implementation files
├── tests/                     # Google Test files
│   ├── CMakeLists.txt
│   ├── test_main.cpp
│   └── test_wfc.cpp
├── examples/                  # Example programs
│   ├── CMakeLists.txt
│   ├── basic_wfc_2d.cpp
│   ├── basic_wfc_3d.cpp
│   ├── texture_generation.cpp
│   └── model_generation.cpp
├── thirdparty/                # External dependencies
│   └── CMakeLists.txt
└── build/                     # Build directory (generated)

Building the Project

Prerequisites

CMake 3.16 or higher
C++17 compatible compiler (GCC 8+, Clang 8+, MSVC 2019+)
Git

Build Instructions

# Clone the repository
git clone <repository-url>
cd nd-wfc

# Create build directory
mkdir build
cd build

# Configure with CMake
cmake ..

# Build the project
cmake --build . --config Release

# Run tests
ctest --output-on-failure

# Run examples
./examples/basic_wfc_2d

CMake Options

ND_WFC_BUILD_TESTS=ON/OFF - Build tests (default: ON)
ND_WFC_BUILD_EXAMPLES=ON/OFF - Build examples (default: ON)
ND_WFC_USE_SYSTEM_LIBS=ON/OFF - Use system libraries instead of bundled (default: OFF)

Usage

Basic 2D Example

#include "nd-wfc/wfc.hpp"
#include "nd-wfc/types.hpp"

int main() {
    // Create a 10x10 grid
    nd_wfc::Size<2> size = {10, 10};

    // Define tile types
    std::vector<nd_wfc::TileId> tiles = {0, 1, 2, 3};

    // Define constraints (adjacency rules)
    std::vector<nd_wfc::Constraint> constraints = {
        {0, 0, nd_wfc::Direction::North}, // Tile 0 can connect to tile 0 from North
        {0, 1, nd_wfc::Direction::South}, // Tile 0 can connect to tile 1 from South
        // ... more constraints
    };

    // Configure WFC
    nd_wfc::WfcConfig config;
    config.seed = 12345;

    // Create and run WFC
    nd_wfc::Wfc2D wfc(size, tiles, constraints, config);
    nd_wfc::WfcResult result = wfc.run();

    if (result == nd_wfc::WfcResult::Success) {
        // Access the result
        const auto& grid = wfc.getGrid();
        // Use grid data...
    }

    return 0;
}

3D Example

// Create a 3D WFC instance
nd_wfc::Size<3> size = {8, 8, 8};
nd_wfc::Wfc3D wfc(size, tiles, constraints, config);

Third-party Libraries

The project includes several third-party libraries:

RapidJSON: JSON parsing and serialization
STB: Image loading and manipulation (STB Image, STB Image Write)
Assimp: 3D model loading and processing
SDL2: Graphics and windowing
Google Test: Unit testing framework

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

References

Original WFC Algorithm: https://github.com/mxgmn/WaveFunctionCollapse
N-dimensional WFC concepts and optimizations
Various academic papers on constraint satisfaction and procedural generation