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/marian42/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.

WAIT — Stale — last commit 5y ago

• 3 active contributors
• MIT licensed
• ⚠ Stale — last commit 5y ago
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 98% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

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

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

What it runs against: a local clone of marian42/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 marian42/wavefunctioncollapse | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | 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 ≤ 1899 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of marian42/wavefunctioncollapse. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/marian42/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 marian42/wavefunctioncollapse and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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 "Assets/Code/WaveFunctionCollapse/InfiniteMap.cs" \\
  && ok "Assets/Code/WaveFunctionCollapse/InfiniteMap.cs" \\
  || miss "missing critical file: Assets/Code/WaveFunctionCollapse/InfiniteMap.cs"
test -f "Assets/Code/WaveFunctionCollapse/AbstractMap.cs" \\
  && ok "Assets/Code/WaveFunctionCollapse/AbstractMap.cs" \\
  || miss "missing critical file: Assets/Code/WaveFunctionCollapse/AbstractMap.cs"
test -f "Assets/Code/WaveFunctionCollapse/ModuleData.cs" \\
  && ok "Assets/Code/WaveFunctionCollapse/ModuleData.cs" \\
  || miss "missing critical file: Assets/Code/WaveFunctionCollapse/ModuleData.cs"
test -f "Assets/Code/GenerateMapNearPlayer.cs" \\
  && ok "Assets/Code/GenerateMapNearPlayer.cs" \\
  || miss "missing critical file: Assets/Code/GenerateMapNearPlayer.cs"
test -f "Assets/Code/Culling/Chunk.cs" \\
  && ok "Assets/Code/Culling/Chunk.cs" \\
  || miss "missing critical file: Assets/Code/Culling/Chunk.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 1899 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1869d)"
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/marian42/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).

An infinite, procedurally generated city engine built in C# / Unity that uses the Wave Function Collapse algorithm with backtracking to assemble modular blocks into coherent urban layouts. Players can walk, fly, or jetpack through unbounded procedurally-generated worlds without predefined boundaries, with the core innovation being constraint-satisfaction-based generation rather than noise or rule-based systems. Monolithic Unity project structure: Assets/Code/ is organized by concern (CameraControl/, Culling/, Trees/, Language/) rather than by module. Core generation lives in GenerateMapNearPlayer.cs and MapBehaviour.cs, which invoke WFC via ModulePrototype instances edited in the Prototypes scene. Culling system (Chunk.cs, OcclusionCulling.cs, Portal.cs) runs parallel to generation for performance. Utilities in Language/ (RingBuffer, QueueDictionary, Extensions) provide data structure helpers.

Game developers and procedural generation enthusiasts interested in implementing WFC for large-scale 3D environments, artists wanting to explore generative city design without coding, and students learning constraint-satisfaction algorithms applied to game world generation.

Actively maintained but feature-complete: the project is playable and published on Itch.io, with polished camera controls and culling systems. However, it is a creative/experimental project rather than a game engine—there is no gameplay loop, combat, or progression. The single-maintainer model (marian42) and lack of automated tests suggest it is a stable showcase project rather than production infrastructure.

Low risk for learning/experimentation but high risk for commercial reuse: single maintainer (marian42), no CI/CD visible, no automated test suite, and serialization explicitly disabled in editor workflows ('none of the components serialize'). Long dependency chains via Unity itself, and WFC backtracking can cause performance unpredictability in large regions. No formal versioning or changelog visible.

No recent commit information visible in provided data, but the README shows the project is stable and playable. Active development likely includes iteration on ModulePrototype definitions (edited via the Prototypes scene) and performance tuning via culling (DistanceCulling.cs, OcclusionCulling.cs). Tree generation (Trees/TreeGenerator.cs, TreePlacer.cs) is a secondary feature area.

Clone the repo: git clone https://github.com/marian42/wavefunctioncollapse.git. Open in Unity (version constraint unknown from provided data—check README or Assets for minimum version). Load the Game scene to play, or the Prototypes scene to edit modules. No external package manager setup needed beyond Unity's built-in asset pipeline.

Daily commands:

