Quick start

Build your first Wave Function Collapse Assembly in Grasshopper in 9 steps. This guide walks through the minimum viable workflow: one Module, three Rules, and one solved Assembly. For the full component reference, see the main documentation.

How do I build my first Monoceros assembly?

Monoceros uses the Wave Function Collapse (WFC) algorithm to fill a spatial Envelope with discrete building blocks called Modules. You define the Modules, tell the Solver which Faces are allowed to touch (via Rules), and Monoceros does the rest. The following nine steps cover the entire workflow from installation to a finished Assembly.

1. Install

Install Monoceros from the Rhino Package Manager (_PackageManager command in Rhino) or download Monoceros3.gha, Monoceros3.Sdk.dll, and the monoceros_ffi library manually and place them in your Grasshopper Libraries folder.

Windows: for a manual install, place Monoceros3.gha, monoceros_ffi.dll, and Monoceros3.Sdk.dll in the Grasshopper Libraries folder. If the native Solver library is blocked, use the Unblock Files button in the Monoceros dialog to unblock monoceros_ffi.dll and Monoceros3.gha, or right-click those two files in Explorer, open Properties, and click Unblock if available. Restart Rhino afterwards.

macOS: open Terminal and run the following command to remove the macOS quarantine flag from the Monoceros files, regardless of where they were installed:

find ~/Library/Application\ Support/McNeel -name "monoceros_ffi.dylib" -exec xattr -d com.apple.quarantine {} \;

If monoceros_ffi.dylib is blocked, the WFC Solver reports Library blocked and opens a dialog. Follow its macOS options to allow the library in Privacy & Security, reveal it in Finder for Open, or copy the quarantine-removal command for the library and Monoceros3.gha.

Restart Rhino after installing. The Monoceros 3 tab appears in the Grasshopper ribbon.

2. Create a Grid

Drop a Homogeneous Grid component onto the canvas. Set Base Plane to World XY, Diagonal to a Vector for one Cell's dimensions (for example {1,1,1}), and X Count, Y Count, and Z Count to 5. The Cells output contains 125 cubic Cells. Envelope size is unlimited on every tier; the free-tier cap is on Solver runs (a limited number per fixed time window, aligned to UTC clock boundaries), not on Slots.

3. Define a Module

Drop a Construct Module component. Give it:

• A Module Name - e.g. "pipe" (or leave it empty for a generated name).
• Cells from your grid (one Cell for this single-Cell Module).
• Geometry - e.g. a simple cylinder that fits inside the Cell. The geometry is what Monoceros will place into each solved Slot.
• Rotational Freedom - leave it at None for this exercise.

This is your building block. A real project will have many Modules; for this quickstart one is enough to verify the pipeline.

4. Get Faces

Drop a Get Module Faces component and feed it your Module. Its six Direction outputs each list the external Faces in that Direction (+X, -X, +Y, -Y, +Z, -Z). Faces are the basis for adjacency Rules.

5. Create Rules

Drop a Construct Rules from Faces component. Connect the +X Face to Source Faces and the -X Face to Target Faces. Repeat for Y and Z, producing three Rules so the Module can tile with copies of itself in every Direction. Cross Match can stay at its default True.

Rules are the creative core of Monoceros - they determine which combinations are valid and which are forbidden. In larger projects you will use many Rules to encode complex design intent.

6. Build Slots

Drop a Construct Slot component. Feed it all Cells from your grid and the Module Name. This tells the Solver that every Cell in the Envelope could potentially contain your Module. The result is a list of Slots that forms the solving Envelope.

7. Construct Assembly

Drop the Construct Assembly component. Connect your Modules, Slots, and Allowed Rules. Indifference defaults to True; set it to False to stop uncovered Faces from pairing. The component packages everything into a Discrete Assembly.

8. Solve

Drop the WFC Solver component. Connect your Assembly. Set a Random Seed to any integer (e.g. 42). Wire a Boolean Toggle to the Run input and set it to True - the Solver only executes when Run is True, which prevents upstream slider changes from accidentally triggering solves. If the Solver succeeds, every Slot is now assigned exactly one Module. Changing the Seed produces a different valid arrangement.

On the Free tier, the component footer shows a live run counter indicating how many runs remain in the current window and when it resets. A solve may count toward the run limit when it starts, regardless of its outcome; invalid input and Run set to False do not start a solve. Paid tiers are unlimited.

If the Report starts with "WFC SOLVER FOUND A CONTRADICTORY SOLUTION." and Contradictory is True, check the Rules and Envelope. See the FAQ for troubleshooting.

9. Materialize

Drop the Materialize Assembly component. Connect a solved Assembly from the Solver's Assemblies list output to it. Geometry appears in the Rhino viewport - your first WFC Assembly. Each Slot now contains a correctly oriented copy of the assigned Module geometry.

Adding Connectors. The quickstart above uses explicit Rules. Monoceros 3 also supports Connectors (objects that combine interface identity - name and symmetry - with placement on a specific Module Face) and Connector Pairs (which Connector Names can connect). Feed Connectors and Connector Pairs into Construct Assembly alongside Modules, Slots, and Rules. The Assembly component generates all Module rotation variants, merges explicit Rules with Connector-generated Rules, and runs an internal Audit. See Example 2.3: The Assembly workflow and the Connectors FAQ for details.

What should I do after my first Monoceros assembly?

With the basic pipeline working, explore the rest of the Monoceros ecosystem:

• Full documentation - complete reference for all data types and 52 Grasshopper components.
• Strategies & example workflows - 8 workflow strategies and 36 step-by-step examples covering multi-Module assemblies, boundary handling, weighted solving, and more.
• FAQ & tips - answers to common questions on Solver failures, Module design, performance, and the free-tier run-rate cap (Limited number of solutions).

Questions? Reach out at info@monoceros.tools.