Wave Function Collapse 3D

A 3D procedural generation tool using the Wave Function Collapse algorithm, built with React Three Fiber and TypeScript.

Overview

This project implements the Wave Function Collapse (WFC) algorithm for procedural 3D world generation using modular 3D tiles with defined adjacency rules to generate coherent structures in a 3D world.

Features

• 3D Wave Function Collapse algorithm — Generate 3D worlds using constraint-based tile placement
• Real-time Visualization — Watch the algorithm collapse cells step-by-step or run instantly
• Editor Mode — Browse, inspect and edit the result
• Custom Modules — Support for custom 3D models with adjacency rules defined in JSON
• Interactive Controls — Orbit, zoom, and explore generated worlds

Tech Stack

• React Three Fiber — React renderer for Three.js
• Three.js — 3D graphics library
• TypeScript — Type-safe JavaScript
• Vite — Fast build tool
• Zustand — State management

Getting Started

Prerequisites

• Node.js (v18+)
• npm or yarn

Installation

# Clone the repository
git clone <repository-url>
cd wave-function-collapse

# Install dependencies
npm install

Development

# Start the development server
npm run dev

Open http://localhost:5173 to view the app in your browser.

Build

# Build for production
npm run build

Usage

WFC Mode

1. Click "Start WFC (instant)" to generate a world immediately
2. Click "Start WFC (auto animated)" to watch the generation process
3. Click "Start WFC (step by step)" to advance one step at a time
4. Use "Reset WFC" to clear and start over

Editor Mode

Toggle between WFC Mode and Editor Mode using the button in the top-left corner. Editor Mode allows you to browse all available prototype tiles.

Project Structure

src/
├── WaveFunctionCollapseV2/     # Core WFC algorithm
│   ├── Cell.ts                 # Cell state management
│   ├── Map3D.ts                # 3D grid structure
│   ├── WaveFunctionCollapse.ts # Main WFC logic
│   └── Prototype/              # Tile prototype definitions
├── World/                      # 3D world rendering
├── Editor/                     # Editor mode components
└── Resources/                  # Providers and utilities

Custom Modules

Custom 3D modules are stored in public/models/wfc_modules/:

• wfc_modules.glb — 3D model file containing all tile meshes
• prototype_data.json — Adjacency rules and prototype definitions

License

MIT