1. Open the project in Unity Editor. 2. Load Assets/Scenes/Game.cs (inferred from README). 3. Press Play in the Editor. 4. Use WASD to walk, Space to jump, Shift to run, Ctrl to jetpack. 5. Press M to toggle flight mode. For editor-only generation, select the Map object and use MapBehaviour component to initialize an NxN area.

• Assets/Code/WaveFunctionCollapse/InfiniteMap.cs — Core infinite procedural generation engine using WFC algorithm; every contributor must understand how tiles are collapsed and constrained
• Assets/Code/WaveFunctionCollapse/AbstractMap.cs — Base abstraction for WFC map generation defining the core collapse/backtracking logic that InfiniteMap and TilingMap inherit
• Assets/Code/WaveFunctionCollapse/ModuleData.cs — Central scriptable object storing all module prototypes, neighbor constraints, and connectors; edit this to change world generation
• Assets/Code/GenerateMapNearPlayer.cs — Entry point that triggers chunk generation as player moves; orchestrates the dynamic loading pipeline
• Assets/Code/Culling/Chunk.cs — Manages instantiated game objects for a spatial chunk; bridges generated tiles to rendering and occlusion culling
• Assets/Code/WaveFunctionCollapse/Slot.cs — Represents a single tile position in the grid with its possible module states and constraint satisfaction logic
• Assets/Code/CameraControl/FreeCameraController.cs — Main gameplay entry point handling player input and camera synchronization with the generation system

Add a new building block (module)

1. Create a 3D model mesh and assign a material in Assets/ (Assets/)
2. Open Assets/Prototypes.unity and place your block in the scene to see prototype setup (Assets/Prototypes.unity)
3. Create a ModulePrototype entry in the inspector for ModuleData.asset, assign mesh/material, set rotation modes, and define neighbor connectors (Assets/ModuleData.asset)
4. Define neighbor compatibility rules in the Module Prototype Editor by specifying which modules can connect on each side (Assets/Editor/ModulePrototypeEditor.cs)
5. Set spawn weight probability in ModuleData to control how often the block appears (Assets/Code/WaveFunctionCollapse/ModulePrototype.cs)
6. Test in Assets/Game.unity by walking around and observing generation (Assets/Game.unity)

Modify neighborhood constraints (e.g. 'only grass under buildings')

1. Open ModuleData asset and identify the modules needing constraints (Assets/ModuleData.asset)
2. Edit the ModulePrototype entry in the editor, navigate to its connector side rules (Assets/Editor/ModulePrototypeEditor.cs)
3. Set the neighbor module filter for each direction (north, south, east, west, up, down) to restrict valid adjacent modules (Assets/Code/WaveFunctionCollapse/BoundaryConstraint.cs)
4. Run AbstractMap.propagate() to validate constraints during generation; backtracking handles conflicts (Assets/Code/WaveFunctionCollapse/AbstractMap.cs)

Change the world size and generation behavior

1. Adjust chunk generation radius in GenerateMapNearPlayer.cs (how far from player chunks are queued) (Assets/Code/GenerateMapNearPlayer.cs)
2. Modify InfiniteMap initialization parameters to change grid resolution and seed behavior (Assets/Code/WaveFunctionCollapse/InfiniteMap.cs)
3. Tune distance culling thresholds in DistanceCulling to balance visual range vs performance (Assets/Code/Culling/DistanceCulling.cs)
4. Monitor performance in Assets/Game.unity and adjust spawn probability weights in ModuleData if generation is too slow (Assets/Code/WaveFunctionCollapse/ModuleData.cs)

Add occlusion culling to a building interior

1. Create a Room volume in the scene and assign it to a building module via Room.cs (Assets/Code/Culling/Room.cs)
2. Define Portal objects connecting adjacent rooms to indicate line-of-sight (Assets/Code/Culling/Portal.cs)
3. Enable OcclusionCulling and configure visibility graph to hide rooms not visible from player position (Assets/Code/Culling/OcclusionCulling.cs)
4. Test in Game.unity; occlusion should prevent rendering of indoor geometry when looking outside (Assets/Game.unity)

