Quick Start Monoceros 3

Build your first Wave Function Collapse Assembly in Grasshopper in 9 steps. This guide walks through the minimum viable workflow: one Module, one Rule, 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 the .gha file manually and place it in your Grasshopper Libraries folder.

Windows: right-click the .gha file in Explorer, open Properties, and click Unblock.

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-wfc-*.dylib" -exec xattr -d com.apple.quarantine {} \;

If you see a macOS security warning saying a file named monoceros-Wfc-….dylib could not be opened, the native Solver library still has the quarantine flag. Open System Settings, go to Privacy & Security, and scroll down to the Security section. You will see a line saying the file was blocked, with an Allow Anyway button — click it. This only needs to be done once.

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

2. Create a Grid

Drop a Homogeneous Grid component onto the canvas. Connect a Plane (World XY), a diagonal Point (e.g. {5,5,5}), and grid counts (e.g. 5,5,5). This produces a regular 5 × 5 × 5 grid of cubic Slots - 125 cells in total. 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 Name - e.g. "pipe".
• A Grid Box from your grid (just one cell is enough for a 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.

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 Module Faces component and feed it your Module. It extracts the six Faces - one for each Axis Direction (+X, -X, +Y, -Y, +Z, -Z). Faces describe the interface on each Face and are the basis for adjacency Rules.

5. Create Rules

Drop a Construct Rules from Faces component. Connect matching Faces to both inputs. A Rule states that two specific Module Faces are allowed to be adjacent. For a single Module, connect the +X Face to the -X input (and likewise for Y and Z) so that the Module can tile with copies of itself in every Direction.

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 Grid Boxes 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 Rules. Enable the Indifference input if you want uncovered Faces to pair freely. 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. Each Solver invocation that produces a result counts as one run. Paid tiers are unlimited.

If the Solver reports "World state is Contradictory", your Rules are too restrictive for the given Envelope. See the FAQ for troubleshooting.

9. Materialize

Drop the Materialize Assembly component. Connect the Solver's Assembly output directly 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 46 Grasshopper components.
• Strategies & example workflows - 7 workflow strategies and 30 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.