mr-highball/wfc

wave function collapse algorithm

wfc

wave function collapse algorithm

Features

some features at a glance...

• 2D & 3D graph
• comfortable api to reshape and define constraints
• generic user defined values
• extendable classes if base behavior is not desired

Sample

Below is a sample which shows a possible use for wfc:

//easily define the shape (2D or 3D is supported)
LGraph := TGraph.Create.Reshape({width} 5, {height} 5, {depth} 1);

(*
  constraints are also very easy to add and the interface provide fluent setters.
  in this case A's & B's can be present in "any direction" on the graph (north, east, up, down, etc...)
*)
LGraph.AddValue('A')
  .NewRule(AllDirections, ['A', 'B']);

(*  
  but here, we constrain to just a few directions 
  A or B (N & S) of a "C"
*)
LGraph.AddValue('C')
  .NewRule([gdNorth, gdSouth], ['A', 'B']); 
  
(*
  when you're finished defining constraints and all of the
  possible values (states), then just run and the result can be 
  persisted or you can access the completed graph directly
*)
LGraph.Run();

How To Use

1. download and install lazarus if you don't already have it (http://www.lazarus-ide.org)
2. git clone this repo
   • some examples have submodule dependencies so if you want to clone this repo and bring in all of those do a git clone --recursive
   • if you already cloned you can update submodules with git submodule update --init --recursive
3. open wfc_test.lpr and attempt to compile/run (F9 Key)
   • this project shows some basic usage of the library
   • also, by going to Toolbar -> Project\Project Options\Paths you can copy the other units text to include in your own project
4. add .\src path to your project other units

Tip Jar

• 💵 BTC - bc1q55qh7xptfgkp087sfr5ppfkqe2jpaa59s8u2lz
• 💶 LTC - LPbvTsFDZ6EdaLRhsvwbxcSfeUv1eZWGP6

wfc's Issues

Add concept of "passes"

Add the concept of "passes" to tgraph. In essence allow new constraints to be applied to each value depending on the "pass" that we're on.
A "pass" should allow for interesting behavior that allows a unique set of constraints to be defined for a user defined label (ie. floor, furniture, decorations could be 3 unique passes when constructing a game world)

AC's

• SwitchToPass() method introduced
  • switches the graph to the requested pass label or initializes a new pass
  • dimensions will be the same as "first" pass
  • updates CurrentPass AND CurrentPassIndex property
• introduce CurrentPass property
  • handle when a caller sets the pass property (allow Read/Write)
• introduce TotalPassCount property (includes "first" pass)
• introduce CurrentPassIndex property
• introduce a ForEachPass() method that guarantees sequential iterating
  • does not affect current props
  • callback provides AGraph, APass, APassIndex
• when Reshape() is called needs to perform same behavior on first pass to all subsequent passes
• AddValue() to respect the current pass
• WrapNeighbors() to propagate to all subsequent passes when updated
• Planes property to respect current pass
• Run() should not "complete" until all passes have been "run"
  • empty passes (no constraints) should be copied from the "prior" pass
  • while running if the pass was changed to a different pass by selection callback, we need to keep track and update it back
• update Reset() to clear all passes as well

invalid state handling

currently the generation can result in "boards" with invalid states due to the way things are generated. need to troubleshoot and possible change up the traversal of neighbors (think this is due to skipping emptys or something, but just noting this so I don't forget)

3D demo with simple building kit

spawned from this reddit post. we'll see about handling the world generation along with attempting to get around the invalid states

image source

feature to 'explicitly' require a certain rule

when working to implement #3 it was clear that there wasn't a way to enforce the output of a graph to make sense when dealing with a complex rule set. for example, if certain elements (like a wall mid section) can only be present in between other components or directly beside something.

AC's

• when adding a rule, allow for an optional boolean parameter ARequireRule
  • default this parameter to False
• when ARequireRule is True the following should take place
  • rule added to the internal rules collection with this flag
  • TGraph.DoValidate() needs to be altered to handle the Required flag
    • when True Force the constraints of a rule with Required to be present
• when ARequireRule is False the default behavior for wfc should remain
  • rule added to the internal rules collection with this flag