WAIT — Single-maintainer risk — review before adopting

• Last commit 7w ago
• 14 active contributors
• Other licensed
• ⚠ Single-maintainer risk — top contributor 85% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Wave Function Collapse is a procedural generation algorithm implemented in C# that generates novel bitmaps and tilemaps that are locally similar to an input example by extracting NxN patterns and using constraint propagation inspired by quantum mechanics. It reads a single sample image, learns the frequency distribution of tile/pixel patterns within it, then iteratively collapses a superposition of possibilities into a complete output that respects the learned pattern constraints. Monolithic C# application with three core model classes: Model.cs (abstract base), OverlappingModel.cs (pixel-pattern based generation), and SimpleTiledModel.cs (discrete tile-based generation). Helper.cs contains utility functions. Program.cs ties everything together with samples.xml defining input/output configurations for batch generation. No separation into library vs. application; the entire project is a single executable that reads images from samples/ directory.

Game developers and procedural content creators who need to generate dungeon layouts, textures, or level designs from a single example without hand-coding rules. Also useful for researchers exploring constraint-based generation and pattern-learning algorithms.

The project is stable and well-established with multiple language implementations listed in README.md, suggesting proven algorithmic correctness. However, the C# implementation shows no recent commits visible in the file metadata, and the repository appears to be a reference implementation rather than an actively maintained library. No automated test suite is visible in the file structure (no Tests/ or test directories listed), which limits confidence in ongoing maintenance.

Single-author repository (mxgmn) with no visible CI/CD pipeline (.github/workflows absent; only FUNDING.yml present), increasing bus-factor risk. The algorithm can fail with contradictions that are NP-hard to avoid, meaning generation may fail unpredictably on certain inputs. No version pinning or dependency management beyond .csproj is evident, and the absence of visible recent commits suggests limited active support for bug fixes.

No active development is visible from the provided file list. The repository appears to be a stable, complete reference implementation. The presence of CITATION.cff suggests recent metadata updates for academic citation, but no pending PRs, issues, or milestones are evident from the available data.

git clone https://github.com/mxgmn/WaveFunctionCollapse.git
cd WaveFunctionCollapse
dotnet build WaveFunctionCollapse.csproj
dotnet run --project WaveFunctionCollapse.csproj

This builds and runs the program with configurations from samples.xml, reading input images from samples/ and writing outputs.

Daily commands:

dotnet run --project WaveFunctionCollapse.csproj

by default. Program reads samples.xml to determine which sample images to process and which parameters (N, symmetry, output dimensions) to use. Outputs generated images alongside the input samples.

• Model.cs — Abstract base class defining the core WFC algorithm interface that all generation models inherit from; essential for understanding the framework's architecture.
• OverlappingModel.cs — Implements pattern-based generation from arbitrary input bitmaps using overlapping tile extraction; the primary algorithm for most use cases.
• SimpleTiledModel.cs — Implements constraint-based generation using predefined tilesets with adjacency rules; handles structured tile-based output.
• Program.cs — Entry point orchestrating sample generation and configuration loading; shows how to instantiate and execute models.
• Helper.cs — Utility functions for image I/O, bitmap manipulation, and pattern analysis supporting both model types.
• samples.xml — Configuration file defining all test cases with model parameters, input/output paths, and generation constraints.