1. Serialization is explicitly disabled ('none of the components serialize'), so maps generated in Play mode cannot be saved or reloaded—initialization must happen in Play mode only. 2. ModuleData asset must be regenerated after editing Prototypes scene ('Click Create module data'); forgetting this step will cause old constraints to persist. 3. No constraint graph is visibly exported; understanding connector rules requires reading ModulePrototype inspector in the editor, not source code. 4. Backtracking in WFC can cause frame drops; no visible progress indication or timeout mechanism suggests potential for infinite loops on poorly-designed module sets. 5. Camera controller switching (ControlModeSwitcher.cs) suggests multiple input schemes exist, but no visible input remapping UI.

• Wave Function Collapse (WFC) — The core algorithm driving world generation; understanding WFC's constraint satisfaction and backtracking is essential to modify generation behavior and debug unsolvable module sets.
• Constraint Satisfaction Problem (CSP) — WFC is a CSP solver; understanding variable domains, constraint propagation, and search strategies helps diagnose generation bottlenecks and infinite loops.
• Spatial Coherence / Module Adjacency — Blocks are constrained by neighbor connectors; understanding adjacency rules is critical when editing ModulePrototype definitions and debugging implausible city layouts.
• Chunking and Spatial Partitioning — The Chunk.cs class divides the world into manageable units for generation and culling; understanding chunk boundaries affects LOD, memory, and generation scheduling.
• Occlusion Culling — OcclusionCulling.cs implements room/portal occlusion to avoid rendering invisible chunks; essential for performance in dense procedural cities.
• Streaming / Async Generation — GenerateMapNearPlayer.cs suggests asynchronous chunk generation around the player to avoid frame drops; understanding async/await or coroutines is key to avoiding stutter.
• Backtracking Search — WFC uses backtracking to resolve constraint conflicts; understanding backtracking depth, cost, and heuristics (like entropy-based tile selection) helps optimize generation speed.

• mxgmn/WaveFunctionCollapse — The canonical WFC algorithm reference implementation and research; this repo's direct inspiration and algorithm source.
• BorisTheBrave/DeBroglie — C# / .NET implementation of WFC with additional constraint systems; alternative algorithm reference for comparison and integration ideas.
• ajcr/Perlin-Noise-City-Generator — Another procedural city generator using different algorithm (Perlin noise + rule trees); shows complementary generative approach for urban layouts.
• Unity-Technologies/Megacity-Sample — Official Unity large-scale city rendering sample; relevant for learning culling, LOD, and streaming techniques similar to this project's CameraControl and Culling systems.
• keijiro/Pcx — Point cloud renderer for Unity; useful for visualizing or exporting the generated city structure as point data for analysis.

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 Wave Function Collapse core algorithm (Assets/Code/WaveFunctionCollapse/)

The WaveFunctionCollapse directory contains critical algorithm logic (AbstractMap.cs, InfiniteMap.cs, Module.cs, ModuleData.cs) but there are no visible test files. Given this is a complex procedural generation algorithm with backtracking, unit tests would catch regressions in collapse logic, constraint validation, and history management. This is especially important since the algorithm can fail (CollapseFailedException.cs exists) and needs reliable error handling.

• [ ] Create Assets/Tests/WaveFunctionCollapse/ directory structure
• [ ] Add tests for AbstractMap.cs covering tile placement and constraint propagation
• [ ] Add tests for InfiniteMap.cs covering infinite map edge cases and chunk boundaries
• [ ] Add tests for Module.cs and ModuleData.cs covering module compatibility and rotations
• [ ] Add tests for BoundaryConstraint.cs to verify edge constraint enforcement
• [ ] Test CollapseFailedException scenarios with backtracking logic

Add integration tests for procedural generation pipeline (Assets/Code/GenerateMapNearPlayer.cs + Assets/Code/MapBehaviour.cs)

The map generation system coordinates multiple systems (GenerateMapNearPlayer, MapBehaviour, DistanceCulling, OcclusionCulling) to create the infinite city. There are no visible test files validating that chunk generation, culling, and portal management work correctly together. Tests would ensure the generation pipeline doesn't create gaps, overlapping chunks, or culling artifacts.

