Class WaveFunctionCollapse

java.lang.Object

com.github.yellowstonegames.grid.WaveFunctionCollapse

public class WaveFunctionCollapse
extends Object

A port of WaveFunctionCollapse by ExUtumno/mxgmn; takes a single sample of a grid to imitate and produces one or more grids of requested sizes that have a similar layout of cells to the sample. Samples are given as int[][] where an int is usually an index into an array, list, NumberedSet, or similar indexed collection of items (such as char values or colors) that would be used instead of an int directly. The original WaveFunctionCollapse code, here, used colors in bitmap images, but this uses 2D int arrays that can stand as substitutes for colors or chars.
Port of mxgmn's original C# repo.

Field Summary

Fields

Modifier and Type	Field	Description
com.github.tommyettinger.random.EnhancedRandom	random

Constructor Summary

Constructors

Constructor	Description
WaveFunctionCollapse(int[][] itemGrid, int order, int width, int height, com.github.tommyettinger.random.EnhancedRandom random)	Creates a WaveFunctionCollapse that will imitate the given itemGrid.
WaveFunctionCollapse(int[][] itemGrid, int order, int width, int height, com.github.tommyettinger.random.EnhancedRandom random, boolean periodicInput, boolean periodicOutput, int symmetry, int ground)	Creates a WaveFunctionCollapse that will imitate the given itemGrid.

Method Summary

Modifier and Type	Method	Description
int[][]	result()
boolean	run(int limit)	Try to actually generate a result, taking limit tries at most (0 or less for unlimited).
boolean	run(long seed, int limit)	Try to actually generate a result, taking limit tries at most (0 or less for unlimited).

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

random

public com.github.tommyettinger.random.EnhancedRandom random

Constructor Details

WaveFunctionCollapse

public WaveFunctionCollapse(int[][] itemGrid,
 int order,
 int width,
 int height,
 com.github.tommyettinger.random.EnhancedRandom random)

Creates a WaveFunctionCollapse that will imitate the given itemGrid. This will be able to produce 2D int arrays of size width by height, using the same content as present in itemGrid. The order should usually be 2 (low-quality), 3 (normal quality), or sometimes 4 (possibly-too-high quality); it determines how far away from a given cell in itemGrid to consider when placing that cell's value in a result. This acts as if periodicInput is true, making the top row to be considered adjacent to the bottom, and likewise for the left column and right column. This will not produce tiling output; to do that, use the larger constructor and pass true to periodicOutput. The symmetry value will be treated as 1, and ground as 0.

Parameters:

itemGrid - the initial data to imitate; this must not be empty

order - how far away from a cell to look when determining what value it should have; usually 2, 3, or 4

width - the width of the output 2D array to produce

height - the height of the output 2D array to produce

WaveFunctionCollapse

public WaveFunctionCollapse(int[][] itemGrid,
 int order,
 int width,
 int height,
 com.github.tommyettinger.random.EnhancedRandom random,
 boolean periodicInput,
 boolean periodicOutput,
 int symmetry,
 int ground)

Creates a WaveFunctionCollapse that will imitate the given itemGrid. This will be able to produce 2D int arrays of size width by height, using the same content as present in itemGrid. The order should usually be 2 (low-quality), 3 (normal quality), or sometimes 4 (possibly-too-high quality); it determines how far away from a given cell in itemGrid to consider when placing that cell's value in a result. You will probably want to try different values for periodicInput and periodicOutput. If periodicInput is true, then the top row is considered adjacent to the bottom, and likewise for the left column and right column. If periodicOutput is true, this will spend much more time trying to make all the edges match up so the result can tile seamlessly. The symmetry value will be clamped between 1 and 8, inclusive; if 1, only the tiles in their current state will be considered, but if it is greater, more and more reflections and rotations of areas in itemGrid will be considered. I don't really know what ground does, and it should probably be 0.

Parameters:

itemGrid - the initial data to imitate; this must not be empty

order - how far away from a cell to look when determining what value it should have; usually 2, 3, or 4

width - the width of the output 2D array to produce

height - the height of the output 2D array to produce

random - the EnhancedRandom number generator to use; will be referenced directly, not copied.

periodicInput - if true, itemGrid is treated as wrapping from edge to opposite edge

periodicOutput - if true, the output will tile if repeated; may make generation much more difficult

symmetry - the level of symmetry to consider when imitating areas; between 1 and 8, inclusive, but usually 1

ground - not sure what this does, to be honest; should usually be 0

Method Details

run

public boolean run(long seed,
 int limit)

Try to actually generate a result, taking limit tries at most (0 or less for unlimited). Returns true if a result was found successfully. The limit should usually be either 0 or a fairly high number (at least 100) if you want a result from this, though you can call this many times before it gets a successful result. This takes a seed as a long, but you are likely to get comparable results with run(int) if the state of random is deterministic before this is called.

Parameters:

seed - used with random, passed to EnhancedRandom.setSeed(long) before this starts attempts

limit - how many attempts to allow; may be 0 or less for unlimited attempts. A common idiom is: long seed = 1L; // can be any initial seed while (!wfc.run(seed++, 0)); // This tries until there is a success, which may never happen. int[][] resultGrid = wfc.result();

Returns:

true if this found a result successfully, or false if it did not

run

public boolean run(int limit)

Try to actually generate a result, taking limit tries at most (0 or less for unlimited). Returns true if a result was found successfully. The limit should usually be either 0 or a fairly high number (at least 100) if you want a result from this, though you can call this many times before it gets a successful result.

Parameters:

limit - how many attempts to allow; may be 0 or less for unlimited attempts. A common idiom is: while (!wfc.run(0)); // This tries until there is a success, which may never happen. int[][] resultGrid = wfc.result();

Returns:

true if this found a result successfully, or false if it did not

result

public int[][] result()