• Model.cs (abstract base) (C# abstract class, constraint logic) — Defines the WFC algorithm skeleton: observe(), propagate(), constraint checking, and backtracking strategy.
  • Failure mode: If propagate() fails to reduce entropy, generation backtracks; repeated failures cause complete failure.
• OverlappingModel.cs (Pattern hashing, superposition coefficients, entropy calculation) — Learns NxN patterns from input bitmap; manages superposition state per output pixel; applies frequency-preserving collapse.
  • Failure mode: If no valid NxN pattern matches a cell's neighbors, backtracking is triggered; if all attempts fail, generation aborts.
• SimpleTiledModel.cs (XML parsing, adjacency graph, constraint satisfaction) — Enforces tile adjacency constraints from XML definitions; selects valid neighbors per edge direction during propagation.
  • Failure mode: If tile compatibility rules are inconsistent or over-constrained, propagation leaves no valid states and generation fails.
• Helper.cs (Bitmap API, hash tables, numerical aggregation) — Image I/O, color quantization, pattern encoding/hashing, and superposition coefficient accumulation.
  • Failure mode: If input image cannot be loaded or output path is invalid, file I/O exceptions halt generation.
• Program.cs (XML deserialization, file I/O, command-line args) — Bootstrap: loads samples.xml, instantiates appropriate Model type, invokes generation loop, and coordinates output.
  • Failure mode: If samples.xml is malformed or sample paths are missing, initialization fails before any generation.

• samples.xml → Program.cs — Configuration parameters (model type, sample name, output dimensions, pattern size N, tile constraints)
• Input bitmap (samples/) → OverlappingModel.cs — RGB pixel data loaded by Helper.cs, then patterns extracted and stored as superposition coefficient maps
• Tileset XML (tilesets/*.xml) → SimpleTiledModel.cs — Tile names and adjacency rules parsed; tile image paths resolved to PNG files
• OverlappingModel.cs/SimpleTiledModel.cs → Model.cs (propagate loop) — Superposition state passed to constraint propagation; valid patterns/tiles returned after entropy reduction
• Model.cs (final superposition) → Helper.cs (SaveBitmap) — Output superposition coefficients collapsed to RGB colors and serialized to PNG

Add a new OverlappingModel sample

1. Place input bitmap in samples/ directory (e.g., samples/MyPattern.png) (samples/MyPattern.png)
2. Add <sample> element to samples.xml with model=OverlappingModel, specifying input path, output dimensions, and pattern size N (samples.xml)
3. Run Program.cs; Helper.cs will extract all NxN patterns and Model.cs will generate output respecting locality constraints (Program.cs)

Add a new SimpleTiledModel tileset

1. Create subdirectory under tilesets/ (e.g., tilesets/MyRuleset/) with individual tile PNG files (tilesets/MyRuleset)
2. Create XML file (e.g., tilesets/MyRuleset.xml) defining tiles and adjacency rules per edge (left/right/up/down) (tilesets/MyRuleset.xml)
3. Add <sample> element to samples.xml with model=SimpleTiledModel pointing to the new XML; SimpleTiledModel.cs will parse constraints and enforce them during generation (samples.xml)

Implement a custom Model variant

1. Create new class inheriting from Model.cs abstract base (Model.cs)
2. Override protected abstract methods: Clear(), IsValid(), Propagate(), and protected virtual Generate() (Model.cs)
3. Use Helper.cs utilities for image I/O and pattern encoding; add reference in Program.cs to instantiate and invoke Run() (Helper.cs)

• C# / .NET — Cross-platform desktop application with strong support for image processing; enables fast bitmap manipulation and constraint solving.
• Bitmap-based pattern extraction — Enables learning from a single example image without manual tiling; automatically discovers local patterns and frequencies.
• Entropy-based heuristic (lowest entropy first) — Greedy observation strategy that minimizes backtracking; prioritizes cells with fewest valid options to prune search space early.
• XML constraint definitions — Declarative tile adjacency rules; allows non-technical users to define tilesets without modifying code.

• Single-threaded constraint propagation loop

  • Why: Simplicity and predictability; avoids race conditions in superposition state updates.
  • Consequence: Large output dimensions or fine pattern sizes (N=4+) may be slow; GPU acceleration would be needed for real-time generation.

• Greedy lowest-entropy observation vs. global search

  • Why: Polynomial time complexity and fast iteration; good for medium-sized outputs (~100x100).
  • Consequence: May produce suboptimal patterns or fail to find valid solutions in highly constrained domains; backtracking required.

• Per-pixel superposition coefficients vs. discrete states

  • Why: Enables smooth probability weighting and distribution matching (Weak C2).
  • Consequence: Higher memory usage and slower propagation than discrete discrete-state implementations.

• Overlapping model extraction of all NxN patterns

  • Why: Automatic discovery from a single example; preserves both local structure and frequency distribution.
  • Consequence: Cannot handle patterns larger than input size; no control over pattern selection (all are included).

• Does not perform real quantum mechanics; uses real-valued superposition coefficients inspired by QM concepts.
• Does not support GPU acceleration; CPU-bound and suitable for offline generation only.
• Does not guarantee 100% success rate; may fail to find valid solutions in highly constrained scenarios requiring backtracking.
• Does not provide interactive editing during generation; purely offline batch processing.
• Does not support 3D generation in core library; examples show 3D in separate implementations.

• Unbounded backtracking without iteration limit (Medium) — Model.cs Generate() method: If propagate() consistently fails in highly constrained scenarios, generation may retry indefinitely; no explicit iteration cap or timeout.
• undefined: undefined

The algorithm can enter unrecoverable contradiction states during propagation, causing generation to fail silently or throw exceptions—no graceful retry mechanism is documented. Pattern size (N) must be tuned per-sample; too large wastes memory and finds no matches, too small loses semantic structure. The SimpleTiledModel requires manually-defined tile adjacency rules (not auto-detected), which are error-prone to configure. No explicit threading or parallelization despite O(WxH) per iteration; large output dimensions may block the UI. System.Drawing bitmap I/O is Windows-dependent (requires System.Drawing.Common NuGet on Linux/Mac).

• Constraint Propagation — The core mechanism in Model.Propagate() that enforces pattern validity across the grid after each observation; understanding this is critical to modifying generation behavior
• Shannon Entropy — Used to select which region to observe next (lowest-entropy heuristic in OverlappingModel); lower entropy means fewer valid pattern choices remain
• Superposition and Wave Function Collapse — Conceptual foundation: pixels/tiles exist in superposed states (multiple possibilities) until observed, then collapse to a single value; inspired by quantum mechanics but uses deterministic probability
• Pattern Frequency Distribution — OverlappingModel.cs learns the distribution of NxN patterns in the input (Weak C2 constraint); generation preserves this distribution to match input statistics
• Graph Coloring / Adjacency Constraints — SimpleTiledModel enforces that adjacent tiles must respect defined neighbor relationships; classic constraint satisfaction problem relevant to discrete tile-based generation
• Backtracking / Contradiction Detection — When propagation results in zero valid patterns for a cell, the algorithm has hit a contradiction (NP-hard to avoid in general); understanding why this occurs is key to tuning parameters
• Bitmap Sampling and Local Neighborhoods — OverlappingModel extracts all NxN windows from the input (with rotations/reflections); this neighborhood sampling is how semantic features are learned from a single example

• math-fehr/fast-wfc — High-performance C++ implementation of the same algorithm with optimizations for large-scale generation; reference for performance-critical ports
• ikarth/wfc_2019f — Python port of Wave Function Collapse with interactive visualizations; useful for comparing language implementations and educational purposes
• kchapelier/wavefunctioncollapse — JavaScript/WebGL port enabling browser-based procedural generation; complements the C# implementation for web workflows
• sjcasey21/wavefunctioncollapse — Java implementation used in game engines and cross-platform tools; reference for implementing within JVM ecosystems
• procedural-generation/tiled-map-generator — Related tile-based dungeon/map generation approaches using similar constraint satisfaction; ecosystem resource for procedural content creators

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for Model.cs constraint propagation logic

The core wave function collapse algorithm in Model.cs lacks test coverage. Testing the constraint propagation, entropy calculation, and observation steps would catch regressions and make the algorithm behavior explicit. This is critical since WFC's correctness depends on proper constraint handling across OverlappingModel.cs and SimpleTiledModel.cs.

• [ ] Create Tests/ directory with ModelTests.cs
• [ ] Add tests for Model.Propagate() method with various constraint scenarios
• [ ] Add tests for entropy calculation and lowest-entropy-heuristic selection
• [ ] Add tests for Model.Observe() with different observation strategies
• [ ] Add tests for both OverlappingModel and SimpleTiledModel subclasses
• [ ] Ensure tests verify behavior matches documented local similarity constraints (C1, C2)

Create GitHub Actions CI workflow for cross-platform builds

The repo has .github/FUNDING.yml but no CI workflow. WaveFunctionCollapse.csproj indicates this is a .NET project that should be tested on Windows, Linux, and macOS. A CI workflow would catch platform-specific issues early and ensure samples.xml configurations work across environments.

• [ ] Create .github/workflows/dotnet-build.yml workflow file
• [ ] Configure matrix build for windows-latest, ubuntu-latest, macos-latest
• [ ] Add steps to restore dependencies, build WaveFunctionCollapse.csproj, and run Program.cs against samples.xml
• [ ] Add workflow to run on push to main and pull requests
• [ ] Verify that sample image generation (samples/*.png outputs) works consistently

Document samples.xml configuration format and add schema validation

samples.xml drives all example outputs but has no documented schema or validation. The repo contains 40+ sample configurations but new contributors can't easily understand how to add new samples or tweak parameters (N, width, height, etc.). Adding schema documentation and optional XSD validation would reduce onboarding friction.

• [ ] Create samples-schema.md documenting samples.xml structure (sample element attributes, nested tile/symmetry elements)
• [ ] Create samples.xsd XML schema file for validation
• [ ] Update README.md with 'Configuration' section linking to samples-schema.md
• [ ] Add optional XML schema validation in Program.cs that warns on invalid samples.xml
• [ ] Document the difference between OverlappingModel (image-based) and SimpleTiledModel (tile-based) sample configurations

• Add unit tests for Model.Propagate() in OverlappingModel.cs with synthetic patterns (e.g., checkerboard input) to verify constraint propagation correctness and catch regression bugs; currently no test coverage exists.
• Document the samples.xml schema with inline comments and a dedicated SAMPLES_CONFIG.md file explaining N (pattern size), symmetry options, and output dimensions, since these parameters critically affect generation success but lack guidance.
• Implement a failure-recovery mechanism (e.g., automatic restart with randomness injection) when the algorithm hits a contradiction in Model.cs, rather than silently failing, to improve generation reliability for edge-case inputs.

The WaveFunctionCollapse codebase demonstrates a relatively secure posture for a desktop graphics generation application. No hardcoded secrets, SQL injection risks, or web-based vulnerabilities were identified. The primary security considerations relate to: (1) unverified dependency status due to missing package information, and (2) lack of documented input validation for image file processing, which could be a concern if processing untrusted images. The project appears to be a legitimate algorithmic tool without inherent security design flaws, though standard secure coding practices around input handling should be verified in the actual implementation code.

• Low · Missing dependency information — WaveFunctionCollapse.csproj. The project file (WaveFunctionCollapse.csproj) exists but no dependency/package list was provided for analysis. Cannot verify if NuGet packages have known vulnerabilities or if versions are pinned securely. Fix: Provide the full project file content and run 'dotnet list package --vulnerable' to identify vulnerable dependencies. Consider using a dependency scanning tool like OWASP Dependency-Check or Snyk.
• Low · No evidence of input validation on image files — Model.cs, OverlappingModel.cs, SimpleTiledModel.cs, Program.cs. The application processes bitmap and image files from samples and tilesets directories. While the codebase appears to be a generative tool, there is no visible evidence of input validation for malformed or malicious image files that could cause buffer overflows or other memory-based attacks. Fix: Implement input validation for all image file processing: verify file headers, validate dimensions, check file sizes before loading, and handle exceptions gracefully. Use safe image processing APIs.
• Low · No visible access controls or authentication — Program.cs. The application appears to be a desktop/console tool with no visible authentication, authorization, or access control mechanisms. If this were deployed as a service, it would be exposed to unauthorized usage. Fix: If deployed as a service, implement proper authentication and authorization. For desktop use, document trusted input sources. If exposed over network, add authentication layers.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/mxgmn/WaveFunctionCollapse shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live mxgmn/WaveFunctionCollapse repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mxgmn/WaveFunctionCollapse.

What it runs against: a local clone of mxgmn/WaveFunctionCollapse — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in mxgmn/WaveFunctionCollapse | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 79 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mxgmn/WaveFunctionCollapse. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mxgmn/WaveFunctionCollapse.git
#   cd WaveFunctionCollapse
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of mxgmn/WaveFunctionCollapse and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mxgmn/WaveFunctionCollapse(\\.git)?\\b" \\
  && ok "origin remote is mxgmn/WaveFunctionCollapse" \\
  || miss "origin remote is not mxgmn/WaveFunctionCollapse (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Model.cs" \\
  && ok "Model.cs" \\
  || miss "missing critical file: Model.cs"
test -f "OverlappingModel.cs" \\
  && ok "OverlappingModel.cs" \\
  || miss "missing critical file: OverlappingModel.cs"
test -f "SimpleTiledModel.cs" \\
  && ok "SimpleTiledModel.cs" \\
  || miss "missing critical file: SimpleTiledModel.cs"
test -f "Program.cs" \\
  && ok "Program.cs" \\
  || miss "missing critical file: Program.cs"
test -f "Helper.cs" \\
  && ok "Helper.cs" \\
  || miss "missing critical file: Helper.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 79 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~49d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/mxgmn/WaveFunctionCollapse"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.