• [ ] Create Assets/Tests/Integration/ directory for map generation tests
• [ ] Test GenerateMapNearPlayer.cs validates chunks are generated in correct radius around player
• [ ] Test MapBehaviour.cs properly initializes and manages the overall map state
• [ ] Test DistanceCulling.cs and OcclusionCulling.cs work together without rendering invisible chunks
• [ ] Test Portal.cs and Room.cs properly define boundaries for occlusion
• [ ] Validate no chunks are duplicated or have gaps in coverage

Refactor and document CameraControl system (Assets/Code/CameraControl/) with camera mode tests

The CameraControl directory has 4 different controller implementations (FirstPersonController, FlightController, FreeCameraController, ControlModeSwitcher) but no documentation on when to use each mode or tests validating they work correctly. The README mentions M-key for flight mode toggle but this behavior isn't documented in code. Add tests and documentation to clarify camera system behavior.

• [ ] Create Assets/Tests/CameraControl/ with unit tests for each controller class
• [ ] Test FirstPersonController.cs validates gravity, jumping, running mechanics
• [ ] Test FlightController.cs validates automatic flight mode behavior and movement
• [ ] Test FreeCameraController.cs validates unrestricted camera movement
• [ ] Test ControlModeSwitcher.cs validates switching between modes works smoothly
• [ ] Add XML documentation comments to each camera controller explaining use cases
• [ ] Create Assets/Documentation/CameraControls.md documenting control schemes and when each mode is used

• Add automated tests for the Wave Function Collapse solver logic in MapBehaviour.cs: currently no test files exist, and constraint satisfaction is error-prone. Start with a test that validates that adjacent blocks respect connector rules.
• Document the ModulePrototype format and connector rule syntax with code examples in README: the README instructs users to edit Prototypes scene visually but does not explain the data model or what 'connectors' and 'neighbor rules' mean programmatically.
• Implement a timeout / max-iteration guard in the WFC backtracking algorithm to prevent infinite loops on unsolvable module configurations: currently no visible safeguard, and RingBuffer.cs / QueueDictionary.cs suggest custom memory structures that could overflow.
• Add unit tests for the culling system (DistanceCulling.cs, OcclusionCulling.cs): no test files visible, and culling bugs can silently render the wrong chunks or cause memory leaks.
• Create a simple module set validator / linter tool that warns when a module set is likely to cause backtracking: currently users can edit Prototypes and only discover issues at runtime.

This is a Unity-based procedural generation game with no obvious critical security vulnerabilities in the analyzed file structure. The codebase is focused on game logic (WFC algorithm, rendering, camera controls) rather than network communication, data storage, or external integrations. No hardcoded credentials, database queries, or injection risks are apparent from the file names and structure. Main concerns are standard game development practices: dependency management tracking is missing, screenshot functionality should validate file paths, and editor code should be properly excluded from builds. The game appears to be single-player with no multiplayer or backend components visible, reducing attack surface significantly.

• Low · No dependency security information provided — Dependencies/Package file. The Dependencies/Package file content is empty, making it impossible to assess for known vulnerabilities in third-party packages. This could hide outdated or vulnerable dependencies. Fix: Provide package.json, packages.config, .csproj, or equivalent dependency manifest. Regularly audit dependencies using tools like NuGet audit (for C#), OWASP Dependency-Check, or Snyk.
• Low · Screenshot functionality without validation — Assets/Code/TakeScreenshot.cs. The TakeScreenshot.cs file suggests screenshot functionality. Without reviewing the code, there's potential for file path traversal or uncontrolled file writes if user input influences the output path. Fix: Implement strict validation on file paths. Use a whitelist of allowed directories, sanitize filenames, and avoid concatenating user input directly into file paths.
• Low · Editor scripts present in production codebase — Assets/Editor/ directory. Editor-only scripts are mixed with runtime code in the Assets directory. If the build process doesn't properly exclude editor code, editor functionality could be exposed in the shipped game. Fix: Ensure the build pipeline properly excludes Editor folder from builds using Unity's conditional compilation or explicit exclusion in build settings.

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

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

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