DeBroglie Documentation

DeBroglie is a C# library that implements the Wave Function Collapse (WFC) algorithm. It is designed to generate new images or tilemaps that are locally similar to a sample bitmap or follow specific tile adjacency rules.

Key capabilities include:

• Overlapped model implementation: Supports the standard WFC approach.
• Non-local constraints: Allows you to specify global properties for the generated result beyond simple adjacency.
• Backtracking support: Unlike the original WFC algorithm which fails upon encountering a contradiction, DeBroglie can backtrack to resolve complex constraint sets.
• Multi-dimensional support: Works with 2D tiles, hexagonal tiles, and 3D voxels.

DeBroglie is a tool for generating tile-based maps using the Wave Function Collapse (WFC) algorithm. It provides precise control over the generation process and supports various topologies and constraints.

It is available in two primary forms:

1. C# Library: For direct control within Unity or .NET Core applications.
2. Command Line Program: For generating maps from JSON configuration files via an executable.

DeBroglie includes several advanced features for map generation:

• WFC Algorithm: Uses Wave Function Collapse to generate tile maps.
• Multi-topology Support: Supports 2D, 3D, and hexagonal generation.
• Path Constraints: Ability to generate constraints that ensure only connected paths are created.
• General Constraints: Supports many other types of generation constraints.
• Backtracking: Includes backtracking support to handle complex or difficult-to-generate setups.

The AdjacentModel constrains which tiles can be placed next to each other. It maintains a symmetric list of legal neighbors for every tile (e.g., if B can be above A, then A can be below B).

When to use:

• When tile relationships are very complex.
• When you are adding many other direct ITileConstraint requirements.
• When you want a "loose" generation that doesn't strictly follow the sample structure.

How it works: Adding a sample tilemap to the model automatically populates the legal adjacency lists based on the pairs found in that sample. You can also specify adjacent tile pairs directly.

Graph topologies are used for arbitrary data structures that do not follow a repeating grid pattern.

Implementation details:

• Adjacency: You must manually specify a complete list of neighbors for every cell.
• Coordinates: The x-axis corresponds directly to the cell index; other axes are unused.
• Model Requirement: Most standard models do not support graph topologies. You must use the GraphAdjacentModel instead of the standard AdjacentModel.
• Construction: For cases where cells correspond to the faces of a mesh, use the MeshTopologyBuilder utility to construct the topology.

When using an adjacent model without a sample input (e.g., using a file set), you must manually define which tiles can be next to each other using the adjacencies array.

Each entry defines permissible neighbors in specific directions using one of these formats:

• {"left": [...], "right": [...] } (X-axis)
• {"up": [...], "down": [...] } (Y-axis)
• {"above": [...], "below": [...] } (Z-axis)

Example: To allow tile A to be to the left of tile B:

"adjacencies": [
  { "left": ["TileA"], "right": ["TileB"] }
]

Hexagonal topologies use a "pointy side up" convention.

Behavioral notes:

• Coordinate System: The x-axis moves right, and the y-axis moves down and to the left. This results in rhombus-shaped output.
• Limitations: Periodic input/output is not supported for hexagonal topologies.
• Overlapping Model: When using the overlapping model, constraints are applied to n by n rhombus shapes instead of n by n rectangles.
• Integration: Since many tools lack native hexagon support, it is recommended to use the Tiled format. You can use the DeBroglie.Tiled library to convert between ITopoArray<T> objects and Tiled maps.

The OverlappingModel ensures that every n by n (or n by n by n in 3d) rectangle/cuboid in the output is a copy of a rectangle taken from the sample (including potential rotations or reflections).

When to use:

• When you need to accurately reproduce features like corners, lines, and junctions.
• When you want to generate rooms or pathways that resemble the sample structure.

Parameters:

• nx, ny, nz: The dimensions of the rectangle/cuboid. You can set a single value n to apply to all three dimensions.
• Note: Typically, n should be 2 or 3. Larger values significantly increase computation time and the likelihood of failing to find a valid result. This model requires at least one sample to function.

DeBroglie implements the WaveFunctionCollapse (WFC) algorithm as a constraint solver optimized for finding random solutions.

Key components include:

• Namespace: Core logic resides in DeBroglie.Wfc.
• Propagator: The default propagator is ArcConsistency4 (implemented in Ac4PatternModelConstraint). It maintains counts of valid patterns for every index/pattern/direction. When a count drops to 0, that pattern is marked impossible.
• Wave: The Wave class stores the domains (possible patterns) for each variable (cell).

DeBroglie uses the ITopology interface to handle different grid types (square, hex, or irregular). The topology treats the grid as a graph where:

• Each cell is represented by an integer index.
• Edges between nodes have direction labels that uniquely identify the exit edge from a cell.
• edgeLabel is used to control how tiles connect across edges.

This abstraction allows the core algorithm to remain agnostic of the specific grid geometry, enabling easy swapping of grid implementations.