Documentation Monoceros 3
Monoceros 3 is a Discrete Assembly plug-in for Grasshopper / Rhino by Ján Pernecký. It fills a spatial Envelope with discrete Modules according to user-defined Rules using the Wave Function Collapse algorithm. New to Monoceros? See the Quick Start guide.
Workflows
Workflow strategies and step-by-step example workflows.
FAQ & tips
Frequently asked questions, tips & tricks for common workflows and troubleshooting.
Use your AI agent
Get instant help from ChatGPT, Claude, Gemini, or any AI assistant using the official Monoceros documentation.
Join a workshop
Hands-on workshops covering Monoceros fundamentals, module design, and advanced workflows.
Bare minimum ↓ GH
The simplest possible Monoceros setup - one module, one rule, one solver call. Grasshopper file for download.
Puzzle ↓ GH
Interlocking puzzle-piece modules that can only connect one way. Grasshopper file for download.
Table of contents
- 1. Introduction
- 2. How is Monoceros structured?
- 3. What data types does Monoceros use?
- 4. What Grasshopper components does Monoceros provide?
- 5. Strategies & example workflows
- Vocabulary
1. Introduction
1.1 What is Monoceros
Monoceros is a legendary animal living in the huge mountains in the interior of India. It has the body of a horse, the head of a stag, the feet of an elephant and the tail of a boar.
Monoceros is also a suite of tools for optimally occupying an Envelope with discrete Modules, where the spatial relationship between those Modules can be constrained by a set of user-defined Rules. By using the Wave Function Collapse algorithm, it provides an innovative and fast solution to the emerging architectural problem of discrete aggregation for purposes of design, architecture and urban planning. Monoceros is a plug-in for Rhino / Grasshopper originally created at studio Subdigital by Ján Tóth and Ján Pernecký in 2021; Monoceros 3 is developed and maintained by Ján Pernecký.
Monoceros 3 introduces a significant set of capabilities over the original release:
- Weighted Observation and weighted Entropy - per-Module probability control lets the user bias the Solver toward or away from specific Modules in each Slot.
- Heterogeneous Slot dimensions - cells of different X, Y, Z sizes can coexist in the same Envelope, enabling mixed-scale assemblies.
- Automatic Module Rotations - the Module Rotations component generates up to 24 orientations per Module, with voxel-based deduplication to remove geometrically identical results.
- Voxel engine for Face suggestion - robust Face-matching even for complex or irregular geometry.
- Multi-solution output - multiple solve results from different Random Seeds can be collected in a single pass.
- Parallel solving - multiple Attempts run simultaneously on available CPU cores.
- Megamodule support - multi-cell Modules with auto-generated internal Rules, enabling larger design elements that span several Slots.
- Full Grasshopper integration - all Monoceros types cast to and from standard Grasshopper types, allowing direct connection to any GH component.
1.2 What is Wave Function Collapse
Wave Function Collapse (WFC) fills an entire spatial Envelope with Modules according to a set of adjacency Rules. The Envelope is divided into discrete, box-shaped Slots. Each Slot starts out with a list of all Modules that are allowed to occupy it. The algorithm progressively narrows those lists, Slot by Slot, until every Slot holds exactly one Module - and every pair of neighboring Modules is permitted by the Rules.
WFC is not a growth algorithm. It does not grow outward from a Seed or leave gaps behind. It always produces a result that fills the entire Envelope: either a complete, valid aggregate in which every Slot is occupied, or no solution at all. Because the algorithm operates simultaneously across the whole grid rather than expanding incrementally, the results are non-hierarchical - like a rhizome rather than a tree. There is no center, no branching structure, no preferred Direction of growth, no overlapping, and no untreated areas.
Monoceros is a loose implementation of the Wave Function Collapse algorithm originally developed for game design by Maxim Gumin and extended and promoted by Oskar Stålberg with his game Townscaper.
The algorithm
WFC proceeds in four phases:
- Canonicalization – Before the first Observation, the Solver runs an initial Propagation pass on the starting state. This removes any Module that is already impossible in a Slot given the initial allowed-Module lists and Rules, reducing every Slot to the tightest consistent set of possibilities. The result is the Canonical starting state. If any Slot reaches zero allowed Modules during Canonicalization, the setup is Contradictory and no solving is attempted.
- Observation – The Slot with the lowest Entropy - the fewest remaining allowed Modules, weighted by Module Weights - is selected and assigned a single Module chosen randomly according to those Weights, making it Deterministic. A Slot that has only one remaining allowed Module becomes Deterministic without randomness.
- Propagation – The newly fixed assignment is propagated outward through the grid. For each neighbor of the observed Slot, any Module that can no longer legally occupy that Slot - because the Rules no longer permit it next to the now-fixed neighbor - is removed from its allowed list. This removal can in turn force further removals in the neighbors’ neighbors, cascading recursively until the grid reaches a stable state with no further removals possible.
- Repeat – Steps 2 and 3 alternate until either all Slots are Deterministic (success) or a Slot reaches zero allowed Modules (a Contradictory state). On Contradiction the Solver retries with a different Random Seed, up to the configured Attempt limit.
1.3 What are the design principles of Monoceros 3?
Monoceros 3 is not a sequential update of Monoceros 1 but a redesigned tool built on three core principles:
- Less Monoceros, more Grasshopper - what can be done with vanilla Grasshopper should be. Monoceros data types connect directly to standard Grasshopper components and other plug-ins.
- The tool is not the workflow - no design strategy is enforced by the tool. Monoceros components combine freely with any Grasshopper workflow.
- Explicit by default - every decision is visible in the Grasshopper canvas.
These principles caused substantial changes from Monoceros 1. Monoceros 3 data types and components are not compatible with Monoceros 1.
1.4 How do I migrate from Monoceros 1?
Monoceros 3 is a substantial redesign, not a feature update. Data types and components are not compatible with Monoceros 1. The most impactful improvements for daily workflow are:
- Weighted Observation - each Module in each Slot can carry its own Weight. Higher Weight increases the probability of being chosen during Observation, enabling gradient effects, frequency control, and partial pre-determination - none of which were possible in Monoceros 1.
- Heterogeneous Slot dimensions - the Envelope can mix cells of different sizes in a single solve. Monoceros 1 required all cells to be identical. Mixed-scale assemblies are now straightforward.
- Module Rotations component - all distinct rotations of a Module are generated automatically with voxel-based deduplication. In Monoceros 1, every rotated variant had to be defined by hand - up to 24 separate Modules for a fully rotatable element.
- Multi-solution parallel solving - the Solver can run multiple Attempts simultaneously across all CPU cores and return a separate branch per solution. Exploring alternatives no longer requires re-running the definition manually.
- Voxel engine for Rule suggestion - Suggest Rules from Voxels matches Face layers by voxel pattern rather than raw geometry, making automatic Rule suggestion reliable even for complex or irregular Module Faces.
- Full Grasshopper type integration - all Monoceros types cast to and from standard Grasshopper geometry. A Slot casts to a Grid Box, Box, Brep, Point, or Plane. Monoceros components connect directly to standard GH tools without manual conversion steps.
- Indifference as an Assembly-level setting - the Indifference toggle on Construct Assembly replaces the Indifferent Rule from Monoceros 1. The effect is identical but the setup is cleaner and entirely explicit.
2. How is Monoceros structured?
2.1 What is the Monoceros workflow?
A typical Monoceros 3 workflow follows these steps:
- Define a Grid - Use the Homogeneous Grid or Heterogeneous Grid component to create Grid Boxes. A Grid Box carries only geometry - its size and position. A collection of Grid Boxes forms a grid. It is important to understand that Grid Boxes and Slots can be placed freely in world space; nothing enforces that they form a valid grid. Using the grid construction components guarantees a correct arrangement; any manually assembled or post-processed set of Grid Boxes must be carefully verified.
- Construct Modules - Define each Module with a name, a Grid Box (defining its cell size and pivot), and optional geometry. Generate rotation variants with the Module Rotations component if needed.
- Analyze Faces - Extract and inspect the six Faces of each Module. Use the Suggest Rules From Geometry or Suggest Rules from Voxels components to identify matching Face pairs.
- Define Rules - Create Rules specifying which Face pairs are allowed to touch. Each Rule connects a source Face to a target Face facing the opposite Direction.
- Construct Slots (Envelope) - Create Slots from Grid Boxes, optionally specifying which Modules are allowed in each Slot and their relative Weights. This step converts the Grid Boxes into an Envelope: Grid Boxes carry only geometry; Slots additionally carry the list of allowed Module candidates and per-Module Weights needed for solving. If the Allowed Module Names input is not connected, the Slot is created as allow-all and Construct Assembly will resolve it to the full final Module set - useful for the common case where every Slot accepts every Module.
- Add Boundary - Optionally add boundary Grid Boxes around the Envelope, convert them to boundary-specific Slots, and merge them with the interior Slots.
- Construct Assembly - Feed Modules, Slots, Rules, Connectors, and Connector Pairs into Construct Assembly. This expands rotation variants, generates Connector-based Rules, applies indifference, deduplicates, audits, and packages everything into a Discrete Assembly.
- Solve - Connect the Assembly to the WFC Solver. Assembly is the sole data input. The Solver returns an output Assembly with solved Slot states.
- Materialize - Connect the solved Assembly to the Materialize Assembly component to extract placed geometry.
2.2 Where are the Monoceros components in Grasshopper?
All Monoceros 3 components live in the Monoceros 3 tab in the Grasshopper ribbon. They are organized into six subcategories:
- Main - Construct Assembly, Deconstruct Assembly, WFC Solver, Materialize Assembly, Audit Assembly
- Grid - Grid creation, boundary, topology, geometry slicing
- Module - Module construction, deconstruction, rotations, deduplication, Megamodules
- Face - Face extraction, analysis, comparison, suggestion, preview
- Rule - Rule construction, deconstruction, filtering, suggestion, preview
- Slot - Slot construction, deconstruction, pattern finding
3. What data types does Monoceros use?
Monoceros 3 defines custom Grasshopper data types for all elements used in a WFC workflow. All Monoceros types can be passed through standard Grasshopper wires. Several support viewport preview and baking.
3.1 Grid
3.1.1 Grid Box
A Grid Box is the basic spatial cell unit of a Monoceros grid - a box-shaped region that defines the size and position of one cell. Multiple Grid Boxes form a grid; when converted to Slots via the Construct Slot component, they form an Envelope.
Grid Boxes are created by the Homogeneous Grid or Heterogeneous Grid components and can also be cast from standard Rhino Boxes, Rectangles, or Breps. A Grid Box exposes its Box geometry, from which center, dimensions, and Orientation can be derived.
Validity
A Grid Box is valid when its Box geometry is non-degenerate - all three dimensions greater than zero. Invalid Grid Boxes are rejected by all Monoceros components with a warning.
Viewport preview
Draws a wireframe representation of the Grid Box with short colored lines indicating
the +X, +Y, and +Z Directions at the center.
Casting
| From / To | Type | Notes |
|---|---|---|
| Cast from | Box |
A Rhino Box is wrapped directly into a Grid Box. |
| Cast from | BoundingBox |
A BoundingBox is wrapped directly into a Grid Box. |
| Cast from | Rectangle |
A Rectangle is extruded by one unit in Z to form a Grid Box. |
| Cast from | Brep |
The bounding box of the Brep is used as the Grid Box. |
| Cast to | Box |
Returns the Grid Box as Rhino Box geometry. |
| Cast to | Brep |
Returns the Grid Box as a closed Brep surface. |
| Cast to | Point |
Returns the center point of the Grid Box. |
| Cast to | Plane |
Returns the center plane of the Grid Box with its Orientation. |
| Cast to | Vector |
Returns the diagonal vector (X, Y, Z dimensions) of the Grid Box. |
String representation
Displays as a formatted string showing the box origin and dimensions, for example:
Grid Box at (0,0,0) 1×1×1.
Baking
Grid Boxes bake as Rhino Box geometry.
3.2 Module
3.2.1 Module
A Module is the fundamental design element in Monoceros 3. It
carries a name, the geometry of a discrete building element, and a Grid Box that
defines its cell size and pivot. Each Module has exactly six Faces - one per
Face, identified by Axis and Orientation: +X, -X,
+Y, -Y, +Z, -Z. These
Faces determine which neighboring Modules may legally be placed adjacent to it.
During WFC solving, each Slot starts with the full list of allowed Modules as candidates. The Solver progressively eliminates candidates - removing any Module from a Slot when its presence would violate a Rule with a neighboring Slot - until each Slot holds exactly one Module (Deterministic) or none (Contradictory). Selection is probabilistic and guided by the per-Module Weights stored in each Slot.
The Module’s geometry does not need to fit exactly inside the Grid Box - it can extend beyond or remain smaller. When geometry fits tightly and aligns with the Faces, Faces can be suggested automatically using the Suggest Rules From Geometry or Suggest Rules From Voxels components.
Key properties
- Module Name - A unique, lowercase string. Names are lowercased automatically on input. Multiple Modules sharing the same name are treated as variants (invariants) of the same Module type - useful in Heterogeneous Grids where the same Module Name must cover Slots of different sizes.
- Grid Box - The bounding box defining the Module’s cell size and pivot.
- Geometry - Optional Rhino geometry (curves, surfaces, Breps, meshes). Can exceed the bounding box.
- Faces - Six Faces, one per Face. Each is
identified by its Direction (
+X…-Z), which encodes the Face’s Axis (X, Y, or Z) and Orientation (positive or negative). Any Face that should participate in adjacency decisions must appear in at least one Rule. Faces without a Rule are treated as Indifferent when indifference is enabled on Construct Assembly. - Rotation flags - Record whether the Module was transformed. Construct Assembly expands flagged Modules into all implied rotational variants, remapping Face Directions accordingly. The expanded variants are available via Deconstruct Assembly.
Viewport preview
The Module preview draws:
- The Module geometry (wireframe for curves; shaded for Breps and Meshes).
- A semi-transparent wireframe outline of the bounding Grid Box (white if valid, red if invalid).
- Face dots at each Face center, colored by Axis:
X =
red, Y =
green,
Z = blue.
Dot text is white for
positive Directions (
+X,+Y,+Z) and black for negative (-X,-Y,-Z). - The Module name as a text label (with rotation suffixes when applicable).
Validity
A Module is valid when its name is non-empty and its Grid Box is valid. Modules with no geometry are allowed - they produce no output during materialization but participate fully in solving.
Casting
| From / To | Type | Notes |
|---|---|---|
| Cast from | (none) | Use the Construct Module component. |
| Cast to | Module Name |
Extracts the Module's name as a Module Name value. |
| Cast to | Grid Box |
Extracts the bounding Grid Box of the Module. |
| Cast to | Point |
Returns the center point of the Module's Grid Box. |
| Cast to | Plane |
Returns the center plane of the Module's Grid Box with its Orientation. |
| Cast to | Vector |
Returns the diagonal vector (X, Y, Z) of the Module's Grid Box. |
Baking
Modules bake as a group containing the geometry, Face rectangles, and Face text dots.
3.2.2 Module Name
A Module Name is a lowercase string identifier passed to the WFC Solver to represent a Module type. Input strings are converted to lowercase automatically.
Module Names are the unit of identity for the Solver. Two Modules with the same name are treated as variants (called invariants) of the same Module type. The Solver decides which Module “wins” a Slot by name; Materialize then picks the invariant whose dimensions match the Slot’s Grid Box. This is the mechanism used in Heterogeneous Grid setups: define several Modules sharing the same name but with different bounding-box sizes, and the Solver treats them as interchangeable - Materialize picks the one that physically fits.
Rules apply to all invariants simultaneously. A Rule defined for a name covers every size variant of that name. You write the Rule once; all invariants obey it.
Variant design contract. Sharing a name is a commitment that all size variants are functionally equivalent from the Solver’s point of view. If two size variants would need different connection Rules - for example, a long variant connects to a long neighbour but a short variant does not connect to a short neighbour - they must not share a name. Give them independent names and define separate Rules. See example 1.8 - The invariant design contract for a detailed worked example.
Validity
A Module Name is valid when it is non-empty and free of the reserved characters
: (colon), -> (arrow), @,
#, and newlines. Spaces are allowed.
Casting
| From / To | Type | Notes |
|---|---|---|
| Cast from | String |
The string is lowercased and used as the Module Name. |
| Cast from | Module |
Extracts the Module's name. |
| Cast from | Integer |
The integer is converted to a string and used as the Module Name. |
| Cast from | Number |
The number is converted to a string and used as the Module Name. |
| Cast from | Data Path |
The Data Path is converted to a string and used as the Module Name. |
| Cast to | String |
Returns the name string. |
String representation
Returns the name string, for example: wall or corner-piece.
Baking
Module Names are string values and do not bake directly.
3.3 Face
3.3.1 Face Index
A Face Index is an integer 0–5 that identifies one
of the six Face Directions of a Module or Grid Box. Each index maps to a named
Direction combining an Axis (X, Y, or Z) and an Orientation (positive or
negative). Opposite Faces always have indices that sum to 5
(+X 0 ↔ -X 3, etc.), which is how the
Solver checks that neighboring Faces Face each other correctly.
Face Indices appear as input to Rule-construction components such as
Get Module Faces and Construct Rules From Faces, and as part of
FaceId strings. When building Rules manually, the named form
(+X, -Y, etc.) is preferred over the numeric form
for readability.
| Index | Name | From / To | Opposite |
|---|---|---|---|
0 |
+X |
X Positive | -X (3) |
1 |
+Y |
Y Positive | -Y (4) |
2 |
+Z |
Z Positive | -Z (5) |
3 |
-X |
X Negative | +X (0) |
4 |
-Y |
Y Negative | +Y (1) |
5 |
-Z |
Z Negative | +Z (2) |
Casting
| From / To | Type | Notes |
|---|---|---|
| Cast from | Integer |
Integers 0–5 map directly to Faces. |
| Cast from | Number |
Numbers are truncated to integers 0–5. |
| Cast from | String |
Accepts numeric ("0") and named ("+X",
"-Y") formats.
|
| Cast to | Integer |
Returns the numeric index (0–5). |
Validity
Valid indices are integers 0 through 5. Strings in named form
(+X, -Y, etc.) are also accepted as input.
Baking
Face Indices do not bake directly.
3.3.2 Face (UID)
A Face uniquely identifies a specific Face on a specific Module. It combines a Module Name and a Face Index.
Properties
- Module Name - The name of the Module this Face belongs to.
- Face Index - The Face Direction as an integer
(0-5) or named form (
+X…-Z).
String representation
Format: modulename:+X. Both numeric and named indices are accepted.
Examples:
wall:+X
corner:3In Rules the format is:
wall:+X -> corner:-XValidity
A FaceId is valid when its Module Name is non-empty and its Face Index is in the range 0–5.
Casting
| From / To | Type | Notes |
|---|---|---|
| Cast from | String |
Parses the "modulename:faceindex" format. |
| Cast to | String |
Returns the FaceId string, e.g. wall:+X. |
Baking
Face UIDs do not bake directly. Use the Preview Faces component to visualize them in the viewport.
3.4 Slot
3.4.1 Slot
A Slot represents one cell in the Envelope. It holds the list of Module Names currently allowed to occupy it, along with a per-Module Weight for each candidate. The WFC Solver progressively reduces this list until each Slot holds exactly one Module (Deterministic) or none (Contradictory). Before solving, most Slots allow multiple Modules and are therefore Non-deterministic.
Key properties
- Box - The cell bounding box (same geometry as the Grid Box it was created from).
- Allowed Module Names - The list of Module Names still allowed in this Slot.
- Module Weights - One Number per allowed Module.
Higher Weight increases the probability of that Module being chosen during
Observation. Default Weight is
1.0. - Total Modules Count - Optional. The total number of distinct Module types in the system, used to compute the Entropy color gradient. When omitted (or zero), the gradient and Entropy label are not shown, but the Slot is fully valid for solving.
- Allows All - True when the Slot was constructed without explicit Module Names (empty allowed list and zero Total Modules Count). An allow-all Slot is neither Deterministic nor Contradictory; it is unresolved and will be filled with the full final Module set by Construct Assembly.
States
The Solver aims to make every Slot Deterministic. Slots can also become Deterministic before solving when their allowed list is restricted manually - for example by constructing a Slot with only one allowed Module Name.
| State | Allowed count | Preview color | Meaning |
|---|---|---|---|
| Contradictory | 0 | Red | No Module fits - this solve Attempt failed. The Solver will retry with a different Seed. |
| Deterministic | 1 | Green | Exactly one Module is assigned. The Slot is solved and can be materialized. |
| Non-deterministic | 2+ | Gradient from black (2 allowed) to white (all allowed) | Multiple Modules are still possible - not yet solved. |
| Allow-all | 0 (empty list, zero Total) | White | Unresolved: created without explicit Module Names. Construct
Assembly resolves it to the full final Module set. Previews
with the label All. |
Viewport preview
Draws a colored wireframe box. The wireframe is intentionally drawn slightly smaller than the actual cell box. Adjacent Slots share Faces, so if the boxes were drawn full-size their edges would coincide and overlap, making individual cells impossible to distinguish in the viewport. Shrinking each box inward by a small factor ensures there is always a visual gap between neighbors, even at zero distance. The actual solving geometry uses the full box.
String representation
Displays state and position, for example:
Slot [3 allowed] at (1,0,0),
Slot [deterministic: wall] at (2,1,0), or
Slot [All allowed] at (1,0,0) for allow-all Slots.
Casting
Slots automatically cast to Grid Box when passed to components that accept Grid Boxes (such as Add Boundary Layer). This means solved Slots can be used directly wherever Grid Boxes are expected.
| From / To | Type | Notes |
|---|---|---|
| Cast from | (none) | Use the Construct Slot component. |
| Cast to | Grid Box |
Returns the cell's Grid Box, enabling use wherever Grid Boxes are expected. |
| Cast to | Box |
Returns the Slot's cell as Rhino Box geometry. |
| Cast to | Brep |
Returns the Slot's cell as a closed Brep surface. |
| Cast to | Point |
Returns the center point of the Slot's cell. |
| Cast to | Plane |
Returns the center plane of the Slot's cell. |
| Cast to | Vector |
Returns the diagonal vector (X, Y, Z) of the Slot's cell. |
Baking
Slots bake as colored boxes reflecting their state.
3.5 Rule
3.5.1 Rule
A Rule defines an allowed adjacency between two Module Faces.
It holds two FaceIds - a source Face and a target Face - which
must Face opposite Directions (e.g. source Faces +X, target Faces
-X). Rules are bidirectional for equality:
wall:+X → corner:-X is equivalent to
corner:-X → wall:+X, so each adjacency only needs to be defined once.
Validity
Both FaceIds must be individually valid. The source and target Directions must be opposite. For full validation, the referenced Module Names must exist in the provided Module list.
String representation
Format: modulea:+X -> moduleb:-X
Casting
| From / To | Type | Notes |
|---|---|---|
| Cast from | String |
Parses the "module:index -> module:index" format. |
| Cast to | (none) |
Baking
Rules do not bake directly. Use the Preview Rule component to visualize them in the viewport.
3.6 Connector
3.6.1 Connector
A Connector is a named, rotation-aware interface that binds a type identity to a specific Module Face. Connectors emulate physical Connectors (USB-A, USB-C, 3.5 mm jack): two Faces can connect only when they carry compatible Connectors. Each Connector combines a name, four symmetry flags, a Module Name, a Face Direction, and an in-plane rotation into a single object. There is no separate type-definition step - all Connectors sharing the same name are implicitly the same type. The name carries the type identity.
The four symmetry flags define which of the four in-plane rotations (0°, 90°, 180°, 270°) are self-identical. When all four flags are true, the Connector is rotationally invariant (like a round jack). When only some flags are true, the Connector distinguishes certain rotations from each other, which affects how Rules are generated for rotated Module variants.
Key properties
- Name - A lowercase string identifying the
Connector type. All Connectors with the same name are the same type.
Must not contain
:,->, or@. Spaces are allowed. - Symmetry 0° - Self-identical at 0° rotation.
Default:
true. - Symmetry 90° - Self-identical at 90° rotation.
Default:
true. - Symmetry 180° - Self-identical at 180° rotation.
Default:
true. - Symmetry 270° - Self-identical at 270° rotation.
Default:
true. - Module Name - The name of the Module this Connector is placed on.
- Face Direction - The Face Direction as a Face Index
(
+X…-Z). - Rotation - In-plane rotation on the Face: 0, 90, 180, or 270 degrees.
String representation
Format: connectorName#rot-A@moduleName:faceIndex.
Deconstructs into Connector name, rotation, Module Name, and Face id.
Example: usba#rot-0@wall:+X.
Validity
A Connector is valid when its name is non-empty, contains no reserved characters
(:, ->, @, #),
at least one symmetry flag is true, the Module Name is valid, the Face Direction
is valid, and the rotation is one of 0, 90, 180, or 270.
Casting
| From / To | Type | Notes |
|---|---|---|
| Cast from | String |
Parses the "connectorName#rot-A@moduleName:faceIndex" format. |
| Cast to | (none) |
Preview & Baking
The Connector data type does not support viewport preview or baking on its own. The preview is provided by the producing component - Construct Connector, Suggest Connectors From Geometry, and Suggest Connectors from Voxels each draw Connector labels as stickers on Module Faces when Modules are connected to their inputs.
3.6.2 Connector Pair
A Connector Pair declares that two Connector types can connect
across opposing Faces. A Connector Pair stores two name strings (not references
to Connector objects). Compatibility is bidirectional: declaring
A → B also allows
B → A.
String representation
Format: sourcename -> targetname.
Example: usba -> usba.
Validity
A Connector Pair is valid when both its source name and target name are non-empty and contain no reserved characters.
Casting
| From / To | Type | Notes |
|---|---|---|
| Cast from | String |
Parses the "source -> target" format. |
| Cast to | (none) |
Baking
Connector Pairs do not bake directly.
3.6.3 Connector Name
A Connector Name is a lowercase string that identifies a Connector type. All Connectors sharing the same name are the same type. Input strings are converted to lowercase and trimmed automatically.
Validity
A Connector Name is valid when it is non-empty and free of the reserved
characters :, ->, @,
#, and newlines. Spaces are allowed.
Casting
| From / To | Type | Notes |
|---|---|---|
| Cast from | String |
The string is lowercased and trimmed. Fails if the result contains reserved characters. |
| Cast from | Connector |
Extracts the Connector's name. |
| Cast to | String |
Returns the name string. |
String representation
Returns the name string, for example: usba or rj45.
Baking
Connector Names are string values and do not bake directly.
3.7 Assembly
3.7.1 Assembly
A Discrete Assembly (or simply Assembly) is an opaque bundle that packages Modules, Slots, Rules, and an Audit report into a single container ready for the Solver. The Construct Assembly component creates an Assembly by expanding rotation variants, transforming Connectors, generating Rules from Connectors and Connector Pairs, applying indifference, merging and deduplicating all Rule sources, and running a full Audit. The result replaces the manual Module Rotations → Rule merging → Audit wiring pattern with a single component.
The Solver accepts an Assembly as an optional input. When connected, the Solver uses the Assembly's Modules, Slots, and Rules directly, skipping its own rotation expansion and indifference steps (which are assumed already applied). The Solver also produces an output Assembly containing the solved Slot states.
Key properties
- Modules - Expanded, deduplicated list of all Modules including rotation variants.
- Slots - Current Slot states (pre-solve or post-solve).
- Rules - Complete merged Rule set (explicit, Connector-generated, rotation-expanded, and optionally Indifferent).
- Audit Result - Comprehensive validation report including grid validity, uncovered Faces, unknown Modules, over-constraint detection, and more.
String representation
Format: Assembly (N modules, M slots, K rules).
Validity
An Assembly is valid when its Modules, Slots, Rules, and Audit Result are all non-null.
Casting
| From / To | Type | Notes |
|---|---|---|
| Cast from | (none) | Use the Construct Assembly component or the Solver's Assembly output. |
| Cast to | (none) |
Baking
Assemblies do not bake directly. Use the Deconstruct Assembly component to extract Modules, Slots, and Rules, or connect the Assembly to the Materialize Assembly component to produce geometry.
4. What Grasshopper components does Monoceros provide?
Monoceros 3 provides 53 active Grasshopper components organized into seven categories. Each component is documented below with its full input/output specification and behavior description.
4.1 Connector
Components for constructing Connectors, declaring Connector Pairs, and automatically suggesting Connectors from geometry or voxel patterns. The Connector system provides a higher-level abstraction over Face-based Rules: instead of defining individual adjacency Rules between specific Module Faces, you create Connectors (named, rotation-aware interfaces placed on Module Faces) and declare which Connector names are compatible via Connector Pairs. The Construct Assembly component then generates all the corresponding Rules automatically, including correct handling of rotation variants and symmetry.
4.1.1 Connector from Point
Create Connectors by pointing at a Module Face in the viewport. Combines Face-from-Point lookup with Connector construction: looks up every Module Face whose geometry contains the provided point and produces one Connector per match. Useful when authoring Connectors by clicking on Module Faces directly in the Rhino viewport. 8 inputs total.
Behavior
Resolves the Point Tag into one or more Module Faces using the same point-in-Face matching logic as Faces from Point, then constructs a Connector for each matching Face using the same name, rotation and symmetry inputs as Connector from Face. Zero matches raise a Warning (“Point does not match any Module Face.”); multiple matches emit an informational Remark listing how many Connectors were created. Viewport preview draws the Connector sticker on every matched Face, identically to Connector From Face.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Connector Name | CN |
Connector Name | Item | Connector type name. Case-insensitive. Must not contain
:, ->, or
@. Spaces are allowed. |
| Modules | M |
Module | List | All Modules to search for a Face hit at the Point Tag. Provide a flattened list. |
| Point Tag | Pt |
Point3d | Item | Point marking a location on a Module Face. One Connector is produced per Face whose geometry contains this point. |
| Face Rotation | R |
Integer | Item | In-plane rotation of the Connector on each matched Face.
Integer 0–3 representing 0°, 90°,
180°, 270° respectively. Also accepts
90, 180, 270 directly. Right-click for presets.
Default: 0. |
| Symmetry 0° | S0 |
Boolean | Item | Self-identical at 0° rotation.
Default: true. |
| Symmetry 90° | S90 |
Boolean | Item | Self-identical at 90° rotation.
Default: true. |
| Symmetry 180° | S180 |
Boolean | Item | Self-identical at 180° rotation.
Default: true. |
| Symmetry 270° | S270 |
Boolean | Item | Self-identical at 270° rotation.
Default: true. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Connectors | C |
List (flattened) | List | One Connector per matched Face. If the Point marks multiple Faces (for example, overlapping Modules), each match produces its own Connector. Output is flattened by default so all matches across tree branches land in a single list ready to feed into Construct Assembly. |
See also: 4.1.2 Connector from Face, 4.3.4 Faces from Point.
4.1.2 Connector from Face
Create Monoceros 3 Connectors from Faces - named, rotation-aware interfaces placed on specific Module Faces. Combines type identity (name + symmetry) and placement (FaceId + rotation) in a single object. All Connectors sharing the same name are implicitly the same type. A Module wired directly into the Face input is cast to a short-lived wildcard FaceId that the component expands into the Module's six explicit Faces, producing one Connector per Face. Output is flattened. 8 inputs total. For point-based placement, use Connector from Point.
Behavior
Validates the Connector name (must be non-empty, no reserved characters), the symmetry flags (at least one must be true), the Module Name, Face Direction, and Rotation. The name is lowercased automatically. A Connector with all four symmetry flags set to true behaves identically at every rotation - Rules generated for it do not distinguish Orientation. A Connector with selective flags (e.g. only 0° and 180°) produces different Rules for different in-plane orientations, enabling Direction-sensitive connections. When the optional Modules input is connected, the component draws a viewport preview showing the Connector as a label sticker on the target Face - displaying the Connector name and symmetry arrows in the Connector’s type color, with degree labels (0°, 90°, 180°, 270°) indicating the in-plane rotation.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Connector Name | CN |
Connector Name | Item | Connector type name. Case-insensitive. Must not contain
:, ->, or
@. Spaces are allowed. |
| Face | F |
FaceId | List | FaceId from the Module Faces component, identifying the Module and Face Direction. A Module may be wired here directly - it is expanded to all six of its Faces. |
| Face Rotation | R |
Integer | Item | In-plane rotation of the Connector on this Face.
Integer 0-3 representing 0°, 90°,
180°, 270° respectively. Also accepts
90, 180, 270 directly. Right-click for presets.
Default: 0. |
| Symmetry 0° | S0 |
Boolean | Item | Self-identical at 0° rotation.
Default: true. |
| Symmetry 90° | S90 |
Boolean | Item | Self-identical at 90° rotation.
Default: true. |
| Symmetry 180° | S180 |
Boolean | Item | Self-identical at 180° rotation.
Default: true. |
| Symmetry 270° | S270 |
Boolean | Item | Self-identical at 270° rotation.
Default: true. |
| All Modules | M |
Module | List | Optional. Modules for viewport preview. When connected, the Connector is displayed as a sticker on the target Face. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Connector | C |
Connector | List | The constructed Monoceros 3 Connectors (flattened). |
See also: 4.1.1 Connector from Point, 4.3.4 Faces from Point.
4.1.3 Construct Connector Pair
Declare which Connector types can connect across opposing Faces. Takes single items: Source Connector (item) + Target Connector (item) produces one Connector Pair (item). Compatibility is bidirectional - declaring A → B also allows B → A. Use Grasshopper’s cross-reference component to make multiple pairs from lists.
Behavior
Takes one Source Connector and one Target Connector, extracts their names, and produces a single Connector Pair object. To generate multiple pairs, use Grasshopper’s Cross Reference component on the inputs.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Source Connector | SC |
Connector | Item | Connector on the source side. |
| Target Connector | TC |
Connector | Item | Connector on the target side. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Connector Pair | CP |
Connector Pair | Item | One declared compatible Connector name pair. |
4.1.4 Deconstruct Connector
Deconstruct a Connector into its constituent parts: Connector name, rotation, Module Name, and Face id. The inverse of Connector from Face.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Connector | C |
Connector | Item | The Connector to deconstruct. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Connector Name | CN |
Connector Name | Item | The Connector type name. |
| Rotation | R |
Integer | Item | The in-plane rotation in degrees (0, 90, 180, or 270). |
| Module Name | MN |
Module Name | Item | The name of the Module this Connector is placed on. |
| Face | F |
Face | Item | The Face identifier (Module Name and Face Index). |
4.1.5 Construct Terminator
Create Terminators — boundary-facing markers placed on Module Faces. A Terminator declares that a specific Module Face is allowed to sit against the Envelope boundary when Require Terminators is enabled on Construct Assembly. For point-based placement, use Terminator from Point.
Behavior
The Face or Module input accepts either a Face (from the Get Module Faces component) or a whole Module. When a Module is wired, the component expands it into all six of its Faces and produces one Terminator per Face; a Remark reports how many were produced. This is the fastest way to mark an entire Module as fully boundary-compatible.
Terminators do nothing unless Require Terminators is enabled on Construct Assembly. When it is, Construct Assembly synthesizes a one-cell-thick boundary layer and links each Terminator-marked Face to it. Module Faces without a Terminator cannot touch the outer edge of the Envelope; if the Solver is forced to place such a Face against the boundary, the Assembly will contradict.
The optional All Modules input provides Modules for viewport preview. When connected, a terminator badge — a smooth circle with an inner × — is drawn on each target Face in the viewport.
String representation
Format: Terminator@moduleName:faceIndex.
Example: Terminator@pipe:+X.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Face or Module | F |
Face / Module | List | Face where the Terminator is placed (from Get Module Faces), or a Module (expanded into all six of its Faces, producing one Terminator per Face). |
| All Modules | M |
Module | List | Optional. Modules for viewport preview. When connected, the terminator badge is displayed on each target Face. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Terminator | T |
Terminator | List | Constructed Terminators (flattened). One per input Face; one per Face of each input Module. |
4.1.6 Terminator from Point
Create Terminators from a point tag. Looks up every Module Face whose geometry contains the provided point and creates a Terminator for each matching Face in one step. Useful for authoring Terminators by clicking on Module Faces in the Rhino viewport. For Face-based placement, use Construct Terminator.
Behavior
Uses the same point-in-Face matching as Faces from Point: the component tests every Face in every Module, checking whether the tagged point falls within the Face’s geometry. A Face matches if the point is within its boundary.
Zero matches raise a Warning and produce no Terminators. Multiple matches (e.g. two Modules whose geometries overlap at the point location) emit an informational Remark and produce one Terminator per match. Output is flattened.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Modules | M |
Module | List | All available Modules to search for a Face hit. Provide a flattened list. |
| Point Tag | Pt |
Point | Item | Point marking a location on a Module Face. The component returns one Terminator per Module Face whose geometry contains the point. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Terminators | T |
Terminator | List | One Terminator per matched Face. If the Point marks multiple Faces (e.g. overlapping Modules), each match produces its own Terminator. |
4.1.7 Suggest Connectors from Geometry
Given an exemplar Connector, find all geometrically matching Faces across all Modules and output Connectors with detected rotation offsets. Uses the same naked-edge / curve-endpoint / point extraction as Suggest Rules From Geometry but additionally detects the in-plane rotation offset between each match and the exemplar.
Behavior
Extracts Face geometry for every Module Face, transforms to a normalized base plane, and compares against the exemplar Connector's Face. For each match, the component tests all four 90° rotations of the geometry pattern to detect the rotation offset. The output is a list of Connectors covering all matching Faces (including the exemplar itself), each with the correct rotation. The exemplar Connector's name and symmetry flags are inherited by all output Connectors. The component draws a viewport preview showing all detected Connectors as stickers on Module Faces (name label and symmetry arrows in the Connector’s type color, with degree labels).
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Exemplar Connector | C |
Connector | Item | The Connector used as a reference for matching. Its name, symmetry flags, Module, Face, and rotation define the exemplar. |
| Modules | M |
Module | List | All Modules to search. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Connectors | C |
Connector | List | All matched Connectors with detected rotations. |
| Match Count | MC |
Integer | Item | Number of Faces matched (including the exemplar). |
4.1.8 Suggest Connectors from Voxels
Given an exemplar Connector, find all voxel-pattern-matching Faces across all Modules and output Connectors with detected rotation offsets. Uses voxelized geometry for more robust matching on complex surfaces.
Behavior
Voxelizes all Modules at the specified resolution, extracts Face voxel layers at configurable depth, and compares against the exemplar Connector's Face voxel pattern. Tests all four 90° rotations of each candidate pattern to detect the rotation offset. The exemplar itself is always included in the output. The exemplar Connector's name and symmetry flags are inherited by all output Connectors. The component draws a viewport preview showing all detected Connectors as stickers on Module Faces (white name label and symmetry dots).
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Exemplar Connector | C |
Connector | Item | The Connector used as a reference for matching. Its name, symmetry flags, Module, Face, and rotation define the exemplar. |
| Modules | M |
Module | List | All Modules to search. |
| Voxel Resolution | V |
Vector3d | Item | Number of voxels in each Direction of the Module Grid Box.
Default: 16×16×16. |
| Scanning Depth | D |
Interval | Item | Relative depth interval (0.0-1.0) for voxel layer scanning.
Default: 0-0. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Connectors | C |
Connector | List | All matched Connectors with detected rotations. |
| Match Count | MC |
Integer | Item | Number of Faces matched (including the exemplar). |
4.2 Envelope
Components for constructing and inspecting Grid Boxes - the individual cells that form the spatial foundation of a WFC setup. A grid consists of Grid Boxes, which carry only geometry (size and position). A grid becomes an Envelope once the Grid Boxes are converted to Slots via the Construct Slot component. Slots additionally carry the list of allowed Module candidates and per-Module Weights needed for solving.
4.2.1 Heterogeneous Grid
Generate a grid where cells along each Axis can have different sizes. Each Axis receives an independent list of dimension values; the component creates all combinations. For example, three X sizes, four Y sizes, and two Z sizes produce 3×4×2 = 24 Grid Boxes, each with dimensions determined by its position along each Axis. The homogeneity of the Homogeneous Grid means all cells are identical; here, each column, row, or layer has a distinct dimension while all cells within the same column, row, or layer share that Axis value.
Behavior
Cells are placed with cumulative offsets along each Axis, so each cell starts exactly where the previous one ends. The resulting Grid Boxes can have different sizes in one, two, or all three dimensions.
What makes a grid Heterogeneous. The grid is only Heterogeneous when the size lists contain more than one distinct value along at least one Axis, so that neighbouring Slots end up with different dimensions. If all three lists contain a single repeated value, the result is identical to Homogeneous Grid. A grid is not Heterogeneous merely because its cells are non-cubic - a Homogeneous Grid with Diagonal (2, 1, 3) already has rectangular cells; every cell is still the same size.
A practical way to create varied-size input lists is the Grasshopper Gene Pool component for interactively dragging individual values and seeing the resulting grid update in real time.
For the Heterogeneous Grid to work with WFC, Module invariants are required
whose dimensions match the different cell sizes. For example, if X sizes are
[1, 2], you need at least one Module with X = 1 and
one with X = 2, both sharing the same Module Name. Rules are
defined once per name and apply to every dimensional invariant of that name.
Variant design contract. Sharing a Module Name across different sizes asserts that all size variants are functionally equivalent: the Solver will allow any invariant in any position where the name fits, regardless of which size ends up there. If the connection geometry or logic differs between sizes, the two variants should have separate names and separate Rules. See example 1.8 - The invariant design contract for a detailed worked example.
The output is a flat list of Grid Boxes. Flatten the output when passing it to the Construct Slot component.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Base Plane | P |
Plane | Item | The plane whose origin is placed at the center of the first Grid Box
(grid coordinate 0,0,0). Cells grow in the plane's X, Y, and Z Axis
Directions. Default: World XY. |
| X Sizes | X |
Number | List | Width of each column of cells along the X Axis. One value = one column at that width. All values must be greater than zero. |
| Y Sizes | Y |
Number | List | Depth of each row of cells along the Y Axis. All values must be greater than zero. |
| Z Sizes | Z |
Number | List | Height of each layer of cells along the Z Axis. All values must be greater than zero. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Grid Boxes | B |
Grid Box | List | Variable-sized Grid Box instances as a data tree, flattened by the component. Connect directly to Construct Slot. |
See also workflows and FAQs: 2.8 Heterogeneous grid, 2.25 Rectangular (non-square) Modules.
4.2.2 Homogeneous Grid
Generate a regular Envelope made of uniform cells. All cells share the same X, Y and Z dimensions, arranged in a cuboid block. This is the most common starting point for a WFC setup.
Behavior
Creates a 3D array of identically-sized Grid Boxes, aligned to the given base plane. Each individual cell can have different X, Y, and Z dimensions; the homogeneity means all cells in the grid share exactly those same dimensions. A single-cell grid (X Count = Y Count = Z Count = 1) is valid and can be used for any purpose that requires an isolated cell.
Non-cubic is not Heterogeneous. Setting the Diagonal to
(2, 1, 3) produces rectangular cells, but every cell in the
grid is still identical - the grid is still Homogeneous. You still
need only one Module size. Use Heterogeneous Grid only when you need
neighbouring Slots to have different sizes from each
other. Although cells do not need to be cubic, cubic cells
(X = Y = Z) are strongly recommended: non-cubic cells
constrain which Modules fit which Slots and can make the setup harder to
manage.
The output is a data tree of Grid Boxes, flattened by the component, in row-major order (X changes fastest, then Y, then Z). Connect directly to the Construct Slot component.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Base Plane | P |
Plane | Item | The plane whose origin is placed at the center of the first Grid Box
(grid coordinate 0,0,0). Cells grow in the plane's X, Y, and Z Axis
Directions. Default: World XY. |
| Diagonal | D |
Vector | Item | Cell size along X, Y, and Z
Axes. Default: (1, 1, 1). All three values
must be greater than zero.
|
| X Count | X |
Integer | Item | Number of cells along X. Default: 1. |
| Y Count | Y |
Integer | Item | Number of cells along Y. Default: 1. |
| Z Count | Z |
Integer | Item | Number of cells along Z. Default: 1. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Grid Boxes | B |
Grid Box | List | Grid Box instances as a data tree, flattened by the component. Connect directly to Construct Slot. |
See also workflows and FAQs: 2.1 Bare minimum, 2.4 Rotating the envelope base plane, 1.1 Top-down: envelope first.
4.2.3 Add Boundary Layer
Surround an existing Grid or Envelope with one or more additional layers of Grid Boxes. Use this to control what appears at the outer edges of the Envelope - for example, to ensure open or closed boundary conditions, or to add a ring of dedicated “cap” Modules that frame the interior.
Behavior
Generates new Grid Boxes that are adjacent to - but not part of - the input Envelope. The component outputs only the new boundary cells, not the original ones. The boundary Grid Boxes are typically converted to a separate set of Slots (using Construct Slot with different Module allowances than the interior), and only then merged with the interior Slots before passing all Slots to the WFC Solver.
You can restrict which Faces of the Envelope get a boundary layer using the
six directional toggles. For example, disable Z+ to leave the top
of the Envelope open. When working with non-rectangular Envelopes, the boundary
generation correctly follows the actual outer Face of the shape.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Grid Boxes | B |
Grid Box | List | All Grid Box objects that form the inner Envelope to surround. |
| Diagonal Neighbors | D |
Boolean | Item | When true, also fill corner-diagonal positions.
Default: false. |
| Layers | L |
Integer | Item | Number of boundary layers to generate. Default: 1. |
| Include X+ | X |
Boolean | Item | Add boundary on the +X Face. Default: true.
|
| Include Y+ | Y |
Boolean | Item | Add boundary on the +Y Face. Default: true.
|
| Include Z+ | Z |
Boolean | Item | Add boundary on the +Z Face. Default: true.
|
| Include X- | X |
Boolean | Item | Add boundary on the -X Face. Default: true.
|
| Include Y- | Y |
Boolean | Item | Add boundary on the -Y Face. Default: true.
|
| Include Z- | Z |
Boolean | Item | Add boundary on the -Z Face. Default: true.
|
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Boundary Layer Boxes | B |
Grid Box | List | Newly generated boundary Grid Boxes only - the original Grid Boxes are not included. Convert these to boundary Slots (typically with restricted Module allowances) and merge the resulting Slots with the interior Slots before passing all Slots to the WFC Solver. |
See also workflows and FAQs: 2.10 Boundary handling, 2.11 Constructing Slots from geometry, FAQ 1.7 How do I handle boundaries?.
4.2.4 Are Grid Boxes Boundary
Identify which Grid Boxes in an Envelope sit on its outer boundary. Returns a
boolean per input box - true if the box is within the
specified number of layers from the outer edge. Use this to separate boundary
cells from interior cells to treat them differently - assign dedicated
boundary Modules, restrict allowed candidates, or simply visualize the
distinction.
Behavior
The component scans the Envelope from the outside inward. Any Grid Box that
has fewer occupied neighbors than expected in the enabled Axes is considered a
boundary box. With Layers set to 1, only the
outermost ring is flagged. With 2, the two outermost rings are
flagged, and so on.
The output boolean list matches the input list order one-to-one. A convenient workflow is to feed the boolean pattern into a Dispatch component to split the Grid Boxes (or their resulting Slots) into boundary and interior groups, then apply different constraints to each.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Grid Boxes | B |
Grid Box | List | All Grid Box objects to test for boundary membership. |
| Layers | L |
Integer | Item | Number of outer layers to mark as boundary. Default:
1.
|
| Include X | X |
Boolean | Item | Check for boundary along the X Axis. Default: true. |
| Include Y | Y |
Boolean | Item | Check for boundary along the Y Axis. Default: true. |
| Include Z | Z |
Boolean | Item | Check for boundary along the Z Axis. Default: true. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Boolean Pattern | B |
Boolean | List | true for each Grid Box that falls within the specified
boundary depth. Feed into a Dispatch component to split Grid Boxes
(or Slots) into boundary and interior groups. |
See also workflows and FAQs: 2.10 Boundary handling, 2.27 Restricting Modules to specific regions.
4.2.5 Deconstruct Grid Box
Extract the center plane, diagonal dimensions and Axis intervals from a Grid Box. Useful for working with the geometry of individual cells directly, for example to generate Module geometry at a cell’s exact position and size.
Behavior
Decomposes each Grid Box in the input tree into its geometric components. The output tree structure mirrors the input tree. Invalid Grid Boxes produce null outputs in their branch positions (with a component warning), preserving index alignment with the input.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Grid Box | B |
Grid Box | Tree | Grid Boxes to deconstruct. Accepts any tree structure. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Center Plane | P |
Plane | Tree | Plane at the center of each Grid Box, with the Grid Box Orientation. |
| Diagonal | D |
Vector | Tree | X, Y, Z dimensions of each Grid Box. |
| X Interval | X |
Interval | Tree | Interval along the X Axis (from -halfX to
+halfX relative to center).
|
| Y Interval | Y |
Interval | Tree | Interval along the Y Axis (from -halfY to
+halfY relative to center).
|
| Z Interval | Z |
Interval | Tree | Interval along the Z Axis (from -halfZ to
+halfZ relative to center).
|
See also workflows and FAQs: 2.20 Grid topology analysis, 2.27 Restricting Modules to specific regions.
4.2.6 Grid Topology
Extract the discrete grid coordinates and adjacency map of an Envelope. For each Grid Box, the component reports its integer position in the grid and which other boxes are its neighbors. Useful when reasoning about spatial relationships within the Envelope in Grasshopper - for example, to drive custom Module allowances based on grid position.
Behavior
The Relative Coordinates output gives each Grid Box’s
integer (column, row, layer) position within the grid, expressed as a Point.
These are not world-space coordinates - they are grid indices. Index
(0, 0, 0) is always the first box.
The Topology output is a tree where branch N
contains the indices of all Grid Boxes adjacent to box N. This
is analogous to the Grasshopper Proximity 3D component, but
works in discrete grid-step distances rather than Euclidean distance, and
respects the actual cell connectivity of the Envelope rather than raw point
clouds.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Grid Boxes | B |
Grid Box | List | All Grid Box objects forming the Envelope. |
| Diagonal Neighbors | D |
Boolean | Item | When true, also include corner-diagonal adjacencies.
Default: false. |
| Bi-Directional Topology | BiDi |
Boolean | Item | When true (default), each pair appears in both
Directions. When false, only the positive-Axis
Direction is listed (halves the output size for undirected
graph work).
|
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Relative Coordinates | C |
Point | List | Integer grid coordinates (column, row, layer) for
each Grid Box, matched by index. |
| Topology | T |
Integer | Tree | For each Grid Box (by branch index): the list of indices of its adjacent neighbors. |
See also workflows and FAQs: 2.20 Grid topology analysis, 2.27 Restricting Modules to specific regions.
4.2.7 Neighbor Grid Boxes
Find the Grid Boxes that are adjacent to a given set of focus cells. Given a list of focus indices, the component returns the indices of all Grid Boxes within the specified search distance (in grid steps) that are not themselves focus boxes. Useful for selecting “everything around” a particular sub-region of the Envelope.
Behavior
The search follows Grid Topology (not Euclidean distance), so a distance of
1 returns only directly adjacent cells, 2 includes
those plus their neighbors, and so on. The focus cells themselves are excluded
from the output.
A typical workflow is to use the Are Grid Boxes Boundary component to get boundary indices, then feed those into Neighbor Grid Boxes to find the row of cells just inside the boundary. You can then use a Dispatch component to separate neighbor cells from the rest and apply different Module allowances to each group.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Grid Boxes | B |
Grid Box | List | All Grid Box objects forming the Envelope. |
| Grid Box Indices | I |
Integer | List | Indices of the focus cells whose neighbors to find. |
| Layers | L |
Integer | Item | Search distance in grid steps. Default: 1. |
| Include X | X |
Boolean | Item | Search along the X Axis. Default: true. |
| Include Y | Y |
Boolean | Item | Search along the Y Axis. Default: true. |
| Include Z | Z |
Boolean | Item | Search along the Z Axis. Default: true. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Neighbor Indices | I |
Integer | List | Unique indices of Grid Boxes neighboring the focus cells (focus cells excluded). Use with Dispatch to separate the neighbor region from the rest of the Envelope. |
See also workflows and FAQs: 2.20 Grid topology analysis.
4.2.8 Grid Boxes from Geometry
Generate a set of Grid Boxes whose cells cover the shape of input geometry. Use this to define a non-rectangular Envelope that follows an arbitrary form - for example a curved building mass, a terrain surface, or a point cloud.
Behavior
The component samples the input geometry at grid intersection points and creates a Grid Box for each cell that the geometry passes through or contains. The Fill Method controls whether only the surface skin is covered, only the interior volume, or both.
The sampling works by testing candidate grid positions against the geometry. When a test point lies exactly on a geometric feature (such as on a surface edge or curve endpoint), the result can be ambiguous and that position may be skipped. The component reports these cases with a remark. If Grid Boxes are missing in expected positions, try slightly offsetting, scaling, or simplifying the geometry near those gaps.
Supported geometry types: Points, Curves, untrimmed Surfaces, Breps, and Meshes. Trimmed surfaces should be converted to Breps before use (use the Convert to Brep component in Grasshopper).
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Geometry | G |
Geometry | List | Input geometry defining the Envelope shape. Multiple items are merged into a single Envelope. |
| Base Plane | B |
Plane | Item | Grid Orientation and origin. Must match the Orientation of the
Modules used in the setup. Default: World XY. |
| Grid Box Diagonal | D |
Vector | Item | Cell size along X, Y and Z Axes. Should match the Module cell
size. Default: (1, 1, 1).
|
| Fill Method | F |
Integer | Item | 0 = surface wrap only (cells touching the geometry
surface), 1 = interior fill only (cells fully inside
the geometry), 2 = both (default). Use
0 for open shells and thin geometry. Use
1 for solid volumes where only the interior is needed.
|
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Grid Boxes | B |
Grid Box | List | Generated Grid Box instances covering the input geometry, suitable for constructing Slots. |
See also workflows and FAQs: 2.11 Constructing Slots from geometry, 2.24 Sparse grids with intentional gaps, FAQ 1.17 What geometry types are supported?, FAQ 1.18 Can I use curved geometry as Modules?.
4.2.9 Fill Block of Grid Boxes4.3 Face
Components for extracting, analyzing, comparing, and suggesting Module Faces.
4.3.1 Get Module Faces
Deconstruct a Module into its 6 individual Faces, one per output.
Behavior
Reads the Module’s internal Face array and outputs each Direction as a separate FaceId parameter. Returns error if Module is null or invalid.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Module | M |
Module | Item | Module from which to extract Faces. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
+X Face |
+X |
FaceId | Item | Face facing positive X. |
-X Face |
-X |
FaceId | Item | Face facing negative X. |
+Y Face |
+Y |
FaceId | Item | Face facing positive Y. |
-Y Face |
-Y |
FaceId | Item | Face facing negative Y. |
+Z Face |
+Z |
FaceId | Item | Face facing positive Z. |
-Z Face |
-Z |
FaceId | Item | Face facing negative Z. |
See also workflows and FAQs: 2.5 Defining Rules from Faces, 2.19 Visualizing Rules and Faces.
4.3.2 Analyze Face
Analyze Face properties including geometry, Direction and Rule/Connector usage. Provides Direction flags, Face planes, rectangles, and used/unused classification.
Behavior
Looks up each Face’s Module, extracts Face plane and rectangle geometry, determines Direction flags, and checks Rule and Connector references. Builds output trees parallel to the input Face tree.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Face | C |
FaceId | Tree | FaceId items to analyze. A Module wired here stands for all six of its Faces. |
| Modules | M |
Module | Tree | Modules to resolve Face geometry. Optional. |
| Rules | R |
Rule | Tree | Rules to determine Face usage. Optional. |
| Connectors | C |
Connector | Tree | Connectors to determine Face usage. Optional. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Module Name | MN |
ModuleName | Item | Module Name associated with the Face. |
| Face Planes | CP |
Plane | Item | Local planes describing Face geometry. |
| Face Rectangles | CR |
Rectangle3d | Item | Projected rectangle outlines of each Face. |
| Face Direction | CD |
Vector3d | Item | Unit vector for the Face normal. |
| Is X / Is Y / Is Z | X / Y / Z |
Boolean | Item | True if Face points in the respective positive Direction. |
| Is -X / Is -Y / Is -Z | -X / -Y / -Z |
Boolean | Item | True if Face points in the respective negative Direction. |
| Face Use Pattern | CUP |
Boolean | Item | True when the Face is referenced by any Rule or Connector. |
| Used Faces | CU |
FaceId | Item | Faces referenced by at least one Rule or Connector. |
| Unused Faces | CUU |
FaceId | Item | Faces not referenced by any Rule or Connector. |
See also workflows and FAQs: 2.5 Defining Rules from Faces, 2.19 Visualizing Rules and Faces.
4.3.3 Compare Faces
Compare two Faces for identity, Module membership and Direction relationship.
Behavior
Compares Module Name, Face Index and Direction. Same Axis = same or opposite; different Axis = skew.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Face | C |
FaceId | Item | First Face to compare. |
| Face | C |
FaceId | Item | Second Face to compare. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Identical | I |
Boolean | Item | True if the Faces are identical. |
| Same Module | M |
Boolean | Item | True if they refer to the same Module. |
| Same Direction | D |
Boolean | Item | True if they Face the same Direction. |
| Opposite Direction | O |
Boolean | Item | True if they Face opposite Directions. |
| Skew Direction | S |
Boolean | Item | True if they Face skew (non-parallel) Directions. |
See also workflows and FAQs: 2.5 Defining Rules from Faces.
4.3.4 Faces from Point
Detect Module Faces at a point location. Returns all Faces whose geometry contains the given point.
Behavior
Tests point containment against each Face of each Module. Warns if point matches zero Faces; remarks if point matches more than one.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Modules | M |
Module | List | All Modules to Sample for Faces. |
| Point Tag | Pt |
Point3d | Item | Point marking a Face location. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Faces | C |
FaceId | List | Faces whose geometry contains the point. |
See also workflows and FAQs: 2.12 Fixing Modules in the Envelope, 4.1.1 Connector from Point (creates a Connector directly from a point tag).
4.3.5 Used Faces
Filter Module Faces by Rule and Connector coverage. Partitions every Module’s six Faces into used (referenced by at least one Rule or Connector) and unused (no reference). Wire the Unused output into Construct Terminator to mark uncovered Faces as boundary-safe, or use it to assign indifference Connectors.
Behavior
Collects all Face references from Rules (source and target) and Connectors (Module + Face Index) into a set, then tests each of the six Faces of every input Module against that set. Both inputs are optional — when neither is provided all Faces are reported as unused. Output trees mirror the input Module tree structure with one grafted branch per Module.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Modules | M |
Module | Tree | Modules whose Faces will be checked for coverage. |
| Rules | R |
Rule | Tree (flattened) | Rules to check. A Face referenced as source or target of any Rule is considered used. Optional. |
| Connectors | C |
Connector | Tree (flattened) | Connectors to check. A Face with any Connector assigned is considered used. Optional. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Used Faces | F |
FaceId | Tree | Faces referenced by at least one Rule or Connector. |
| Unused Faces | UF |
FaceId | Tree | Faces not referenced by any provided Rule or Connector. |
See also workflows and FAQs: 2.35 Marking unused Faces as Terminators, 2.20 How to allow all indifferent Faces on the boundary.
4.3.6 Preview Faces
Visualize Faces with their geometry, anchor planes and Direction indicators. Display-only component (no geometry outputs).
Behavior
Draws rectangles at Face planes with Direction arrows colored by Axis (X = red, Y = green, Z = blue). Supports both viewport preview and baking to Rhino with grouped geometry.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Faces | C |
FaceId | Tree | FaceId items to preview. A Module wired here stands for all six of its Faces. |
| Modules | M |
Module | Tree | Modules to resolve Face geometry for preview. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| No outputs - preview/display only. | ||||
See also workflows and FAQs: 2.19 Visualizing Rules and Faces, FAQ tip 2.7 Test Rules visually before solving.
4.3.7 Suggest Faces from Geometry
4.3.8 Suggest Faces from Voxels
4.3.9 Touching Faces from Slots4.4 Main
The core components that drive the Monoceros workflow: validating the setup, running the WFC Solver, converting results into geometry, and the Assembly pipeline that packages everything for the Solver in a single step.
4.4.1 Construct Assembly
Build a complete Discrete Assembly in a single step. Expands rotation variants, transforms Connectors to match rotated Modules, generates Rules from Connectors and Connector Pairs, removes Disallowed Rules, enforces Exclusive Rules, applies indifference for unconnected Faces, merges all Rule sources, deduplicates Modules and Rules, runs a full Audit, and packages everything into an Assembly consumed by the Solver.
Behavior
Construct Assembly replaces the manual wiring pattern of Module Rotations → Rule merging → Audit with a single component. It performs rotation expansion on all Modules with rotation flags set, remaps existing Rules for the new variants, transforms Connectors to match the expanded variants, generates explicit Rules from Connectors and Allowed Connector Pairs (respecting symmetry flags and rotations), merges these with manually provided Allowed Rules, removes Disallowed Rules (explicit and from Disallowed Connector Pairs), enforces Exclusive Rules (explicit and from Exclusive Connector Pairs) by removing all other Rules referencing the same Faces, deduplicates everything, optionally generates Indifferent Rules for uncovered Faces, and runs the same Audit logic as the standalone Audit component.
During Rule remapping, each rotation variant receives a Face permutation that maps original Face Indices to their new positions after rotation. When both sides of a Rule are rotation-expanded, only variants with the identical rotation (same Face permutation) are paired - the spatial neighborhood rotates as a rigid unit. Mismatched rotations would produce geometrically wrong Rules even when Face Directions remain opposite. When only one side is expanded, only the rotated side’s Face Index is permuted.
The output Assembly is an opaque container. Connect it to the WFC Solver, to a Deconstruct Assembly component for inspection, or to Materialize Assembly after solving. The AllowIndifferent flag is now handled here instead of on the Solver.
Allowed Connector Pair deduplication. Construct Assembly
removes exact-duplicate Allowed Connector Pairs from the input list before
generating any Rules. Cross-referencing Connector lists on the canvas easily
produces exact duplicates, and the Rule generator is O(Modules² ×
Axes) per pair - deduplicating up front saves substantial computation
on larger definitions. A single Remark reports how many duplicates were
dropped. Note that A→B and B→A are kept
as separate entries because the downstream Rule generator treats Direction
as meaningful.
Allow-all Slot resolution. Construct Assembly also resolves
any allow-all Slots (Slots created without explicit Module Names) it receives.
After rotation expansion has produced the final Module set, every allow-all
Slot is filled with the deduplicated list of Module Names, assigned uniform
Weights of 1.0, and its Total Modules Count is set to match.
Modules whose box dimensions do not match the Slot are filtered out, so mixed-
dimension setups still produce dimension-consistent Slots. A single summary
Remark reports how many Slots were resolved and to how many Modules -
one Remark per Slot would flood the log for large allow-all Envelopes.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Modules | M |
Module | List | Modules with rotation flags still set. Rotation expansion is performed internally. |
| Slots | S |
Slot | List | Slot Envelopes to include in the Assembly. |
| Allowed Rules | R |
Rule | List | Optional. Manually defined allowed Rules. Merged with Rules generated from Connectors and Allowed Connector Pairs. |
| Disallowed Rules | DR |
Rule | List | Optional. Rules to remove from the allowed set. |
| Exclusive Rules | ER |
Rule | List | Optional. Rules whose Faces become exclusive: all other Rules referencing those Faces are removed, then the exclusive Rules are added. |
| Connectors | C |
Connector | List | Optional. All Connector-to-Face bindings. Combined with Connector Pairs to generate Rules automatically. |
| Allowed Connector Pairs | CP |
Connector Pair | List | Optional. Connector Pair declarations for generating allowed Rules. Combined with Connectors. |
| Disallowed Connector Pairs | DCP |
Connector Pair | List | Optional. Connector Pairs whose generated Rules are removed from the allowed set. |
| Exclusive Connector Pairs | ECP |
Connector Pair | List | Optional. Connector Pairs whose Faces become exclusive: all other Rules referencing those Faces are removed, then the exclusive Rules are added. |
| Require Terminators | RT |
Boolean | Item | Enable automatic boundary enforcement. When true,
Construct Assembly wraps the Envelope in a one-cell-thick
synthesized boundary layer and generates adjacency Rules linking
each Terminator-marked Face to the boundary. Module Faces without
a Terminator are forbidden from touching the outer edge. Requires
at least one Terminator to be connected. Default:
false. |
| Terminators | T |
Terminator | List | Optional. Boundary-facing Face markers produced by
Construct Terminator or
Terminator from Point.
Each Terminator marks one Module Face as allowed to sit on the
Envelope boundary. Required when Require Terminators is
true; ignored otherwise. |
| Indifference | I |
Boolean | Item | Enable indifference for unconnected Faces. When true,
Faces not covered by any Rule are automatically paired with matching
opposite Faces. Default: true. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Assembly | A |
Assembly | Item | Complete, audited Discrete Assembly ready for the Solver. |
4.4.2 Deconstruct Assembly
Extract all authored inputs from a Discrete Assembly: Modules, Slots, Connectors, Connector Pairs, Rules, Terminators, and the Indifference and Require Terminators flags.
Behavior
Extracts the authored side of the Assembly container - the data exactly as supplied on Construct Assembly before rotation expansion and Rule generation. Rotation variants generated from Module symmetry flags are not included; use Dissolve Assembly to access the expanded Solver-ready state.
After solving, the Slots output returns authored Slots with narrowed Module Names: rotation variants in each solved Slot are projected back to their source Module Name, and the result is intersected with the authored Slot's original Module Names list so order and Weights are preserved. All Audit outputs have moved to the Audit Assembly component.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Assembly | A |
Assembly | Item | Any Discrete Assembly from Construct Assembly or the Solver. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Modules | M |
Module | List | Authored Modules as supplied on Construct Assembly. Rotation variants are not included. |
| Slots | S |
Slot | List | Authored Slots in original order. After solving, Module Names are narrowed to surviving source Modules (rotation variants projected back). |
| Connectors | C |
Connector | List | Authored Connectors as supplied on Construct Assembly. |
| Allowed Connector Pairs | CP |
Connector Pair | List | Authored allowed Connector Pairs. |
| Disallowed Connector Pairs | DCP |
Connector Pair | List | Authored disallowed Connector Pairs. |
| Exclusive Connector Pairs | ECP |
Connector Pair | List | Authored exclusive Connector Pairs. |
| Rules | R |
Rule | List | Authored allowed Rules as supplied on Construct Assembly. |
| Disallowed Rules | DR |
Rule | List | Authored disallowed Rules. |
| Exclusive Rules | ER |
Rule | List | Authored exclusive Rules. |
| Indifference | I |
Boolean | Item | Whether Indifference was enabled on Construct Assembly. |
| Terminators | T |
Terminator | List | Authored Terminators — boundary-facing Face markers as supplied on Construct Assembly. |
| Require Terminators | RT |
Boolean | Item | Whether Require Terminators was enabled on Construct Assembly. |
4.4.3 WFC Solver
The WFC Solver runs the Wave Function Collapse algorithm on the supplied Envelope. It takes a Discrete Assembly as its sole data input, progressively eliminating Module candidates from each Slot - guided by adjacency constraints and weighted Entropy - until every Slot holds exactly one Module, or the Attempt ends in a Contradiction. Returns an output Assembly with solved Slot states, status flags, Seed values, and a Solver log.
Behavior
Before starting, the Solver validates all inputs and checks whether the Envelope is already Deterministic (fully solved) or already Contradictory (cannot be solved at all). If so, it stops immediately without running any solve steps.
The Solver then runs one single-threaded Attempt using the chosen Seed. This is a fast, cheap check: if the problem is easy it often finds a solution or reaches a Contradiction right away, with no extra overhead. Only when that first Attempt does not produce a definitive result does the Solver spawn parallel workers on the remaining CPU cores, each with an incremented Seed, to search for a solution simultaneously.
Each Attempt works by repeating two steps. First it picks the Slot with the fewest remaining candidates and assigns it a single Module, making it Deterministic (an Observation). Then it cascades the consequences of that choice through the whole Envelope, eliminating Module candidates that would violate Rules with neighboring Slots (this is called Propagation). The cycle continues until either every Slot has exactly one candidate (Deterministic - success) or some Slot has no candidates left (Contradictory - failure). A Contradictory result is retried with a different Seed.
The Solver log (Report output) shows a summary of preprocessing, the number of Rules used (including any auto-generated Indifferent Rules), and the outcome of each Attempt.
Seeds
The Random Seed input controls the starting point for the Solver's random
choices. For the same Slots, Modules, and Rules, the same Seed always produces the
same result. Seeds themselves have no inherent meaning - they are arbitrary integers
that initialize the random number generator. There is no relationship between the
Seed value and the visual outcome; consecutive Seeds (e.g. 42, 43, 44) give
independent, unrelated results. To explore the solution space, increment the Seed
by 1 for each variation, or use Return First = false with
Max Attempts set to the desired number - the Solver automatically
increments the Seed for each Attempt. When a result is satisfactory, record the
Seed from the Seeds output to reproduce it exactly later.
Indifferent Faces
Every Module has six Faces - one per Face. To be valid for solving, every Face that appears on a Module allowed in at least one Slot must be referenced by at least one Rule. A Face with no Rule provides no instruction: the Solver cannot determine what that Module may be placed next to.
Indifferent Faces are Faces with no explicit Rule that are automatically allowed to connect to any other uncovered Face facing the opposite Direction on the same Axis. The Solver generates these implicit pairings internally at solve time. The effect is equivalent to having manually written a Rule that permits all uncovered Faces to freely connect to each other - which is the same behavior as the Indifferent Rule in Monoceros 1.
This behavior is controlled by the Indifference input on Construct Assembly. When enabled, Construct Assembly generates Indifferent Rules for uncovered Faces before packaging the Assembly. When disabled, any uncovered Face is treated as a hard error.
To inspect which Faces are uncovered before solving, use the Faces Not In Rules output on the Audit Assembly component. Connect those Faces to a Preview Faces component to visualize them in the viewport, or use them as input to a Rule-construction component to add explicit Rules for those pairs.
The Audit Assembly report marks uncovered Faces as warnings - not errors - because
Construct Assembly can handle them via indifference. The
Slots Suitable for Solver output remains true even
when Faces are uncovered - it only turns false for hard errors
such as an invalid grid, unknown Module Names, or Contradictory Slots.
When Indifferent pairings are generated, the output log shows the total Rule count as N (M Indifferent), so you can see exactly how many Rules were auto-generated versus explicitly authored.
Limits
The free tier caps the WFC Solver at a limited number of runs per fixed time window (windows are aligned to UTC clock boundaries); paid tiers (Annual, Edu, Lifetime) are unlimited. Each Solver invocation that produces a result counts as one run regardless of the Max Attempts setting. The component footer shows a live counter indicating how many runs remain and when the window resets.
Regardless of tier, the Solver supports a maximum of 16,370 distinct Module Names across all Slots. Each rotation variant of a Module counts as a separate name - a single Module design can produce up to 24 Orientation invariants (from 90° turns around X, Y and Z Axes), so the limit accommodates roughly 682 fully-expanded unique designs, or more if not every Module uses all three rotation Axes. Exceeding this Module-name limit causes the Solver to report an error and stop without producing results.
Run input gate
The WFC Solver has a mandatory boolean Run input (default
false). The Solver only executes when Run is explicitly set to
True, which prevents upstream slider changes from accidentally burning
through the free tier's run budget. Connect a Boolean Toggle or a Button
component.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Assembly | A |
Assembly | Item | Discrete Assembly from Construct Assembly. The sole data input. |
| Random Seed | S |
Integer | Item | Starting Seed for the Solver. The same Seed always produces the same
result for the same input. Default: 42. When multiple
Attempts are needed, each Attempt uses an incremented Seed. |
| Max Attempts | A |
Integer | Item | Maximum number of solve Attempts before giving up. Raise this if
the Solver keeps failing on a tight setup. Default:
CPU cores + 1.
|
| Max Observations | O |
Integer | Item | Maximum number of Observations (collapse steps) per Attempt. The default is virtually unlimited. Lower this to produce partially-solved Envelopes on purpose - useful for step-by-step visualization or to Seed a partial result and continue solving manually. |
| Return First | F |
Boolean | Item | When true (default), stops as soon as the first
successful solution is found and outputs only that result. When
false, collects results from all Attempts and outputs
them as separate branches in a data tree - one branch per
successful solution. This allows comparing multiple variations from
different Seeds.
|
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Report | R |
Text | Item | Solver log summarizing preprocessing, the Rule set (including how many Indifferent Rules were generated), and the outcome of each Attempt. Useful for diagnosing slow or failing solves. |
| Assembly | A |
Assembly | Item | Output Discrete Assembly with solved Slot states. Connect to Materialize Assembly for geometry or Deconstruct Assembly for inspection. |
| Deterministic | OK |
Boolean | List | True if the corresponding solution is fully solved and ready to Materialize. |
| Contradictory | C |
Boolean | List | True if the corresponding Attempt ended in a Contradiction (no valid arrangement could be found with that Seed). |
| Seeds | S |
Integer | List | The Seed used for each returned Attempt. Record Seeds that produce results to reproduce them exactly later. |
| Observations | O |
Integer | List | Number of Observations (collapse steps) performed in each Attempt. |
| Attempts | A |
Integer | Item | Total number of Attempts the Solver ran. |
See also workflows and FAQs: 2.1 Bare minimum, 2.17 Solver settings, 1.1 Top-down: envelope first, FAQ 1.3 “World state is contradictory”, FAQ 1.4 Why can’t the Solver find a solution?.
4.4.4 Audit Assembly
Analyze a Discrete Assembly for consistency and errors. Reports missing Modules, unfitting Modules, Unused Faces and other issues that may block solving or materialization. Run this component before the Solver to catch setup problems early.
Behavior
Performs comprehensive validation: verifies Slots form a valid grid, cross-references Modules against Slots and Rules, detects orphaned or unused components, identifies dimension mismatches, checks for redundant Rules, self-connecting Modules, and potential over-constraint. The text Report groups findings into Grid, Slots, Modules, Rules and warning sections. All diagnostic outputs are available.
Faces not covered by any Rule are reported as warnings rather than errors because indifference on Construct Assembly (when enabled) automatically generates matching Rules for such Faces. The Faces Not In Rules output provides the actual Face objects for visualization or further use.
Allow-all Slot check. Audit flags any Slots that are still in the allow-all state as an Error - Construct Assembly is expected to resolve them before the Audit runs, so an unresolved Slot indicates that the pipeline was bypassed. Slots that were originally allow-all but have since been resolved are reported as an informational Remark so the user is reminded that the Module set was wired implicitly for those positions.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Assembly | A |
Assembly | Item | Discrete Assembly to analyze. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Report | R |
Text | Item | Human-readable report detailing all identified issues and warnings. |
| Slots Suitable for Solver | SlotsInGrid |
Boolean | Item | True if all hard errors are absent: valid grid, no unknown Module Names, no Contradictory Slots. Uncovered Faces alone do not make the setup unsuitable when indifference is enabled on Construct Assembly. |
| Grid Block Dimensions | GridDim |
Vector | Item | Number of Slots forming the Envelope in X, Y, Z Directions. |
| Is Grid Homogeneous | HomoGrid |
Boolean | Item | True if all Slots have identical cell dimensions. |
| Slots Accommodating All Modules | SlotsAccommodatingAll |
Integer | List | Indices of Slots whose Allowed Module Names list is a superset of every unique Module Name in the Assembly. Such Slots impose no per-Slot constraint - the Solver picks freely based on adjacency Rules and neighboring Slots. Includes Slots that were constructed as allow-all (no Module Names wired) and Slots manually wired with the full Module Name list. In Heterogeneous Envelopes allow-all Slots may be absent from this list because their Module Names were filtered down to the dimensionally-fitting subset during Construct Assembly resolution. |
| Slots Without Geometry | SlotsWithoutGeo |
Integer | List | Indices of Slots only allowing Modules without geometry. |
| Slots Accommodating Unknown Modules | SlotsUnknownMod |
Integer | List | Indices of Slots allowing unknown Module Names (error during materialization). |
| Slots Without Fitting Modules | SlotsUnfittingMod |
Integer | List | Indices of Slots only allowing Modules that have no Variant with matching dimensions. |
| Slots With More Fitting Modules | SlotsMoreMod |
Integer | List | Indices of Deterministic Slots where the single allowed Module exists in multiple Variants with identical dimensions. |
| Domain Of Module Weights | Weights |
Interval | Item | Min/max Weight values across all Slots. |
| Module Names | ModName |
Module Name | List | Unique Module Names. All other per-Module outputs are indexed according to this list. |
| Module Variants | ModVar |
Integer | Tree | Indices of Modules sharing the same Module Name, grouped by name. |
| Module Name Count In Slots | ModNamInSlots |
Integer | Tree | Number of Slots allowing each Module Name. |
| Module Variant Count In Slots | ModInSlots |
Integer | Tree | Number of Slots allowing each Module Variant. |
| Module Variant Never In Slots | ModNotInSlots |
Integer | List | Indices of Module Variants not allowed in any Slot. |
| Module Variant Never In Rules | ModNotInRules |
Integer | List | Indices of Module Variants not referenced by any Rule. |
| Module Variant Face Never In Rules | ModFaceNotInRules |
Integer | List | Indices of Module Variants that have at least one Face not covered by any Rule. Use for counting and filtering. For the actual Face objects, see Faces Not In Rules. |
| Modules With Geometry | ModWithGeo |
Integer | Tree | Indices of Module Variants containing geometry. |
| Modules Without Geometry | ModWithoutGeo |
Integer | Tree | Indices of Module Variants containing no geometry. |
| Modules With And Without Geometry | ModWithWithoutGeo |
Integer | Tree | Module Names where some Variants have geometry and others do not (likely a mistake). |
| Modules With Identical Names and Dimensions | ModIdentDim |
Integer | Tree | Variants with identical Name and dimensions (certainly a mistake: duplicate placements). |
| Modules Allowed in Unfitting Slots | ModInUnfitSlots |
Integer | Tree | Slots that cannot be materialized because they only accommodate Modules with unfitting dimensions. |
| Module Faces | ModFace |
Face | Tree | All Faces for each Module Variant. |
| Module Faces Use Count | ModFaceUse |
Integer | Tree | Number of Rules referencing each Module Face. |
| Rules Referring Unknown Modules | RulUnknownMod |
Integer | List | Indices of Rules referring to unknown Module Names. |
| Rules Referring Unused Modules | RulUnusedMod |
Integer | List | Indices of Rules referring to Module Names not allowed by any Slot. |
| Rule Occurrence Count | RulCount |
Integer | List | How many times each Rule occurs (above 1 = redundancy). |
| Is Rule’s First Occurrence | RulFirst |
Boolean | List | True for the first occurrence of each Rule (use as cull pattern for deduplication). |
| Modules With Only Self-Connecting Rules | ModSelfOnly |
Integer | List | Variants appearing exclusively in self-connecting Rules (often unintentional). |
| Potential Over-Constraint | OverConstrained |
Boolean | Item | True if the setup is likely over-constrained even with Indifferent Faces accounted for. Faces that have no valid opposite partner on the same Axis cannot be made Indifferent and will cause Solver errors. See also Faces Not In Rules. |
| Faces Not In Rules | FaceNotInRules |
Face | List | All Faces across all provided Modules that are not covered by any Rule. These are the Faces that become Indifferent when indifference is enabled on Construct Assembly. Connect to a Face Preview component to visualize them in the viewport, or into a Rule construction component to add explicit Rules for those Faces. |
| All Faces Indifferent | AllIndiff |
Boolean | Item | True if no Faces appear in any Rule at all. When true the Assembly has no explicit adjacency constraints and the Solver will place Modules randomly. |
| Effectively Indifferent Faces | EffectIndiff |
Face | List | Faces that are technically covered by Rules but are effectively Indifferent because they are paired with every possible opposing neighbour. These Faces do not constrain the Solver at all. |
| Singly Constrained Faces | SingleCon |
Face | List | Faces covered by exactly one Rule. When all Faces are singly constrained the Solver has no choices and every Seed produces the same result. Useful for diagnosing lack of variety. |
| Require Terminators Active | ReqTerm |
Boolean | Item | True if Construct Assembly synthesized a boundary layer (Require Terminators was enabled). False means no boundary layer was added and the two Terminator Face outputs below are empty. |
| Terminator Faces Covered | TermCovered |
Face Index | List | Face Directions (+X, +Y, +Z, −X, −Y, −Z) for which at least one Terminator was supplied. Only populated when Require Terminators is Active. A Direction absent from this list means no Module Face on that side of the Envelope is allowed to touch the boundary — the Solver is likely to contradict. |
| Terminator Faces Missing | TermMissing |
Face Index | List | Face Directions (+X, +Y, +Z, −X, −Y, −Z) for which no Terminator was supplied. Only populated when Require Terminators is Active. An empty list means all six Face Directions are covered and any Module Face can be placed against the boundary. |
See also workflows and FAQs: 2.18 Audit-driven debugging, 1.5 Debugging strategy, FAQ 1.3 “World state is contradictory”, FAQ 1.4 Why can’t the Solver find a solution?.
4.4.5 Materialize Assembly
Extract placed geometry from a solved Discrete Assembly. Takes an Assembly as input and produces geometry. For every Deterministic Slot, it looks up the assigned Module (including rotation variants), finds the variant whose dimensions match the Slot’s cell box, and moves and orients the Module geometry into place. The output is ready to bake, render, or process further in Grasshopper.
Behavior
Each Deterministic Slot is matched to the Module Variant whose name and cell dimensions agree. The Module geometry is transformed from its original position into the Slot’s position and Orientation via a plane-to-plane mapping. Non-deterministic Slots (still carrying multiple candidates) are skipped. Contradictory Slots (zero allowed Modules) produce no geometry.
When multiple Module Variants share the same name and the same dimensions, all matching Variants are placed into the corresponding Slot. This is typically a configuration mistake and the Modules With Identical Names and Dimensions output of the Audit Assembly component will flag it.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Assembly | A |
Assembly | Item | Solved (or partially solved) Discrete Assembly from the Solver’s Assembly output. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Geometry | G |
Geometry | Tree | Placed geometry for all Deterministic Slots. The tree structure mirrors the input Slot tree - each branch corresponds to one solution when multiple solutions were requested. |
| Transforms | X |
Transform | Tree | Transformation matrix applied to each geometry piece, matched by index to the Geometry output. Useful for driving block instances or applying the same transformation to related data. |
| Module Names | MN |
Text | Tree | Module Name placed in each Deterministic Slot. |
See also workflows and FAQs: 2.1 Bare minimum, 2.16 Materializing results, 2.29 Exporting results for fabrication.
4.4.6 Sample Geometry
Create Module candidates by sampling input geometry into GridBox cells. Chops geometry to Slot Envelopes, voxelizes for comparison, and deduplicates identical Modules. Returns Modules ready for Face analysis and Rule construction.
Behavior
For each GridBox, chops geometry (curve–brep intersection, mesh splitting, brep trimming) in parallel. Voxelizes each Module and deduplicates by comparing voxel patterns and box dimensions (epsilon comparison). Creates a Slot for each box with the assigned Module Name and default Weight.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Module Name Base | ModNamBas |
Text | Item | Base string for auto-generated Module Names (counter appended). |
| Voxel Resolution | V |
Vector | Item | Voxels per Axis for comparison. Default:
16×16×16.
|
| Geometry | G |
Geometry | List | Geometry to Sample (Point, Curve, Brep, Mesh). |
| Sampling Boxes | B |
GridBox | List | Boxes used to chop and Sample geometry. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Modules | M |
Module | List | Unique Module candidates extracted from the sampled geometry. |
| Module Count | MC |
Integer | Item | Number of Module instances derived from the input. |
| Slots | S |
Slot | List | Slots created along with Module placements. |
| Box to Module Index | B2MI |
Integer | List | For each input box, the index of the Module it produced (-1 if none). |
| Box to Slot Index | B2SI |
Integer | List | For each input box, the index of the Slot it produced (-1 if none). |
See also workflows and FAQs: 2.1 Bare minimum, 2.11 Constructing Slots from geometry, FAQ tip 2.14 Use Sample Geometry to verify Module content.
4.5 Module
Components for constructing, deconstructing, rotating, and deduplicating Modules.
4.5.1 Construct Module
Construct a Module from a name, GridBox and optional geometry. Modules are the building blocks placed into Slots during WFC solving. Each Module has 6 Faces (one per Face).
Behavior
Validates name and GridBox. Removes invalid geometry items with warnings. Tracks geometry GUIDs. Reads rotation flags and stores them on the Module. Construct Assembly expands these flags into actual rotational variants, remapping Rules and Face Indices accordingly. The expanded variants are available via Deconstruct Assembly. Warns if geometry extends significantly outside the Module's Grid Box.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Module Name | MN |
ModuleName | Item | Name for the Module (converted to lowercase). |
| Module Box | B |
GridBox | Item | Box that contains the Module geometry. |
| Geometry | G |
Geometry | List | Geometry to Materialize. Does not need to fit within the Grid Box. Optional. |
| Rotate X | RX |
Boolean | Item | Auto-generate 90°/180°/270° rotated variants around X in
Construct Assembly. Variants appear via Deconstruct Assembly.
Default: false. |
| Rotate Y | RY |
Boolean | Item | Auto-generate rotated variants around Y. Default: false.
|
| Rotate Z | RZ |
Boolean | Item | Auto-generate rotated variants around Z. Default: false.
|
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Module | M |
Module | Item | Constructed Module instance. |
See also workflows and FAQs: 2.1 Bare minimum, 2.6 Working with multiple Modules, 1.2 Bottom-up: Modules first.
4.5.2 Deconstruct Module
Extract the components of a Module: name, GridBox, geometry, validity flag and all Faces.
Behavior
Retrieves Module properties and outputs them as separate parameters. Generates a flat list of FaceId items for all 6 Directions. Warns if the Module is invalid.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Module | M |
Module | Item | A Module to deconstruct. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Module Name | MN |
ModuleName | Item | Module Name (lowercase). |
| Module Box | B |
GridBox | Item | Box containing the Module geometry. |
| Geometry | G |
Geometry | Item | Geometry contained in the Module. |
| Is Valid | V |
Boolean | Item | True if the Module is valid for the Solver. |
| Faces | C |
FaceId | List | All 6 FaceId entries for this Module. |
See also workflows and FAQs: 2.9 Weighted Module placement, 2.27 Restricting Modules to specific regions.
4.5.3 Construct Megamodule
Create a multi-cell Module from a name and a list of adjacent GridBoxes.
Automatically
creates one sub-Module per box (named {name}_p0/N,
{name}_p1/N, etc. where N is the total part count), generates
exclusive
internal Rules, and identifies external (boundary) Faces.
Behavior
Every sub-Module receives the full Megamodule geometry so that Face
suggestion components can analyze all external Faces. Only the first
sub-Module (_p0) materializes the geometry - the Materialize
component skips geometry output for the remaining parts to avoid
duplication.
Each sub-Module previews its sibling Grid Boxes as dashed ghost outlines, making the full Megamodule footprint visible even when viewing a single part in isolation.
Optional Rotate X/Y/Z flags propagate to every sub-Module. When enabled, the Solver automatically generates rotated variants of the entire Megamodule and remaps both internal and external Rules accordingly.
Detects adjacency when Faces Face opposite Directions and anchor plane origins coincide (within epsilon). Creates internal Rules and tracks which Faces are used. Warns if multiple boxes provided but no adjacencies found.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Megamodule Name | MN |
ModuleName | Item | Base name for the Megamodule. Sub-Modules will be named
{name}_p0/N, {name}_p1/N, etc. |
| Grid Boxes | B |
GridBox | List | Adjacent GridBoxes defining the Megamodule footprint. |
| Geometry | G |
Geometry | List | Geometry spanning the full Megamodule. All geometry is given to every sub-Module for Face analysis; only the first sub-Module materializes it. Optional. |
| Rotate X | RX |
Boolean | Item | Generate 90°, 180° and 270° rotated variants around X. Default: false. |
| Rotate Y | RY |
Boolean | Item | Generate 90°, 180° and 270° rotated variants around Y. Default: false. |
| Rotate Z | RZ |
Boolean | Item | Generate 90°, 180° and 270° rotated variants around Z. Default: false. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Modules | M |
Module | Tree | Sub-Module instances, one per input GridBox. Each sub-Module is in its own tree branch {i}. Flattened by default. |
| Internal Rules | IR |
Rule | List | Exclusive adjacency Rules connecting adjacent sub-Modules. |
| External Faces | EF |
FaceId | Tree | Faces on the outer boundary, available for user-defined Rules. Each sub-Module's Faces are in their own tree branch {i}. Flattened by default. |
See also workflows and FAQs: 2.15 Megamodule construction, FAQ 1.19 How do I create L-shaped or T-shaped Modules?.
4.5.4 Deconstruct Megamodule
Extract GridBoxes, internal Rules, and external Faces from a set of Megamodule sub-Modules. Inspection companion to Construct Megamodule.
Behavior
Reconstructs internal Rules by comparing all Module pairs for opposite-Direction Faces with coinciding anchor planes. Remaining Faces (not in internal Rules) are output as external Faces.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Modules | M |
Module | List | Sub-Module list as produced by Construct Megamodule. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Grid Boxes | B |
GridBox | List | One GridBox per sub-Module. |
| Internal Rules | IR |
Rule | List | Adjacency Rules connecting sub-Module Faces. |
| External Faces | EC |
FaceId | List | Faces on the outer boundary. |
See also workflows and FAQs: 2.15 Megamodule construction.
4.5.5 Cull Duplicate Modules
Remove duplicate Modules by comparing voxelized geometry and box dimensions. Use after generating rotated variants or importing from multiple sources.
Behavior
Voxelizes each Module in parallel and compares voxel patterns and box dimensions using epsilon comparison. Tracks index mapping and valence. If Rules provided, remaps source/target Module Names for culled Modules, creating a cartesian product of mapped names.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Modules | M |
Module | List | Modules to deduplicate. |
| Voxel Resolution | V |
Vector | Item | Voxels per Axis for comparison. Default:
16×16×16.
|
| Rules | R |
Rule | List | Rules to remap to culled Modules. Optional. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Modules | M |
Module | List | Unique Modules after deduplication. |
| Indices | I |
Integer | List | Index map: which input Module each output represents. |
| Valence | V |
Integer | List | Number of input Modules represented by each output. |
| Rules | RD |
Rule | List | Rules remapped to the culled unique Modules. |
See also workflows and FAQs: 2.7 Automatic Module rotations.
4.5.6 Module Rotations
Generate rotated variants of a Module around each enabled Axis (90°, 180°, 270°) producing up to 24 unique orientations. Optionally deduplicates identical variants by voxel comparison.
Behavior
Builds compound rotation and translation transforms for each enabled Axis. Creates rotated geometry in parallel. If deduplication is enabled, voxelizes the original Module once, then maps those voxels through each rotation’s coordinate transform to produce a comparable voxel block per variant; compares patterns and box dimensions to keep only unique Modules.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Module | M |
Module | Item | Module to rotate. |
| Rotate X | X |
Boolean | Item | Enable X rotation. Default: true. |
| Rotate Y | Y |
Boolean | Item | Enable Y rotation. Default: true. |
| Rotate Z | Z |
Boolean | Item | Enable Z rotation. Default: true. |
| Cull Duplicates | C |
Boolean | Item | Remove identical rotated variants. Default: true. |
| Voxel Resolution | V |
Vector | Item | Voxels per Axis for comparison. Default:
16×16×16.
|
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Modules | M |
Module | List | Rotated Module variants. |
See also workflows and FAQs: 2.7 Automatic Module rotations, FAQ 1.30 Can I use Module Rotations instead of defining every direction?, FAQ tip 2.16 Use Module Rotations for isotropic geometry.
4.6 Rule
Components for constructing, deconstructing, filtering, and visualizing Rules.
4.6.1 Construct Rules from Faces
Construct Rules from two Face lists. All valid opposite combinations between the source and target lists are created. This is the most common way to define Rules.
Behavior
Iterates all source–target combinations, validating that Face Directions are opposite. Creates a Rule for each valid pair. Deduplicates automatically and reports non-opposite couples and duplicate count.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Source Faces | SC |
FaceId | List | Source-side FaceId entries. A Module wired here stands for all six of its Faces. |
| Target Faces | TC |
FaceId | List | Target-side FaceId entries. A Module wired here stands for all six of its Faces. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Rule | R |
Rule | List | Generated Rules from valid opposite pairings. |
See also workflows and FAQs: 2.5 Defining Rules from Faces, FAQ tip 2.6 Use Cross Reference for bulk Rule creation.
4.6.2 Construct Rules from Modules
Build Rules from source and target Module Name lists. Opposite Faces are
inferred
automatically. Provides six directional target inputs (+X,
+Y, +Z, -X, -Y,
-Z).
Behavior
For each source Module and each Direction, pairs with opposite-Direction Faces of target Modules. Deduplicates and reports counts. Warns if no target names specified.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Source Module Names | SMN |
ModuleName | List | Source Module Names. |
| X+ Target Module Names | X+ TMN |
ModuleName | List | Targets via +X Face. Optional. |
| Y+ Target Module Names | Y+ TMN |
ModuleName | List | Targets via +Y Face. Optional. |
| Z+ Target Module Names | Z+ TMN |
ModuleName | List | Targets via +Z Face. Optional. |
| X- Target Module Names | X- TMN |
ModuleName | List | Targets via -X Face. Optional. |
| Y- Target Module Names | Y- TMN |
ModuleName | List | Targets via -Y Face. Optional. |
| Z- Target Module Names | Z- TMN |
ModuleName | List | Targets via -Z Face. Optional. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Rule | R |
Rule | List | Generated Rules. |
See also workflows and FAQs: 2.21 Rules from Face Groups, 2.5 Defining Rules from Faces.
4.6.3 Deconstruct Rule
Deconstruct a Rule into its source and target FaceId entries.
Behavior
Extracts and outputs the SourceFaceId and TargetFaceId from the Rule.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Rule | R |
Rule | Item | Rule to deconstruct. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Source Face | SC |
FaceId | Item | Source-side FaceId. |
| Target Face | TC |
FaceId | Item | Target-side FaceId. |
See also workflows and FAQs: 2.19 Visualizing Rules and Faces.
4.6.4 Are Rules Equal
Compare two Rules for equality.
Behavior
Compares Rules using the Equals method (bidirectional: A→B equals
B→A).
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Rule A | RA |
Rule | Item | First Rule. |
| Rule B | RB |
Rule | Item | Second Rule. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Equal | E |
Boolean | Item | True when both Rules are equivalent. |
See also workflows and FAQs: 2.26 Combining manual and automatic Rules.
4.6.5 Rule from Curve
Create Rules from curves drawn between Module Faces. Each curve’s endpoints are matched to Faces that contain the point. A single curve can produce multiple Rules when endpoints overlap Faces from different Modules.
Behavior
Extracts start/end points from each curve. Finds all Faces that contain the endpoint (same logic as Faces From Point). Cross-references all start/end matches and creates Rules for pairs facing opposite Directions. Previews matched curves colored by Axis. Reports skipped curves and non-opposite pairs.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Curves | C |
Curve | List | Lines/curves drawn between two Faces. |
| Modules | M |
Module | List | All Modules to search for Faces. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Rules | R |
Rule | List | Rules from valid endpoint pairings. |
See also workflows and FAQs: 2.5 Defining Rules from Faces, 2.26 Combining manual and automatic Rules.
4.6.6 Suggest Rules from Geometry
Analyse Module Face geometry (naked edges, curves, points) and directly output Rules for all geometrically matching pairs. Combines Suggest Faces + Construct Rules in one step.
Behavior
Collects naked edge polylines from Breps/Meshes, open curve endpoints and point geometry. Projects onto Face planes. Pairs matching source/target Faces by checking opposite Directions, equal Face dimensions and epsilon-equal point lists.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Modules | M |
Module | List | All Modules to analyse for Face geometry matches. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Rules | R |
Rule | List | Suggested Rules from geometry matches. |
See also workflows and FAQs: 2.5 Defining Rules from Faces, 2.26 Combining manual and automatic Rules.
4.6.7 Suggest Rules from Voxels
Voxelize Modules at the specified resolution, scan Face voxel layers within the configured depth range, and directly output Rules for all matching Face pairs. Combines voxel-based Face suggestion and Rule construction in one step.
Behavior
Voxelizes each Module geometry at the given resolution. For each Face pair (source positive, target negative) that Faces opposite Directions and has matching dimensions, OR-folds voxel Face layers within the scanning depth interval and compares them. Outputs Rules for all pairs whose patterns are identical.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Modules | M |
Module | List | All Modules to voxelize and analyse for Face matches. |
| Voxel Resolution | V |
Vector | Item | Number of voxels per Direction. Higher values detect finer differences. |
| Scanning Depth | D |
Interval | Item | Relative depth range (0–1) of Face layers to compare. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Rules | R |
Rule | List | Suggested Rules from voxel-matched Face patterns. |
4.6.8 Preview Rule
Display Rules as lines connecting individual Faces for visual verification and baking. Display-only component (no geometry outputs).
Behavior
Finds matching source and target Module Faces for each Rule. Draws lines between Face anchor plane origins, colored by Direction Axis (X = red, Y = green, Z = blue). Supports viewport preview and baking to Rhino.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Rules | R |
Rule | Tree | Rules to preview. |
| Modules | M |
Module | Tree | All Modules to display with Rules. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| No outputs - preview/display only. | ||||
See also workflows and FAQs: 2.19 Visualizing Rules and Faces, FAQ tip 2.7 Test Rules visually before solving.
4.6.9 Construct Rules from Faces & Modules
4.6.10 Rule from Points4.7 Slot
Components for constructing and analyzing Slots.
4.7.1 Construct Slot
Create a Slot with allowed Module Names and optional Weights. Assemble from a GridBox and a set of allowed ModuleNames. The Allowed Module Names input is optional: when omitted, the Slot is created in an “allow all” state and will be resolved to the full final Module set by Construct Assembly.
Behavior
Validates branch matching between GridBoxes, Module Names and Weights. Defaults Weights to 1.0 if not provided; extends the Weight list with the last value if fewer Weights than names. Creates Slot instances with validated inputs. All Weights must be > 0.
Allow-all Slots. If Allowed Module Names is not connected, the component emits the Remark “No Module Names provided. Slot allows all Modules. The allowed set will be resolved by Construct Assembly.” and builds a Slot with an empty Module list. Any Weights connected alongside an empty Module Names input are ignored (a Remark is emitted). The Slot previews as white (“All allowed”) in the viewport until Construct Assembly resolves it to the deduplicated final Module Name list with uniform Weights.
AllModulesCount is no longer a user input. Every Slot leaves
Construct Slot with AllModulesCount = 0 (the total Module count
is not yet known). The viewport preview reflects that: the cage shows only the
allowed-Module count — one number in the corner, no
/ total. Once the Slots pass through Construct Assembly,
AllModulesCount is stamped with the size of the final Module set
and the preview switches to the familiar
allowed / total form. No cross-component wiring is
required to keep Entropy percentages consistent.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Grid Box | B |
GridBox | tree (grafted) | Box that will become a Slot. |
| Allowed Module Names | MN |
ModuleName | Tree | Module Names the Slot permits. Single flat list reuses across boxes; branch-matching lists specify per-box. Optional - if not connected, the Slot is created as allow-all and will be resolved by Construct Assembly to the full final Module set. |
| Allowed Modules Weights | W |
Number | Tree | Weights for allowed Modules. Optional — if not connected or
empty, every allowed Module gets a uniform Weight of 1.0.
Ignored when Allowed Module Names is not connected. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Slot | S |
Slot | Tree | Constructed Slot instances. |
See also workflows and FAQs: 2.1 Bare minimum, 2.11 Constructing Slots from geometry, 2.12 Fixing Modules in the Envelope, 2.9 Weighted Module placement.
4.7.2 Deconstruct Slot
Extract a Slot’s components: GridBox, allowed Module Names, Weights, determinism flag, Contradiction flag and Entropy.
Behavior
Iterates through all Slots in the input tree. Calculates Entropy as
AllowedModulesCount / AllModulesCount. Skips invalid Slots with an
error message. Pre-Assembly and allow-all Slots both have
AllModulesCount = 0, so Entropy falls back to
1.0 explicitly — every Module is still a possibility until
Construct Assembly stamps AllModulesCount with the size of the
final Module set and (for allow-all Slots) resolves the allowed list.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Slot | S |
Slot | tree (grafted) | Slot to deconstruct. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Grid Box | B |
GridBox | Tree | The Slot’s spatial extent. |
| Allowed Module Names | MN |
ModuleName | Tree | Modules allowed in the Slot. |
| Allowed Module Weights | MW |
Number | Tree | Weights of allowed Modules. |
| Is Deterministic | Det |
Boolean | Tree | True if exactly one Module allowed. |
| Is Contradictory | Con |
Boolean | Tree | True if no Module allowed. |
| Entropy | E |
Number | Tree | Ratio of allowed to total Modules (1.0 = all, 0.0 = none).
Allow-all Slots report 1.0 explicitly. |
See also workflows and FAQs: 2.9 Weighted Module placement, 2.21 Rules from Face Groups, 2.12 Fixing Modules in the Envelope.
4.7.3 Changed Slots
Given an original list of Slots and one or more new Slot lists, identify which Slots changed between them. Returns a tree of indices - one branch per new list - where each index points to a Slot whose set of allowed Module Names differs from the original.
Behavior
The comparison is performed element-wise: each Slot at position
i in the original list is compared to position i
in the same branch of the new Slot tree. The allowed Module Names are sorted
before comparison so orderings that differ only in insertion sequence do not
produce false positives. The component runs each branch comparison in
parallel.
A common use is to connect the pre-solve and post-solve Slot lists and inspect which cells the Solver collapsed or constrained. Another use is design-space exploration: feed a Data Recorder's stored results as separate branches to the New Slots input, then compare against a baseline to see which regions of the Envelope vary across Seed runs.
All branches of the New Slots tree must have the same count as the Original Slots list. If any branch length mismatches, the component reports an error and produces no output.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Original Slots | OS |
Slot | List | The baseline Slot list to compare against. |
| New Slots | NS |
Slot | Tree | One or more Slot lists to compare. Each branch is compared independently against the original. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Changed Indices | ChngIdx |
Integer | Tree | For each branch, the flat indices of Slots whose allowed Module set differs from the original. |
See also workflows and FAQs: 2.17 Solver settings, 2.22 Proto-results workflow, FAQ tip 2.15 Compare results with Changed Slots, FAQ tip 2.9 Use Data Recorder to save multiple results.
4.7.4 Occurrence Count
Count how many Slots in the Envelope contain a given Module Name. Run after solving to get placement frequencies for fabrication estimates, bill-of-materials, or distribution analysis.
Behavior
By default, only Slots where the target Module is the sole allowed option
(Deterministic) are counted. Set Only Resolved to
false to also count Non-deterministic Slots where the target Module
appears alongside others - useful for inspecting unsolved or partially
solved Envelopes.
To get a full bill of materials, run Occurrence Count once per Module Name (e.g. via a loop or by grafting the Module Names list). The output is a single integer per invocation.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Module Name | MN |
Module Name | Item | The Module Name to count across the Slot list. |
| Slots | S |
Slot | List | List of Slots to search - typically the solved Slots output of the WFC Solver. |
| Only Resolved | OR |
Boolean | Item | When true (default), only Deterministic Slots are
counted. Set to false to also count Non-deterministic
Slots where the target Module appears alongside others. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Count | C |
Integer | Item | Number of Slots in the input list that contain the given Module Name. |
See also workflows and FAQs: 2.28 Occurrence Count analysis, 1.6 Fabrication-oriented workflow, FAQ 1.13 Module appears too often or not enough.
4.7.5 Slot Pattern
Find a Slot sub-pattern inside an existing Slot Envelope. Useful for template matching and locating repeated Module patterns.
Behavior
Builds a 3D grid from pattern and Envelope Slots via Grid Topology. Iterates through all Envelope positions testing if the pattern fits (bounds, dimension matching, Module Name inclusion). Returns indices for each match found.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Slots | S |
Slot | List | Envelope Slots to search. |
| Slot Pattern | P |
Slot | List | Slot sequence defining the sub-pattern to find. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Pattern Found | F |
Boolean | Item | True when the pattern exists within the Envelope. |
| Slot Indices | I |
Integer | Tree | Indices of matched Slots in the Envelope. |
See also workflows and FAQs: 2.20 Grid topology analysis, 2.27 Restricting Modules to specific regions.
4.7.6 Slot to Module
Place Module geometry into solved Slots. Similar to Materialize Assembly but works at the Slot level rather than the Assembly level — takes a flat list of Modules and a tree of solved Slots as separate inputs.
Behavior
By default only Deterministic Slots (exactly one allowed Module) are materialized. Set Only Deterministic to false to also place geometry for every allowed Module in Non-deterministic Slots. Contradictory Slots (zero allowed Modules) are always skipped.
For each eligible Slot, the component looks up the allowed Module Name(s) in the input Module list, finds the variant whose cell dimensions match the Slot, and transforms the Module geometry from its original position into the Slot’s position via a plane-to-plane mapping. Baking produces shared Rhino block definitions — one per unique Module — with one instance per Slot placement.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| All Modules | M |
Module | List (flatten) | Complete list of all Modules, including rotation variants. Connect the All Modules output from the WFC Solver directly here. |
| Solved Slots | S |
Slot | Tree | Slots resolved by the Solver. Each branch contains one complete solution when Return First is false. |
| Only Deterministic | D |
Boolean | Item | When true (default), only Deterministic Slots are materialized. When false, all non-Contradictory Slots are materialized, placing geometry for every allowed Module in each Slot. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Geometry | G |
Geometry | Tree | Placed geometry for all eligible Slots. The tree structure mirrors the input Slot tree. |
| Transforms | X |
Transform | Tree | Transformation matrix applied to each geometry piece, matched by index to the Geometry output. |
See also workflows and FAQs: 4.4.5 Materialize Assembly, 2.16 Materializing results.
4.7.7 Preview Rule in Slots
Generate Slots by applying a Rule to Module placements. Useful for creating assemblies that follow explicit Face constraints and for visualizing Rule effects.
Behavior
Finds source and target Modules matching the Rule Faces. Matches compatible pairs by comparing Face dimensions (within epsilon). Creates Deterministic Slots and placed Modules by transforming Module boxes to align with the pivot plane. The output Modules preserve their original rotation flags.
Inputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Rule | R |
Rule | Item | Rule defining Face relationships. |
| Face Pivot Plane | P |
Plane | Item | Plane to position source and target. Default:
World XY.
|
| Modules | M |
Module | List | Modules to find compatible pairings. |
Outputs
| Name | Nickname | Type | Access | Description |
|---|---|---|---|---|
| Source Slots | SS |
Slot | List | Slots permitting the source Module. |
| Target Slots | TS |
Slot | List | Slots permitting the target Module. |
| Source Modules | SM |
Module | List | Source Modules placed at the Rule positions. Rotation flags are preserved. |
| Target Modules | TM |
Module | List | Target Modules placed at the Rule positions. Rotation flags are preserved. |
See also workflows and FAQs: 2.12 Fixing Modules in the Envelope, 2.9 Weighted Module placement.
Vocabulary
All terms used in Monoceros 3 documentation and component tooltips, listed alphabetically. Terms that correspond to a data type or component link to their reference section.
- Attempt
- A single WFC solve run, from Canonicalization through cycles of Observation and Propagation. Multiple attempts with incrementing seeds run automatically when the first attempt ends in a Contradiction.
- Axis
- One of the three coordinate axes: X, Y, or Z. Each Face direction belongs to one axis (positive or negative face).
- Canonical
- The tightest consistent starting state of the Envelope, reached after the initial Propagation pass (Canonicalization). Every Slot contains only Modules that are actually achievable given the Rules.
- Canonicalization
- The initial constraint-propagation pass run before the first Observation. It eliminates already-impossible Module assignments from every Slot so the solver starts from the tightest consistent state. See 1.2 The algorithm.
- Changed Slots
- Compares two sets of Slots element-wise and returns the indices of Slots whose allowed Module list has changed. Useful for tracking which parts of the Envelope were affected by a Rule or weight change. See 4.7.3 Changed Slots.
- Connector
- A named, rotation-aware interface placed on a specific Module face. Combines type identity (name + symmetry flags) and placement (module + face + rotation) in one object. All Connectors sharing a name are the same type. Symmetry flags define which in-plane rotations are self-identical.
- Connector Pair
- Declares that two Connector types (by name) can connect across opposing faces. Bidirectional: A → B also allows B → A.
- Contradictory
- A Slot state where no Module can legally occupy it, making the current solve attempt impossible. The solver retries with a different seed up to the configured attempt limit.
- Deterministic
- A Slot state where exactly one Module is allowed. A fully deterministic Envelope means the solve succeeded and can be materialized.
- Direction
- One of the six face orientations: +X, −X, +Y, −Y, +Z, −Z. Combines an Axis and an Orientation. Direction is not a direct Grasshopper parameter — it is expressed through Face Index names.
- Discrete Assembly
- An opaque bundle containing expanded Modules, Slots, merged Rules, and audit results. Produced by Construct Assembly and consumed by the WFC Solver.
- Entropy
- A measure of how many Module candidates remain in a Slot. Low entropy means few options remain; a Slot with all Modules allowed has maximum entropy. The WFC solver always observes the Slot with the lowest entropy first.
- Envelope
- A set of Slots arranged in a valid grid, forming the spatial volume to be filled by the WFC solver. A grid of Grid Boxes becomes an Envelope once the Grid Boxes are converted to Slots. See 4.2 Envelope.
- Face
- One of the six faces of a Module, identified by a FaceId (e.g. module_name:+X). Rules specify which Face pairs may touch. Every Module has exactly six Faces, one in each direction: +X, −X, +Y, −Y, +Z, −Z. See 3.3.2 Face.
- Face Index
- An integer 0–5 identifying one face direction of a Module or Grid Box: ±X = 0/1, ±Y = 2/3, ±Z = 4/5. See 3.3.1 Face Index.
- Grid Box
- The basic spatial cell unit in a Monoceros grid — a box-shaped region that defines the size and position of one cell. See 3.1.1 Grid Box.
- Heterogeneous Grid
- A grid where cells can have different sizes along each axis. Each row along X can have a different width, each column along Y a different depth, and each layer along Z a different height. See 4.2.1 Heterogeneous Grid.
- Homogeneous Grid
- A grid where every cell has the same X, Y, and Z dimensions. The most common starting point for a WFC setup. See 4.2.2 Homogeneous Grid.
- Indifferent Face
- A Face that has no explicit Rule. When indifference is enabled on Construct Assembly, indifferent Faces automatically connect to any other indifferent Face facing the opposite direction on the same axis.
- Megamodule
- A Module that spans multiple adjacent Grid Boxes, treated as a single design element by the WFC solver. Sub-modules are named {name}_p0/N, {name}_p1/N, etc. All parts carry the full geometry for face analysis; only the first part materializes it. Supports auto-rotation (Rotate X/Y/Z) — the Solver expands all parts together.
- Module
- A named design element that carries geometry and six Faces. During WFC solving each Slot starts with all allowed Modules as candidates. See 3.2.1 Module.
- Module Name
- A lowercase string identifying a Module type. Multiple Modules sharing the same name are treated as Variants of the same type. See 3.2.2 Module Name.
- Module Rotations
- Generate rotated variants of a Module around each enabled axis (90°, 180°, 270°), producing up to 24 unique orientations. See 4.5.6 Module Rotations.
- Non-deterministic
- A Slot state where multiple Modules are still possible. Non-deterministic Slots have not yet been resolved by the solver.
- Observation
- The WFC step where the Slot with the lowest entropy is selected and assigned a single Module, chosen at random weighted by Module weights. See 1.2 The algorithm.
- Occurrence Count
- Counts how many Slots in the envelope contain a given Module Name. By default (Only Resolved = true) only Slots where that Module is the sole allowed option are counted; set Only Resolved to false to also include Slots that still allow the target Module alongside others. Useful for bill-of-materials and distribution analysis after solving. See 2.28 Occurrence Count analysis.
- Orientation
- Positive or negative along an axis. Combined with an axis (X, Y, or Z), orientation defines one of the six faces of a Grid Box or Module.
- Propagation
- The WFC step that cascades the consequences of an Observation through the Envelope. After a Slot is assigned a Module, neighboring Slots that can no longer legally host certain Modules have those candidates removed. This cascade continues until the Envelope stabilises. See 1.2 The algorithm.
- Random Seed
- An integer that initialises the pseudo-random number generator used during WFC Observation. The same seed with the same input always produces an identical result. Changing the seed explores a different solution path without altering any rules or weights.
- Rule
- An allowed adjacency between two Module Faces facing opposite directions. Rules are bidirectional: each adjacency only needs to be defined once. See 3.5.1 Rule.
- Slot
- A cell in the Envelope that holds a list of allowed Module candidates and their weights. Before solving, Slots allow multiple Modules; after solving, each holds exactly one Module (deterministic) or none (contradictory). See 3.4.1 Slot.
- Wave Function Collapse (WFC)
- An algorithm that fills a spatial envelope by alternating Observation and Propagation steps until all Slots are deterministic or a contradictory state is reached. See 1.2 The algorithm.
- Weight
- A per-Module probability value stored in each Slot. Higher weight increases the chance of that Module being chosen during Observation. Default weight is 1.0.
- WFC Solver
- The main Monoceros 3 component. Given a Discrete Assembly it runs the Wave Function Collapse algorithm and returns an output Assembly with solved Slot states, along with diagnostics and statistics. See 4.4.3 WFC Solver.