ARCHIMATIX

NODE-BASED PARAMETRIC MODELING FOR UNITY

Archimatix
Contents
1. First Steps
2. The Archimatix Library
3. Getting into Shapes
4. Just Meshing Around
5. Repeating Yourself
6. It’s All What You Node
7. Group Dynamics
8. Getting to Know Your Relations
Better

© 2017 Rory O’Neill, Roaring Tide Productions,

Archimatix
From the Desk of the Developer

Welcome to parametric modeling in

Unity with Archimatix!

Archimatix (AX) is a powerful node-

based parametric modeler extension for
Unity. Archimatix's purpose is to
enable artists and game developers to
quickly create rich worlds using
intuitive "smart models" capable of
generating hundreds of unique
architectural forms and typologies from
simple geometric primitives.

As the developer of AX, I am excited to walk you through your first steps in what should
prove to be an exciting in-editor modeling adventure!

If you have never tried parametric modeling, don’t worry, it’s not hard to pick up. While
quite different from brush-based, or topological, modeling, where you directly manipulate
vertices and faces, parametric modeling enables you to manipulate relatively few handles or
gizmos that alter the entire mesh in smart ways. Archimatix features non-destructive mesh
creation, allowing you to produce many variations of a form quickly, either as an iterative
design process, or as a way to stamp out multiple versions of the model to create a rich and
varied environment.

These three versions of Robot Kyle’s reception deck are generated from the same parametric model.
The variations are created by adjusting the handles visible in the center image.

As the result of several years of development and testing, Archimatix is a full-featured

extension to Unity. I hope you find this User Guide to be a fun and useful introduction to
parametric modeling in Unity with Archimatix!

Rory O'Neill, Ph.D.

Roaring Tide Productions Archimatix User Guide 1

 1. First Steps

Archimatix
1. First Steps
Archimatix is available in the Unity Asset Store. If you have
not installed Archimatix yet, please follow Unity’s
instructions for Importing from the Asset Store.

If you have already successfully purchased (thank you!) and

installed Archimatix, then you have taken your first step into
parametric modeling in Unity!

Congratulations!
Robot Kyle
For the next step, let’s instantiate a parametric object from remembers his
the Archimatix 3D Library. Our first example will be an very first step
interactive staircase?, the basic dimensions of which can be with Archimatix…
changed in realtime in the editor. To launch a “smart” stair and it was a doozy! But
from the Library, choose one from the main Unity menu. that was back during pre-
Alpha. Archimatix is much less
perilous now than it was back then!
Instantiate a Parametric Object Robot Kyle’s Skyplatform, 5 nodes.

Step 1.1: From the Unity menu, choose: City (below), 7 nodes.
GameObject > 3D Object > Archimatix > Stairs >
BasicStair

Roaring Tide Productions Archimatix User Guide 2

1. First Steps

You should now be looking at a basic stair

with a plywood material in your scene. You
can frame it using the F-key. Since it is
selected, it should also be displaying its
relevant control handles.

Step 1.2: Click on the point handle at the

top of the magenta stair Shape and
begin to drag it. In the Inspector, you will notice the relevant parameters
changing.

As you drag the handle around you should be able to create the following variations:

This handle is modifying two parameters at once: the stair length, or run, and the stair
height. The logic of the parametric object dictates what other parameters should change in
response to your modifications. For example, altering the run of the stairs re-calculates the
tread size, making the steps deeper.

You may have noticed that this run-height handle modifies the stair as fast as you can drag.
In the development of Archimatix, a key goal was to ensure that the modification of
parameters is realtime within the editor.

Let’s go ahead and modify another parameter of the stair.

Roaring Tide Productions Archimatix User Guide 3

1. First Steps

Step 1.3: Click on the point handle at the top of the lowest step of the magenta stair Shape
and begin to drag it. Notice that this handle controls the riser height of the steps,
with the number of steps adjusting to maintain the overall height value for the
stair. Try to replicate the variations shown below.

When first encountering new Library items, you may not be sure what the
displayed handles are supposed to control, but don’t be afraid to experiment
with them to explore the parametric behavior of the object – you can’t really
break them, after all; and if you do,
there’s always undo!
Robot Kyle is eager to show you
other types of stairs, but let’s be
patient and cover the basics
before climbing up to more
complex parametric
models!

Roaring Tide Productions Archimatix User Guide 4

The Talented Mr. Kyle
You may have notice that, when you created the BasicStair, another object appeared in the
scene: the one and only Robot Kyle!

This is actually a flat stand-in for the real Robot Kyle – a free asset from Unity Technologies.
While you can download Robot Kyle, or any other character, to help give your design space
a sense of scale, we include this 2D billboard as a lightweight alternative, while paying
homage to the character that has served as an Archimatix mascot throughout the
development process. You can follow the trials and tribulations of Robot Kyle on the
Archimatix community thread on the Unity Forums.

fr It was at that very moment fr Robot Kyle speaks in defense of fr Every now and
Robot Kyle began to wonder if he the last human. then, Robot Kyle
was indeed waterproof... stands in stupefied
awe of his own
Roaring Tide Productions Archimatix User Start Guide creations! 5
fr With no welcoming party fr Robot Kyle hesitates before the fr Hold on, Kyle. This
at the gate to greet him, Kyle's time portal. He remembers last thing isn't even at cruising
robot senses were on high alert. time! speed yet!

The Robot Kyle billboard, which is included with Archimatix as a Prefab, is automatically
instantiated in the scene when you create a new model. Being a standard GameObject, the
Kyle billboard can be translated as such. The billboard rotates automatically with the editor
camera.

Creating parametric objects while maintaining a sense of scale is important when working
with parametric modeling, since it is generally better to size your objects using their
parameters rather than using the scale transforms.

If you would prefer to work without Kyle’s omnipresence, you can click on the toggle at the
bottom of the Scene View to hide him. Or you can simply delete him from the scene.

The Scene View footer menu appears whenever an Archimatix object is selected. The footer
menu also includes grid snapping controls and the Stamp button.

Roaring Tide Productions Archimatix User Start Guide 6

Inspecting the Inspector
Not every parameter is represented by a handle in your scene. To see the full set of
parameters available for a selected object, you can refer to the Inspector.

From the Inspector, we see the parameters for the BasicStair model are listed under certain
headings such as BasicStair, Material and StairShape. This is because a parametric object in
Archimatix is described by any number of nodes in a node graph.

When you select a

parametric object in the
scene, the Inspector
displays the node that
represents that object,
as well as all of the
“upstream” nodes” that
feed into it. These headings represent nodes in
the Archimatix node graph.
Step 1.4: With the
BasicStair still
selected, take a look at the Inspector and begin
to manipulate some of its parameters.

The parameters we modified with the Scene View handles,

run, height and riser, are under the heading of StairShape.

We can use the Inspector to select a material for the

BasicStair. The default material for the model is listed near
the top of the Inspector. This default material will be
applied to any node that does not have its own material
defined. In this case, the BasicStair object does have its
own material node, listed below it in the Inspector.

Step 1.5: Drag a material from your Project Window to

the material ObjectField below the BasicStair
section of the Inspector. Alternatively, you can
click on the circle to the right of the
ObjectField to bring up the Material chooser.

Note: Archimatix does not yet support dragging and dropping a

material directly onto the object in the Scene View window, but
this is an upcoming feature.

Roaring Tide Productions Archimatix User Guide 7

Node Graph Editor (Sneak Peek)
What makes the BasicStair so smart? Underneath
the hood is a full-featured node graph that visually
encodes the logic of how the model is generated.
The image of the Node Graph Editor to the right
reveals that the parametric object BasicStair is
actually composed using only two nodes.

Node base classes can be Shapes, Meshers, Repeaters,

Tools and other bits of functionality to help you
describe the logic of a model. In the BasicStair
parametric object, the StairShape (instantiated
from the 2D Library) has its output fed into the
“Plan Shape” input of an Extrude node. The Extrude
node then takes the StairShape data and, based on The BasicStair is actually composed of two
the Extrude node’s parameter values, generates a nodes: a parametric Shape named StairShape
Unity mesh. This mesh output can then be fed into and an Extrude node named BasicStair. The
other nodes – such as a Repeater node – to duplicate output of the Shape is fed into the Plan input of
it according to the Repeater’s parameters. the Extrude node.

Not all that scary, right? We will revisit the node graph in Chapter 6, but for now, let’s see
what else is happening in the scene.

Hierarchy Window
You may have already noticed that a GameObject has
appeared in the Hierarchy window named “BasicStair (AX).”
This is the root GameObject that instantiates an AXModel
Component, the manager of all Archimatix smart objects
within that model. While you may have multiple AXModel
GameObjects in a scene, it is quite common to have very
few or even only one. When instantiating a new Library
item, the default behavior is to add these to your scene as
node sets within the existing AXModel’s graph.
Hierarchy view of a typical AXModel
Two children of the AXModel GameObject, the
GameObject. Generally, you will not
thumbnailCamera and thumbnailLight, are inactive, being be using the Hierarchy view to select
only used internally by the AXModel component to render the children of this GameObject, but
thumbnail images. generatedGameObjects is a temporary instead you will be working in other
container to hold GameObjects that are generated as the views, such as the Scene View, the
model and its parametric objects are manipulated. Inspector and the Node Graph Editor.

You cannot actually select a child object of the AXModel

Roaring Tide Productions Archimatix User Guide 8

root in the Hierarchy, because with parametric modeling, we do not operate on
GameObjects directly, but rather on nodes that generate GameObjects. Smart objects in
your scene behave like separate GameObjects, but are, in fact, ParametricObject nodes
within the model.

That’s enough basic anatomy for now! Since you are probably itching to manipulate some
more parametric objects, let’s call up a more complex example and explore another way to
instantiate Library objects.

Roaring Tide Productions Archimatix User Guide 9

The Archimatix Library

2. The Archimatix
Library Parametric modeling is made easier with
the help of the Archimatix Library.
With shelf space for a vast array of
While some Library items can be instantiated from
parametric props available for you to
the Unity menus, visiting the Archimatix Library via check out (and check in!), both 2D and
its own window is a great way to see the full holdings 3D parametric objects archived in the
of the Library at any given time. Archimatix ships with Library are searchable.
some example Library items to help get you started,
and your Library will grow over time as you add your
own parametric props and share props with friends, and as packs of parametric props
become available from the Asset Store.

To get a better sense of how this works, let’s open a Library window.

Step 2.1: Create a new scene and then open the Library window via the main Unity
menu: Window > Archimatix > Library

When the Library window opens, feel free to dock it

Roaring Tide Productions Archimatix User Guide 10

The Archimatix Library

within the Unity Editor interface.

Roaring Tide Productions Archimatix User Guide 11

2. The Archimatix Library

The Library Window

The Library window displays a grid of the items
archived in the Library. Each item may be thought
of as a Parametric Prop, a smart object that you
can add to your model, complete with its own
Scene View handles as parameters.

You can search and filter the items in the Library

by keywords and other metadata tags associated
with each item.

To try the Library out, let’s

appease Robot Kyle by
checking out the
RicketyStaircase item from the
Library, adding it to our scene.

Step 2.2: At top of the Library

window, click in the
search field and type “stair.”

Step 2.3: In the filtered results now displayed,

locate the RicketyStaircase and click on
it.

The RicketyStaircase should now be selected in your scene.

Unlike the BasicStair, which had only one Mesher node (the Extrude), this RicketyStaircase is
more complex, composed of several Shapes, Mesher and Repeater nodes. These parts are all
brought together in a Grouper node.

Step 2.4: Click and drag the red, green and blue
handles visible around the
RicketyStaircase to control its run, height
and width parameters.

You should be creating different variations of the

RicketyStaircase. Notice that the step treads, rail
posts and side boards are being “jittered” with
Perlin noise to give that rickety effect.

The boards are created by a repeating 2D Rectangle

with Jitter, and then extruded.

Roaring Tide Productions Archimatix User Guide 12

2. The Archimatix Library

You can find more handles to control the

RicketyStaircase by clicking on various parts
of the model.

Step 2.5: Click on one of the stair rails.

Click and drag the point handle
at the top end of the rail to
modify the run and height of the
staircase.

It is fun to manipulate multiple parameters

with one handle. Like with the BasicStair, this handle at the top of the rail is modifying both
run and height.

Step 2.6: Click on the sideboards of the

staircase.

The handles that appear when you click on

the sideboards are numerous because they
are made of a number of subnodes. Note
the stair profile Shape with top point
handles at the top and bottom of the stair.

Step 2.7: Click on the control point on

the first (lowest) step and drag to
alter the rise parameter (and the
number of steps).

Let’s alter the spacing of the sideboards

themselves.

Step 2.8: Drag the cell size handle of the

LinearRepeater2D that spaces the
sideboard Rectangle Shape. Also,
try dragging the cyan circle to
rotate the repeater.

You should see the boards changing in real

time as you adjust the repeater handles. This
RicketyStaircase prop is driven by two
Repeaters, the LinearRepeater2D to space the
sideboard Shape and a StepRepeater to
distribute the tread boards. As you may have
guessed, the node graph for the RicketyStaircase is a bit more elaborate than that for the
BasicStair.

Roaring Tide Productions Archimatix User Guide 13

2. The Archimatix Library

Before leaving the Library, let’s check out one more feature of working with Library items:
creating stamped or “frozen” versions of models.

Step 2.11: Create a new scene. Find the ArtsAndCraftsChair in the

Library and click on it to add it to your model.

Step 2.12: Modify the chair by dragging its handles.

Step 2.13: Click on the “Stamp” button in the footer control panel at
the bottom of the Scene View.

At this point you have two chairs, one that is a “frozen” copy and the original parametric
object, which remains selected. The frozen copy no longer needs Archimatix.

Step 2.14: Move the parametric object away using the Transform handle. Click anywhere on
the object and manipulate the handles
that are displayed.

Archimatix features “cycle selecting,” whereby

repeatedly clicking on an object selects
“downstream” nodes until eventually the model
itself is selected. If you would like to select the
entire parametric object at anytime, you can do so
in the Hierarchy window.

To see stamping in action, please try this tutorial.

Roaring Tide Productions Archimatix User Guide 14

Getting Into Shapes

The Last Human thinks that Robot Kyle

has him under surveillance, when, in
fact, Kyle is contemplating what merged
Shapes define the cross section of the
skyplatform above.

3. Getting into Shapes

Although Archimatix is an amazing tool for
generating 3D meshes, one of its key strengths is
its ability to manipulate 2D Shapes. With rich
Shape modification features, including thicken,
offset, rounding and boolean merge, Shapes provide a
powerful basis for generating 3D forms.

In Archimatix, Shapes too are parametric objects.

As we already saw with the stair Shape, when you
select a Shape, or an object that uses a Shape, you
will see Shape handles.

Shapers are nodes that operate on Shapes.

These three arch variants are really the same

ArchShape checked out from the Library. They have
The skyplatform above is made with a
been created by playing with the point handles.
composite Shape (the product of a
Now let’s explore the power of Shapes. boolean addition and subtraction of
several simple Shapes) as a section swept
around a Plan Shape.

Roaring Tide Productions Archimatix User Guide 15

3. Getting Into Shapes

This time, instead of selecting an object from the Archimatix Library, let’s start with a demo
scene. Smart Objects' states are saved in the scenes themselves. Loading a scene containing
Smart Objects also loads their parametric relationships and values.

Step 3.1: Using Unity’s Project panel, open the scene:

Archimatix/Scenes/SciFiPlatform

This scene has one Archimatix models in the Hierarchy

called AXModel. This is the main GameObject that
manages the parametric model in the scene. If you
expand the foldout, you will see a thumbnailCamera and a
thumbnailLight, both of which are inactive and are used
to render node thumbnails. The generatedGameObjects
item holds all of the temporary GameObjects created by
Archimatix. You can not select these temporary objects
here will select the node that generated them.

Step 3.2: Select the platform in Scene View to reveal its

handles.

Roaring Tide Productions Archimatix User Guide 16

3. Getting Into Shapes

Step 3.3: Drag the magenta point handles to create variations of the SciFiPlatform like
these:

Don’t forget that you can grab the Circle’s centroid to displace it.

This isn’t the first time

Robot Kyle has needed to
take a leap of faith… and for
some reason, he thinks it
won’t be the last!

Roaring Tide Productions Archimatix User Guide 17

 Fighting an overwhelming desire to turn back, Robot Kyle sails cautiously
toward the Island of the Robot-With-No-Name. He knows in his mechanical
heart that these towering edifices are merely I-Shapes fed into an Extrude
Mesher, but their sheer verticality and oppressive mass unnerve him as they
pierce the horizon.

4. Just Meshing Around

Archimatix has four main types of Meshers that transform
2D Shapes into 3D forms. The Polygon simply triangulates a
2D Shape, turning it into a flat mesh. The Extrude Mesher
takes a Plan Shape and lofts it to a certain height. The
Lathe takes a single Section Shape and spins it around an
axis at a certain radius. Finally, the PlanSweep Mesher takes
a Section Shape and sweeps it around a Plan Shape.

Meshers are represented

in the node graph by the
above nodes.

Roaring Tide Productions Archimatix User Guide 18

4. Just Meshing Around

Archimatix Meshers use the logic of their geometry to automatically generate uv’s,
determining whether faces appear smooth or faceted.

You can control how the normals respond to the curvature of the input Shapes, as well as
define the break angles separately, in Plan and Section. The image above shows identical
columns with different break angle settings. The first column has high break angle values;
the middle two have high break angle values on only one axis; and the last column has low
break angle values on all axes. You can also scale and shift textures that you have applied to
the sides and/or caps for these meshes.

These controls are only accessible from the Node Graph Editor, which will be introduced
shortly!

But first, let’s play with these Meshers to see how they behave.

Roaring Tide Productions Archimatix User Guide 19

4. Just Meshing Around

Step 4.1: Open the scene Archimatix/Demo Scenes/MeshingAround.

Step 4.2: Click on the Extrude Mesher and manipulate the point handle for the radius of the
Circle.

When the Circle is smaller, the Square is dominant. With a bigger radius, the Circle is dominant.
As you vary the radius of the Circle, the PlanSweep object changes as well. This is because
the same Plan Shape is being fed into both the Extrude and PlanSweep Meshers.

A sneak peek at the node

graph for this model shows
that, indeed, the Plan Shape
is shared by the Extrude
and the PlanSweep, while
the Section Shape is shared
by the PlanSweep and the
Lathe. The red connector is
linking the height
parameters of the Section
Shape and the Extrude
Height.

Roaring Tide Productions Archimatix User Guide 20

4. Just Meshing Around

Step 4.3: Select the Lathe object and modify the point handle at the top of the Section.

Step 4.4: Drag the point handle at the midpoint of the Section curve of the Lathe.

The midpoint of the Section is drawn outward. The midpoint of the Section is drawn inward.

The heights of all three objects adjust together. This is because the Extrude Mesher’s Height
parameter is “related” to the height parameter of the Section Shape. The Relation between
them (expressed by the red connector line in the Node Graph Editor image on the
preceding page) has “equals” expressions. We’ll learn more about Relations and their
expressions in Chapter 8.

It’s fun to play with the Section curves of the Lathe and the PlanSweep objects, but what
about poor old Extrude – will it always be consigned to sheer walls? As it turns out, Extrude
has some extra handles up its sleeve for tapering and beveling.

Let’s take a quick look at these Extrude handles.

Roaring Tide Productions Archimatix User Guide 21

4. Just Meshing Around

Step 4.5: Create a new scene and instantiate the BevelBox from the Library.

X-dir: Taper Extrude Height

X-dir (alt)
BevelRadiusTop
Y-dir: Extrude Height
Plan Shape
point handles

Bevel Segments

X-dir: Offset
Y-dir: BevelRadiusBottom

Although it may look like a more complex object, the BevelBox Library item is really just an
Extrude Mesher with the Bevel Top radius and Taper adjusted. The depression in the Top Cap
is set from the Lip Top parameter in conjunction with the Lip Edge parameter found in the
Inspector.

Step 4.6: Vary the handles to make variations like these:

Robot Kyle is a little disappointed that these models are not as bouncy as they look!

Roaring Tide Productions Archimatix User Guide 22

4. Just Meshing Around

Taking Lathe for a Spin!

Circular forms are common in nature and in

architecture. The Lathe Mesher is useful for creating
round objects, such as barrels, tables and towers. It
rotates a single Shape around a center axis at some
radius.

A great example of a lathed object is a tower with a

dome.

Step 4.7: Open the scene TowerWithOnionDome

from the folder Archimatix/Scenes.

Step 4.8: Click on the dome of the tower and drag

the top handle of the section curve to
flatten the dome a bit.

This curve is a parametric Shape with a certain logic,

namely, it offers only two parameter handles (at either
end of the Shape) and makes assumptions about how
the curve between the two points should be generated.
Although this parametric curve is not as general or
flexible as a FreeCurve, it is likely to always produce
results that look like an “onion dome,” such as those
found in Eastern Europe or the Near East.

Step 4.9: Click on the middle of the brick shaft of

the tower and drag the center handle.

The center handle is a Bezier handle, so you can drag

its center point or the points at the end of the tangent
handles that extend from the central point.

This Shape is a FreeCurve that allows you to manipulate

any vertex handle in a free-form way. While it is the
most general type of Shape that Archimatix offers,
there are no assumptions about the logic of the final
outcome, meaning that the design is completely up to
you. Over time, you will develop a sense of when to use
a parametric Shape or a FreeCurve Shape.

The Lathe is a common and powerful tool for generating standard Unity meshes from Shapes.
A more general and powerful Mesher is the PlanSweep Mesher.

Roaring Tide Productions Archimatix User Guide 23

4. Just Meshing Around

Meshes with Sweeping Changes

The PlanSweep Mesher is perhaps one of

Archimatix’s greatest features. It sweeps a
Section Shape around a Plan Shape.
Combined with ShapeMerger, the results
can be particularly exciting!

Step 4.10: Open the scene

PlanSweepTube from the folder
Archimatix/Scenes.

Step 4.11: Click on the yellow tube to reveal

the tool for the tubes Section Shape.

Step 4.12: Use the center point handle of the disc to

drag the yellow tube in and out of the
purple tube.

Roaring Tide Productions Archimatix User Guide 24

Ah, per chance to dream… of
GridRepeaters!

5. Repeating Yourself
Repeaters in Archimatix allow you to distribute instances of
any AX-generated mesh or Unity Prefab in various
patterns, including grids, radial arrays and symmetrical
pairs. We have already seen an example of 2D Repeaters in
the sideboard of the RicketyStaircase. Now, let’s explore
repetition in 3D.

Roaring Tide Productions Archimatix User Guide 25

5. Repeating Yourself

The early 20th-century architect Le Corbusier explored the possibilities of new building
materials such as concrete. Calling a house a “machine for living,” he proposed the Maison
Dom-ino, a structure that represented the essence of domestic space: floors, columns and
stairs. While the Domino House looks a bit drafty, this essential structure provides a great
example of repetition using a GridRepeater
and a FloorRepeater.

Step 5.1: Create a new scene and

instantiate the DominoHouse
from the Library.

Step 5.2: Click and drag on the green

handle at the top of the structure.

As you drag the handle upwards, the

FloorRepeater SizeY parameter increases and, to
maintain a preferred story height, the
FloorRepeater adds more floors. The
actualStory heights vary slightly as the number
of floors increases. Notice how the stair instances
grow or shrink to match the story height.The Extrude
Height of the GridRepeated column is increased to match the
overall SizeY.

Roaring Tide Productions Archimatix User Guide 26

5. Repeating Yourself

Repetition with a Plan

A powerful form of
repetition in Archimatix
uses a Plan Shape to
distribute objects along its
path. For example, a window
unit can be placed around the Shape
of a building.

Step 5.3: Open the scene VillaRomano from

the Scenes folder located in the Archimatix
folder.

Step 5.4: Click on the foundation plinth of the building to display

the handles of the Shapes that are merged to make the Plan of
the building.

The Plan of this villa is a composite of two Shapes, an I-Shape and a

Cross Shape. The Cross Shape is used as the plan for the second
story of the building, and it is also merged with the I-Shape to
form the first story Plan.

Step 5.5: Adjust the handle at the side of the Cross Shape
and drag it toward the center until only one arch
is on the front face of the upper story.

Step 5.6: Adjust the handle at the end of the Cross Shape and drag it
outside of the perimeter of the I-Shape.

When you drag the end handle of the Cross Shape, you should notice that the first
story Plan is now the combination of the two Shapes.

Step 5.7: Continue to adjust various handles to make alternative forms such as the ones
depicted below.

Roaring Tide Productions Archimatix User Guide 27

5. Repeating Yourself

Flat Out Repetition

Most of the 3D Repeaters have 2D

counterparts. These 2D Repeaters
are particularly powerful for
elaborate Shape merging. A good
example of this using a PlanRepeater2D
node included in the Scene folder is
BastionMerge.

BastionMerge uses a Plan Shape that

represents a sort of castle wall outline and
another plan for a bastion that gets repeated at
each node of the wall Shape. In the example at right, the
fortress plan is a FreeformCurve, and the bastion Plan is a square.
The PlanRepeater2D generates a new Shape that is the product of
each Rectangle Shape copied and transformed to each vertex of the
fortress Plan. Then the fortress Plan itself is “thickened,” producing a composite Shape seen
on the right in the diagram below. This composite plan is then extruded.

Step 5.8: Open the scene BastionMerge from the Scenes folder located in the Archimatix
folder. In the scene, you will find three versions of the BastionMerge fortress.

Roaring Tide Productions Archimatix User Guide 28

5. Repeating Yourself

Step 5.9: Click on the stone pathway atop the main wall of the first (simplest) fortress.
When the Shape handles appear, click and drag a node of the wall Shape to make
variations similar to the ones depicted below. Clicking on purple point handles
will move a vertex, while clicking and dragging a cyan handle will create a new
vertex.

Moving vertices. Crossing vertices. Adding vertices and

adjusting the
Rectangles’ handles.

Notice that, as you modify the Plan Shapes of the fortress

wall and the bastion Rectangle, the outline of the
composite Shape is expressed in the parapet wall,
which is parallel to the outline and forms a
continuous path through the bastions. If this
fortress had used a 3D PlanRepeater, each bastion
would have its own parapet. While the latter may
be preferred in some cases, the power of 2D
Repeaters is in the generation of complex
forms. Comparison
between fortresses using a PlanRepeater2D (left)
When the “thickened” wall Shape is subtracted versus a 3D PlanRepeater (right).
from the repeated bastions, a more distinct
pathway is made with openings in solid
bastions that are aligned with the wall. In the
other two fortress variations in the scene,
more Shape merging has allowed for separate
bastion walls that have openings that respond
to the fortress wall Shape.

In the next chapter, you will be introduced to

the Node Graph Editor. Once you are familiar
with editing the logic of forms using nodes, it
will be useful to return to the BastionMerge
scene and see how it was organized.

Roaring Tide Productions Archimatix User Guide 29

6. It’s All What You Node
As we mentioned earlier, the parametric
objects that you have been trying were all
created with the Node Graph Editor. It’s
high time we pull back the curtain and
see how a castle, such as the one depicted
above, can be modeled with relatively
few nodes.

To get started, let’s open up the Node

Graph Editor window.

Step 6.1: Create a new scene and open the Node Graph
Editor window with the Unity menu by choosing Window > Archimatix >
Graph Editor.

Roaring Tide Productions Archimatix User Guide 30

 6. The Node Graph Editor

Anatomy of the Node Graph Editor Window

Before jumping in with node creation, let’s take a look at the main areas of the Node Graph
Editor window.

Model Menu Model Output

2D Library
Nodes

Function
Nodes

3D Library
Nodes

Detail Level
for LOD
Graph Tools
Canvas Model Statistics

The Node Graph Editor window is organized as a canvas area surrounded by tool menus. To
the left and right of the canvas are menus which are used to add nodes to the canvas. The
left sidebar features items from the Archimatix Library. Theses items are divided into 2D
and 3D items. The right sidebar displays functional nodes, nodes that take some input,
process that input and then make the results available to other nodes through an output
socket.

Along the top you will find model controls. The Group Address is a “bread crumb trail” that
expands as you open subnode groups. The three buttons on the upper right give you options
for model output. The “Build” of the model usually happens automatically when you
complete a parameter change. The “Stamp” button creates a “frozen” version of the model
that no longer needs Archimatix in the project. A stamped model can then be modified in
other modeling packages such as ProBuilder or Megafiers. Finally, the Prefab button saves the

Roaring Tide Productions Archimatix User Guide 31

6. The Node Graph Editor

model’s meshes to Unity’s AssetDatabase and creates a standard Unity Prefab. This Prefab is
also “frozen” and no longer parametric.

The bottom bar under the canvas features tools for cleaning up the graph in the canvas and
provides quantitative feedback about your model, such as vertices and triangle counts.

You will be using the Node Graph Editor window a lot

as you create smart models with Archimatix. Take a
moment to find a place to dock it. It works well to have
the Scene View window and the Node Graph Editor
window the same size and side by side. The image on
the right provides an example layout suited to modeling
with Archimatix.

Now that you have an overview of the Node Graph

Editor, it’s time to jump in!

Step 6.2: Start a new scene and click on the Circle node icon in the left sidebar menu.

A Circle node will appear on the canvas and be framed in the Node Graph Editor window.
The 2D circle it produces will be framed in your scene.

Roaring Tide Productions Archimatix User Guide 32

6. The Node Graph Editor

You can pan and zoom the canvas to get a better view of the node palette for the Circle node
you instantiated.

Step 6.3: Use the scroll wheel on your mouse to zoom the canvas in and out. On a touch
trackpad, you can use two-finger scrolling to zoom. Try RMB-drag to pan the
canvas around.

Now that we can zoom into the Node Graph Editor, let’s take a closer look at the Node
Palette.

Anatomy of a 2D Node Palette

Node Type Web Link

Title Bar for more Info

Active Node
Toggle Palette
Menu

Transforms Axis
Foldout Orientation

Geometry
Control Output
Parameters Socket
Foldout

Output Open / Close

Modifiers Shape Toggle
Foldout

Vertice Resize
Count Palette
Thumbnail

Roaring Tide Productions Archimatix User Guide 33

6. The Node Graph Editor segs

The Circle node has 16 sides, or segments, and a radius of 2 units,

by default. Let’s adjust these values. radius

Step 6.4: Open the Geometry Control Parameters Foldout and modify
the radius to 2.5 and segs to 6 to make the Circle a hexagon.

You will notice that some parameter fields in the node palette
are redundant with the fields listed in the Inspector, with an
important difference. Each parameter in the Node Palette has a
socket on either side of it. These sockets, which are color-coded
based on the type of parameter data (red: float; blue: int; yellow:
bool) allow you to link parameters from this node to parameters
from other nodes.

The radius and segs parameters are the two basic values needed to
generate vertices for the Shape. These vertices constitute the final output
of the Shape.

The rectify parameter comes in handy when dealing with an odd number of segs. If the Shape
is rectified, the Circle is turned so that one facet is parallel to the
X-axis, rather than starting with a vertex falling on the X-axis.
This comes into play for Shapes with small segment counts, such
as a pentagon.

The handles and Logic foldouts, which enable you to customize

or create your own Shape behaviors and control handles, are
covered in the advanced topic of coding parametric Shapes using
AX Script. More information on this topic can be found here.

Roaring Tide Productions Archimatix User Guide 34

6. The Node Graph Editor

The Circle Shape has a Circle handle, which features two sub-handles: a point handle locked
to the X-axis, which controls the radius parameter, and a Tangent handle that is
perpendicular to the X-axis and controls the segs parameter. The rectify parameter does not
have a scene handle, and can only be checked in the Inspector or on the node palette.

Each node in Archimatix has specific

parameters, handles and logic. While
often the specifics of a node can be
learned quickly enough through
experimentation, many nodes have
documentation pages at the support
site, archimatix.com.

To quickly get to the

documentation for a node
you are working with, you
can click on the
information icon just below
the title of the node. In the
example shown in the image on the
right, a click to the information icon
on the Circle node has popped up a
Web browser and directed us to the
URL for the Circle Shape’s
documentation.

Step 6.5: Click on the information icon for

the Circle Shape and familiarize
yourself with the Archimatix
support site.

If a specific node does not have a

page yet, then the information icon
will link to a general page about that
class of node – for example, the
Circle is a Shape node.

Next, let’s make a mesh of this thing!

Roaring Tide Productions Archimatix User Guide 35

6. The Node Graph Editor

Meshing with the Node Graph

Having a 2D Shape node in the scene is a great start, but nodes don’t do much in isolation.
Generally two or more nodes work together to generate meshes. As it is with any team
organization, communication is important. Nodes communicate with each other in two
ways: 1. Connections between inputs and outputs; and 2. Relations that are defined by
mathematical expressions. As nodes are connected to each other in non-mutually exclusive
ways, a network of logical relations forms, making a graph data structure. While a graph may
seem like a challenging thing to master, it is really not that difficult. To start, we can just
keep creating nodes and connecting their outputs and inputs.

Since we have the Circle in the scene already, let’s use it to generate a mesh by feeding its
output to the input of an Extrude node, a Mesher node that takes an input Shape, doubles the
Shape at some extrude distance or height, and creates a mesh between the two. As we shall
see, the product of this nodal teamwork will be a Cylinder.

Step 6.6: Click on the purple button, or socket, on the lower right side of the Circle node
that is labeled “Output Shape.” Release the mouse button, and move the mouse to
the right sidebar. Use your scroll wheel to scroll through the list of nodes in the
sidebar until you see the Extrude node, and click on it.

Roaring Tide Productions Archimatix User Guide 36

6. The Node Graph Editor

A new Extrude node will appear in your graph with a connection line automatically rigged up
between the Circle node’s output and the Extrude node’s “Plan” Shape input socket.

With the addition of the Extrude node and the input-output connection between them, you
have officially created a graph!

Now we see that the Cylinder Library Item is really just a two-node graph created in the
Node Graph Editor.

You may click and drag on the window title bar or thumbnail of either node to rearrange
them on the canvas. As you drag, the node moves freely. When you let go, it will snap to the
underlying canvas grid.

In the Scene View, you will notice that the Extrude is displaying its handles and the handles
of the upstream Circle node (as we saw in the SciFi Platform and the BevelBox examples
already). But now that we have the Node Graph Editor open, we have more controls
available in the node palette. For example, we can see the Material inputs and the mesh
output parameters.

Let’s zoom into the Extrude node to take a closer look at it.

Roaring Tide Productions Archimatix User Guide 37

6. The Node Graph Editor

Anatomy of an Extrude Node

Open/Close
Inputs Foldout Shape
Toggle
Input
Shape
New
MaterialTool
Material Node Button
Inputs

Output Mesh
Socket

Physics
Foldout
Combine Meshes
Toggle

Vertices &
Triangles Stats

With the Inputs foldout expanded, we can see various options for inputs. In the case of the
Extrude node, we have a Plan Shape and two Material inputs. The first Material input will be
the main material for all the surfaces of the Extrude. A MaterialTool node connected to the
Top Cap Material input will be the material for the Top Cap and Bottom Cap of the Extrude.

When clicked, the new MaterialTool node button will create a new MaterialTool node and
connect it to the Extrude node. Alternatively, you can connect a MaterialTool node already in
the graph to either of the MaterialTool node inputs.

The “Combine Meshes” toggle signals to the node that it should combine any meshes that it
creates into a single mesh per material. In the future, there will be an option to have one
mesh with submeshes for each material.

The Physics modifiers found in the Physics foldout allow you to specify the type of collider
you would like the output of the Mesher to have. There is also an option to add a RigidBody
and make it kinematic.

Roaring Tide Productions Archimatix User Guide 38

6. The Node Graph Editor

Comparing Input Foldouts

Unlike the Shape node, Mesher nodes like Extrude have multiple inputs. The node’s inputs
help to define its particular mesh-generating functionality. For example, the Extrude Mesher
needs a Plan Shape on which to operate, and it can optionally take a main MaterialTool and a
Top Cap Material as inputs.

We can quickly get a sense of the types of Meshers we have in Archimatix by comparing their
inputs.

With additional complexity, we need more Shape and material input options. Otherwise,
looking at the lower half of the four Meshers, we see that they all share an Output Mesh,
Combine Mesh toggles and a Physics controls foldout.

Roaring Tide Productions Archimatix User Guide 39

6. The Node Graph Editor

Backfaces

Meshers allow you to choose which surface you would like to be visible. For example, in an
Extrude Mesher, you can disable the Top Cap and Bottom Cap. You can also choose to turn on
the Backfaces if you want a thin-shelled form or a thin railing. Turning Backfaces on is also
convenient for inverting meshes to use as interior environments.

Step 6.7: In a new scene, instantiate a

Rectangle from the 2D Library.
Connect the Rectangle’s output to an
Extrude node item in the right
sidebar menu.

You can have the Sides and the Backfaces visible

together, but the caps are only either normal or
inverted. They are inverted only when the
Backfaces are on.

Step 6.8: Expand the Controls foldout on the Extrude node, and turn the
Sides off and the Backfaces on.

You now have the beginnings of an interior model. If you orbit the model
in the scene, you will be looking into the space, but without seeing any of
the exterior surfaces of the walls or floors.

Step 6.9: Instantiate a Circle Shape and connect its output to the Plan
input of the Extrude node with a RMB-double-click (Windows)
or command-click (OS X), automatically creating a ShapeMerger
node in between. Move the Circle and resize it to build out the
interior space.

You can continue to add Shapes, making the interior space larger and
larger.

You cannot currently cut holes in the sides of

an Extrude. Instead, Archimatix works with a
philosophy of 2D Boolean operations and an
additive process of meshes. This is closer to
real-world building practices, where a window
is not really cut out of a wall, but, rather, the
mass of the wall is built up and the window
opening an area where no material was added.

Let’s take a look at an opening made through

2D Shape merging.

Roaring Tide Productions Archimatix User Guide 40

6. The Node Graph Editor

Meshing Off the Rails

In addition to exterior and interior models, a common case that uses both at the same time
is a thin railing. Archimatix is well-suited to making thick railings, but for buildings with a
low level of detail, a thin railing can save triangles.

Step 6.10: From the scene on the previous page, turn the Top Cap and Bottom Cap off and
turn the Sides on, leaving Backfaces on as well. Adjust the height of the Extrude to
be about waist-high on Robot Kyle.

You can continue to add Shapes to the ShapeMerger and move them around or modify their
parameters. But, at the moment, we see that there is no way for Robot Kyle to get inside of
this fenced area.

The simplest way to open the fenced area is to open the Plan Shape. This can be done in one
of two places, either in the Difference output of the ShapeMerger or in the Plan input of the
Extrude. It makes most sense to leave the ShapeMerger output alone, since that Shape could
be reused to generate a floor under the fenced area. This leaves the Plan input as the best
option. Altering a Shape at an input point is essentially a just-in-time alteration that has no
effect on the upstream source Shapes.

Roaring Tide Productions Archimatix User Guide 41

6. The Node Graph Editor

Step 6.11: Click on the Open/Close Shape toggle in the Extrude’s Plan input parameter.

We see that, by opening the Plan Shape, we now have a part of the rail missing, in this case,
right next to the quarter-circle. The problem with simply opening the Shape is that we
cannot easily control where the opening is or allow for multiple openings. To remedy this,
we can use the DifferenceRail of a new ShapeMerger to intentionally cut out parts of the rail.
The DifferenceRail is a Shape composed of the lines of the solid Shapes in the ShapeMerger
inputs without any lines contributed by the void Shapes.

Step 6.12: Click on the connector cable from the ShapeMerger output to the Extrude. While
it is selected, hit the Delete key to remove it (Cmd-Delete on OS X).

Step 6.13: Click on the ShapeMerger

to select it, and then click
on the ShapeMerger icon
in the right-hand sidebar
menu. A new ShapeMerger
will be created and
automatically connected
to the Difference output of
the first ShapeMerger.

Roaring Tide Productions Archimatix User Guide 42

6. The Node Graph Editor

Now you should have the original ShapeMerger

feeding into a new ShapeMerger. It is with this
new one that we will trim out openings using a
new void Shape.

Step 6.14: With the new ShapeMerger selected,

instantiate a Rectangle from the 2D
Library items in the left-hand
sidebar. The Rectangle will be
automatically fed into the new
ShapeMerger.

At first, the Rectangle will probably be too large

and leave little of your Shape left.

Step 6.15: Resize the Rectangle so that it is

removing a sliver of your Plan Shape.

Step 6.16: Click on the checkbox to the left of

the DifferenceRail output to display
the result of that Boolean operation.

Using the original merged Shape, we now see

the DifferenceRail, an “Open” Shape that is
essentially a “rail.” Such a rail Shape can be used
to create thin and thick railings and walls with
openings.

Note that the checkbox that you clicked to

display the DifferenceRail output of the merge is
only for displaying that output parameter’s
Shape in the node’s thumbnail. You can hook
different nodes simultaneously to any and all of
the outputs of the ShapeMerger.

We can use the rail Shape we created in various

Meshers, as we shall see in some examples
presently.

Roaring Tide Productions Archimatix User Guide 43

6. The Node Graph Editor

Step 6.17: Connect the DifferenceRail output of the new ShapeMerger to the Extrude node.

Now Robot Kyle will be able to enter the railed area, but we had better add a floor to
provide some footing. This is where the original ShapeMerger output can come into play and
demonstrate how powerful the non-mutually exclusive aspect of the node graph can be.

Step 6.18: Click on the Difference output of the first ShapeMerger, and then click on the
Extrude icon in the right-hand sidebar menu.

Step 6.19: Click and drag the lower green point handle on the Extrude to offset the Plan so
that it is larger than the railing.

Roaring Tide Productions Archimatix User Guide 44

6. The Node Graph Editor

Step 6.20: Adjust the height of the Extrude until it appears to be a thin floor slab.

Step 6.21: Select the original Rectangle in the Node Graph Editor and make the fenced-in
area larger, then select the new cutting Rectangle and make the opening larger.

1 2

We can see that, as the node graph becomes more developed, we can modify various handles
in the scene with a ripple effect. For example, at this point, modifying the first Rectangle’s
handles alters both the railing and the floor.

Roaring Tide Productions Archimatix User Guide 45

6. The Node Graph Editor

Let’s use the DifferenceRail Shape to create a thick handrail atop the current surface.

Step 6.22: Click on the DifferenceRail to start a connection and then scroll the
right sidebar down until you see the PlanSweep_Plan Mesher icon, and
click on it. A connection will automatically be created. A mesh will
not appear in the scene until we provide the PlanSweep node with a
Section Shape.

Step 6.23: Instantiate a RoundedRectangle from the 2D Library sidebar and

connect the output of this node to the Section input of the PlanSweep.

The DifferenceRail output is now used to generate two different meshes. The PlanSweep
Mesher is currently at the base of the railing and is too large to be a handrail. To make the
RoundedRectangle Shape smaller, it is far better to adjust its parameters than to scale it using
the Shape’s transform controls. This is because, in parametric modeling, the values of
parameters are important in building logical relationships. If we simply scale the Shape, then
the parameters, which retain their value, will not reflect the size.

Step 6.24: Select the RoundedRectangle node

in the Node Graph Editor
window and hit the “f ” key to
frame the node in both the scene
and in the Node Graph Editor.

Step 6.25: Adjust the RoundedRectangle’s

handles in the scene to make the
Shape smaller, and move and
rotate the centroid to lift the
Shape up to the top of the rail.

Roaring Tide Productions Archimatix User Guide 46

6. The Node Graph Editor

Now let’s change the material of the rail sides.

Step 6.26: On the Extrude node palette for the rail sides, click on the icon button to the
right of the Material input parameter. This will automatically add a MaterialTool
node to the graph and connect it to the Material input.

Step 6.27: On the MaterialTool node palette for the rail sides, click on the button to open
the Unity material browser window. Choose AX_BrickWall. You can use the scale
and shift parameters in the MaterialTool node Controls foldout to adjust the look.

Step 6.28: In a similar way, add materials to the PlanSweep node for the handrail and to the
Extrude node for the floor slab, perhaps AX_Wood01 and AX_StriatedMarble,
respectively.

Roaring Tide Productions Archimatix User Guide 47

6. The Node Graph Editor

If we want to change this model to be more like a room with door openings, we can extrude
the rail walls up.

Step 6.29: Click on the rail walls in the scene or

on the Extrude node in the Node
Graph Editor. Click and drag the
green knob in the scene to increase
the height of the wall.

Step 6.30: Click on the Difference output of the first ShapeMerger and connect it to a new
Extrude node from the right sidebar menu. Move the new Extrude node over near
the rail walls’ Extrude. Connect the output of the brick material to the new
Extrude.

Step 6.31: Turn the Top Cap and Bottom Cap of the new Extrude off and the Backfaces on. In
the scene, lift the new Extrude up until it is atop the rail walls. Adjust the height
of the new Extrude.

Roaring Tide Productions Archimatix User Guide 48

6. The Node Graph Editor

Repeating Repeating

In Chapter 4, we looked at the Domino House,

which used Repeaters to allow us to expand the
building, adding floors and columns as we dragged
the Size handles. Now, let’s take a quick look at how
to use Repeaters in the Node Graph Editor to make
our own parametric building. To do this, we will use
parametric props from the Library and connect
them into a GridRepeater to make a sort of castle
with arched openings.

Step 6.32: In a new scene, instantiate a TowerWithOnionDome from the 3D

Library left-hand sidebar.

Step 6.33: Connect the output of the tower to a GridRepeater_Node in the right-
hand sidebar node menu.

Feel free to open the TowerWithOnionDome Grouper and see how it was assembled with its
own set of nodes, including FreeCurve, Lathe and molding profiles. However, part of the
beauty of Grouper and Library items is the ability to work with pre-formed parametric
objects to give you a head start on environment building.

Roaring Tide Productions Archimatix User Guide 49

6. The Node Graph Editor

Step 6.34: Hit the F key to frame the grid of towers in the scene.

The default grid sizing is based on the size of the

object that is initially connected to it. You can
modify this sizing in the scene by dragging the
orange point handles. The key parameters of the
GridRepeater are the overall Size and the size of a
typical Bay, or cell of the grid. Sizes in the X and Z
axes are controlled independently.

When you adjust the Bay size, the Size increases.

When you adjust the Size, the additional bays are
added, while the Actual_Bay size remains as close as
possible to the Bay that had been set.

The parameters are not found in the GridRepeater

node, but in RepeaterTool nodes that feed into it. For
the GridRepeater, there are two RepeaterTool nodes
for the two axes. These tool nodes were added to
your graph automatically when you created the
GridRepeater.

Roaring Tide Productions Archimatix User Guide 50

6. The Node Graph Editor

Let’s add some walls to our castle.

Step 6.35: Adjust the Bay handles to

bring the towers closer
together so that the
arrangement looks like the
image to the right.

Step 6.36: Instantiate an Arch_02 object from the 3D Library.

Step 6.37: Connect its output to both the SpanU Mesh and the SpanV Mesh inputs
of the GridRepeater node.

Roaring Tide Productions Archimatix User Guide 51

6. The Node Graph Editor

Step 6.38: Click on any one of the

arches in the scene and
adjust its size to fill the
spaces between the towers.

Step 6.39: Reduce the Size of the

GridRepeater in both
directions until there are
only four towers remaining.

Arch_02 does not come with a top piece, since it is intended to be an infill object. Using 2D
Shapes and the same RepeaterTool nodes, we can make a top piece with a molding profile, as
well as a base.

Roaring Tide Productions Archimatix User Guide 52

6. The Node Graph Editor

Step 6.40: Instantiate a Circle object

from the 2D Library.

Step 6.41: Connect the output of the

Circle to a GridRepeater2D
from the right-hand sidebar
node menu.

Step 6.42: Click on the “Show All Nodes” button in

the lower left-hand corner of the Node
Graph Editor window. Arrange the
RepeaterTool nodes to look like the image to
the right.

Step 6.43: Delete the two RepeaterTool

nodes that are feeding into
the GridRepeater2D and
connect the ones that are
feeding into the
GridRepeater into the
GridRepeater2D.

Now the circles will always be

positioned where the towers are,
regardless of how you modify the grid.

Roaring Tide Productions Archimatix User Guide 53

6. The Node Graph Editor

Step 6.44: Resize the Circle that is feeding into the GridRepeater2D so that it is slightly
bigger than the base of the tower.

Step 6.45: Instantiate a Rectangle from the 2D Library left-hand sidebar and size
it so that its corners are under the towers.

Step 6.46: Multi-select the GridRepeater2D and Rectangle nodes and then click on
the ShapeMerger node in the right-hand sidebar. Click on the Solid/Void
toggle button to make the circles solid.

We now have a composite Shape that is the outline of the castle in plan. This Plan Shape
will generate the base and top walkway for the castle.

Step 6.47: Connect the output of the ShapeMerger to a

PlanSweep_Plan node from the right-hand sidebar
menu.

Roaring Tide Productions Archimatix User Guide 54

6. The Node Graph Editor

Step 6.48: Create an instance

of BaseMolding_02.
Connect it to the
Section input of the
PlanSweep node.

Step 6.49: In the Inspector, set the Material

(Default) to AX_BrickWall.

Step 6.50: Open the Plan input foldout of the PlanSweep and adjust the Offset until the
PlanSweep object looks like the image below.

Step 6.51: Adjust the width of the BaseMolding_02 node to add to the parallel edge.

Roaring Tide Productions Archimatix User Guide 55

6. The Node Graph Editor

Step 6.52: Multi-select the Rectangle and

the ShapeMerger with the four
Circles again, and click on the
ShapeMerger icon in the right-
hand sidebar menu. Click on
the Solid/Void toggle button to
make the circles solid.

Step 6.53: Open the Plan input foldout

and set a thickness for the
incoming Rectangle.

We now have a Shape to use for the upper walkway and parapet. For this we will use another
PlanSweep.

Step 6.54: Connect the new ShapeMerger’s Difference output to a PlanSweep_Plan

from the right-hand sidebar node menu.

Step 6.55: From the left-hand sidebar, select the CymaReversaMolding profile Shape
and connect its output to the Section input of the new PlanSweep.

Step 6.56: Select the PlanSweep object in the scene and move it up above the arch
walls. Adjust the Lip Top, Lip Edge and Offset of the PlanSweep.

Roaring Tide Productions Archimatix User Guide 56

6. The Node Graph Editor

Step 6.57: Add a new MaterialTool to the Top Cap Material of the new PlanSweep. Set the
material to AX_MedievalWall.

The CymaReversaMolding is a little small for the massing of this castle. Let’s make it a bit
more muscular so that it can hold up some sizable battlements.

Step 6.58: Select the CymaReversaMolding node in the Node Graph Editor and hit the F key
to frame it in the scene. Pull the upper handle upwards and outwards.

Roaring Tide Productions Archimatix User Guide 57

6. The Node Graph Editor

As a final step, let’s add some battlements on top.

Step 6.59: Connect the output of the upper deck ShapeMerger to a PlanRepeater_Plan node in
the right-hand sidebar menu.

Step 6.60: Instantiate a Cube by clicking on it in the left-hand 3D Library menu.

Roaring Tide Productions Archimatix User Guide 58

6. The Node Graph Editor

Step 6.61: Select the new PlanRepeater and lift it up in the Y-axis until it is sitting atop the
upper deck. Open the Plan input foldout in the PlanRepeater node and adjust the
Offset to move the battlements back a little. Select the Cube node and turn off
Bevels Unified, then set the Top Bevel to about .15.

For the final shot above, Ambient Occlusion was added to the scene’s Main Camera from
Unity’s Cinematic Image Effects, a free download from the Asset Store.

As our graphs become richer and more complex, it is clear that we could benefit from a
node that groups and hides portions of the graph. Fortunately, Archimatix ships with a node
that does just this. In the next chapter, we will take a look at the Grouper node.

Roaring Tide Productions Archimatix User Guide 59

6. The Node Graph Editor

7. Group Dynamics
As your parametric models become richer and more complex,
you can use the powerful Grouper node to organize the
Archimatix graph into a series of nested subgraphs. Each Grouper
is a self-contained parametric object that has an interface defined by
the Grouper’s input parameters.

Many of the Library items you have worked with so far are Groupers. For
example, the RicketyStaircase and the ScifiPlatform are Groupers with subnodes
that have been saved to the Library.

A Grouper node may be thought of as a container that can hold other nodes, including other
Grouper nodes, inside of it. Once a node has been placed inside a Grouper, it cannot have a
direct connection with another node outside of the Grouper. Instead, a proxy parameter can
be added to the list of the Grouper’s parameters to relay the connection between nodes
inside and outside of the Grouper.

To initiate a Grouper, you can multi-select nodes and then click the Grouper icon in the right
sidebar of the Node Graph Editor window. The selected nodes will disappear as the new
Grouper node appears in the graph. To see the nodes inside, double-click on the Grouper
node, expanding it. Nodes can be popped back out of the Grouper by dragging them to the
left of the Grouper node. Nodes can be added to a Grouper by dragging and dropping them
over the Grouper node.

Perhaps the best way to understand node group dynamics is to create a group.

Roaring Tide Productions Archimatix User Guide 60

7. Group Dynamics

Let’s use the Node Graph Editor to create GrayShip, a model that is something like the
SciFiPlatform we instantiated from the Library in Chapter 2 of this guide. In this example,
we will be creating a parametric spaceship that can be used to stamp out dozens of
variations to form an entire fleet.

Step 7.1: In a new scene, instantiate the CathedralPlan from the 2D library by
either clicking on its icon in the left sidebar of the Node Graph
Editor window or by finding it in the Library window.

Step 7.2: Extrude the CathedralPlan by connecting it to the Extrude Mesher icon
in the right sidebar.

Step 7.2: Make the CathedralPlan the Plan input of a PlanRepeater by connecting
it to the PlanRepeater icon in the right sidebar.

Step 7.4: Instantiate a Cylinder from the 3D Library and connect it to the Node
Mesh input of the PlanRepeater.

At this point, your graph should look similar to the one in the image below.

Roaring Tide Productions Archimatix User Guide 61

7. Group Dynamics

Lets jump in and group some of these nodes. It will be useful to leave the CathedralPlan
outside of the group, allowing us to have a spaceship model that can take different Shapes as
Plan input.

Step 7.5: Multi-select the Cylinder, Extrude and PlanRepeater nodes (but not the
CathedralPlan Shape) and then click on the Grouper icon in the right
sidebar. Multi-selection can be done by either shift-clicking the
nodes or by dragging a rectangle that includes the nodes to select.

As soon as you clicked the Grouper icon, the node

graph became visually simpler. All the nodes are
still in the graph, but they are now organized in
such a way as to logically hide a portion of the
graph.

The Grouper serves as a parametric object whose

internal implementation is encapsulated. If we
replace the CathedralPlan with any other Shape, we
will have an Extrude surrounded by Cylinders
conforming to the new Shape.

The Plan input parameter was added automatically

to the Grouper to serve as a proxy to relay the
connection between the external Shape and any items inside the Grouper that may want to
use it.

Step 7.6: Double-click the thumbnail at the bottom of the Grouper node to expand it.

Looking inside the Grouper, we can see that the

Plan parameter has been automatically connected
to the inputs of the nodes that were originally
connected directly to the CathedralPlan Shape.

Notice the breadcrumb trail at the top of the

window. Since Groupers can be nested, these links
will allow you to see where you are and to click on
any “upstream” Groupers to pop up to the previous
grouping level. You can also pop back up a level by
double-clicking again on the Grouper node
thumbnail.

Roaring Tide Productions Archimatix User Guide 62

7. Group Dynamics

Step 7.7: In the scene view, select the Extrude and find the green point handles along the
side. Adjust the top handle to give the Extrude a taper. Use the lower one to create
a bevel. The cyan handle coming out from the top green point adjusts the number
of segments in the bevel.

Step 7.8: Select any instance of the Cylinder in the scene.Rotate it until it is parallel to the
tapered side of the hull Extrude.

Step 7.9: Double-click the Grouper thumbnail to pop up a group (in this case, back to the
model).

Step 7.10: Click on the MaterialTool button on the Material input for the Grouper to generate
a MaterialTool node. Choose the Concrete material.

Roaring Tide Productions Archimatix User Guide 63

7. Group Dynamics

Step 7.11: Click on any Cylinder and hit the “f ” key to frame the Cylinder in the scene and in
the Node Graph Editor. Notice that this has automatically opened the Grouper.

Step 7.12: Add a MaterialTool node to the Cylinder Extrude and choose sci_fi_003.

Step 7.13: Connect the new MaterialTool to the Extrude’s Top Cap Material.

Step 7.14: Set the Lip Top of the Extrude to 1.2 and the LipEdge to 0.24.

To make the round saucer

superstructure, we will need to make
several pieces that share a center. This
shared center will be displaced from
the origin of the model, which is
currently at the tail of the ship.

Rather than making each part of the

saucer and translating it, we can
establish a new origin by creating a
Grouper inside our first Grouper and
translating that. Once we do that, any
new nodes we create will be located
relative to the position of the new
Grouper.

Roaring Tide Productions Archimatix User Guide 64

7. Group Dynamics

Step 7.15: With the first Grouper for the hull open, but with nothing selected, click on the
Grouper icon in the right sidebar to create a new Grouper inside the first Grouper.
Rename the new Grouper “Saucer.”

Step 7.16: With the new Saucer Grouper selected, translate it to the front of the ship.

Step 7.17: Double-click the Saucer Grouper’s thumbnail to

open it and then instantiate a Cylinder from
the 3D Library sidebar. Decrease the Extrude
Height of the Cylinder and increase its radius to
make it serve as the deck for the bridge.

You will find the new Cylinder at the Saucer Grouper’s

center. If you were to pop the Cylinder out of the Group
by dragging and dropping the Cylinder node to the left of
the Saucer Grouper node, then the Cylinder would
immediately move to the center of the next Grouper, at
the tail of the ship.

Thus we can see that Groupers, in addition to

encapsulating subnode graphs, also serve as local
reference planes to model in situ.

Let’s add another piece of the saucer superstructure.

Roaring Tide Productions Archimatix User Guide 65

7. Group Dynamics

Step 7.18: Instantiate a DomeMolding Shape from the 2D Library sidebar. Connect it to a
Lathe Mesher in the right-hand node sidebar. Turn the Top Cap of the Lathe to off.

This is as far as we’ll go with GrayShip in

this User Guide. While GrayShip helped GrayShipTutorialGrayShipTutorialGrayShipTut
us understand the Grouper node, it has orialGrayShipTutorialGrayShipTutorialGrayShi
more to teach us! To complete GrayShip, pTutorialGrayShipTutorialGrayShipTutorialGr
please visit the full tutorial video at the ayShipTutorialGrayShipTutorialGrayShipTutori
Archimatix support site. alGrayShipTutorialGrayShipTutorialGrayShipT
utorialGrayShipTutorialGrayShipTutorialGrayS
hipTutorialGrayShipTutorialGrayShipTutorial
GrayShipTutorialGrayShipTutorialGrayShipTut
orialGrayShipTutorialGrayShipTutorial

Robot Kyle can hardly wait to take the helm of his new GrayShip!

Roaring Tide Productions Archimatix User Guide 66

Relations

8. Getting to Know Your Relations

Parts of a parametric model often need to be related to each other in mathematical terms.
The ability of such expression-based relations is important for defining logic that governs
the behavior of a model as you vary parameters. Architectural proportions and the
interrelationships of machine parts depend on such logic.

Archimatix lets you relate any parameter to any other parameter in a graph using a
mathematical expression. For example, if you wanted to set the vertical position of a
Cylinder to always equal the height of a Box, then you would essentially be saying that the
Cylinder should sit on top of the Box as you vary the Box height.

Relations in Archimatix are bi-directional. This means that, in the above example, you can
not only alter the height of the Box and automatically translate the Cylinder, but you could
also translate the Cylinder and automatically alter the height of the Box.

Why don’t we go ahead and try this?!

Roaring Tide Productions Archimatix User Guide 67

8. Getting to Know Your Relations

Step 8.1: Start a new scene and add a Cylinder node and a Box node.

Step 8.2: Open the Transform foldout on the Cylinder and the Controls foldout on the Box.

Step 8.3: Click on the Trans_Y parameter of the Cylinder to start a new connector. Move
the mouse to the Height parameter of the Box and click the input to complete the
Relation connection.

Step 8.4: Adjust the height of the Box either by sliding its Height parameter or by dragging
the Height handle in the scene.

Remember, relations are bi-directional, meaning that the connector socket on either side of
the parameter in the node palette can be chosen when connecting parameters. The bi-
directionally of relations also means that you can adjust either end of the connection and
the parameter on the other side of the connection will be modified according to the
expression in the Relation.

The default Relation expression is equivalency, or “=”. In the above example, the Relation
equation is Cylinder.Trans_Y=Box.Height.

Let’s create a Relation with a slightly more interesting expression.

Roaring Tide Productions Archimatix User Guide 68

8. Getting to Know Your Relations

Cranking Up Relations

A good example of a relation between two objects is

that of a piston to a crankshaft in an internal
combustion engine.
piston
Typically, as the piston moves up and down, the
crankshaft rotates in a constant direction. crankshaft
Conversely, if the crankshaft rotates, it moves the
piston up and down in a sinusoidal motion. Such a
relationship calls for the use of a sine function in its
Relation expression.

To make a simple model of an internal combustion

engine, we will exclude the piston rod, representing
the piston and crankshaft by two cylinders.

Also, for the purposes of a quick start, instead of

using the trigonometry needed to find the more
accurate relation of the piston and crankshaft based
on the length of the piston rod, we will approximate
the Relation with a variation of:

Piston.Trans_Y = sin(Crankshaft.Rot_Z)

For a more elaborate scenario using the actual

geometry of a piston and crankshaft, see this tutorial
at the Archimatix support site:

http://www.archimatix.com/tutorials/piston-and-
crankshaft

Step 8.5: In a new scene, choose the Cylinder item from

the left sidebar menu. Click on the node name
button and change the name to Crankshaft.

Step 8.6: Click the axis orientation button until it is set

to Z. Open the Transform foldout and set the
Align_Z to Center.

Step 8.7: Change the material of the model to

AX_PurpleGrid. In the Scene View, use the
handles to adjust the length of the Crankshaft
and its radius so that it looks like the image
above right.

Roaring Tide Productions Archimatix User Guide 69

8. Getting to Know Your Relations

Step 8.8 Create another Cylinder and rename

it Piston. Adjust its radius until it
looks like the image on the previous
page.

Step 8.9: Open the Transform foldouts for

both nodes and create a connection
between the Rot_Z of the
Crankshaft and the Trans_Y of the
Piston.

As mentioned previously, the default Relation

expression is “=”. If you like, you can drag the
Piston in the Y-axis to see the Crankshaft rotate,
but the sensitivity is not very high. In other
words, as you drag the Piston through 2 units,
the Crankshaft will rotate only 2 degrees.

Step 8.10: Open the Edit Relation window by clicking on the green button at the midpoint
of the connection, or by clicking on the connection cable to select it and then
hitting the Spacebar. Change the expressions to those in the image below.

The expressions relating the two parameters are the inverse of each other. In the second
expression, the sine of the Crankshaft.RotZ is multiplied by 2 to give it more sensitivity, and 3
units are added to lift the sinusoidal motion of the Piston to be centered at 3 units above the

Roaring Tide Productions Archimatix User Guide 70

8. Getting to Know Your Relations

Crankshaft. Again, this is fudged geometry designed to produce quick, rudimentary results.
With it, you can now rotate the Crankshaft in the Z-axis indefinitely, and the Piston will cycle
up and down; if you move the Piston up and down, however, the Crankshaft will only respond
while the Piston is just above the Crankshaft (in its first cycle).

Taking Archimatix to the Next Level

I hope you found this guide useful. For more documentation and tutorials, please visit the
Archimatix support site at http://www.archimatix.com.

And come join the community at http://community.archimatix.com!

If you have specific technical questions, email us at [email protected].

Roaring Tide Productions Archimatix User Guide 71

Automate Everyday
Revit Tasks with
Dynamo
Paul F. Aubin—is the author of many Revit book titles including the Aubin Academy
Series and his "deep dive" into the Revit family editor: Renaissance Revit. He also authors
dozens of video titles at lynda.com (now LinkedIn Learning) covering Revit topics from
beginner to advanced. Paul is an independent architectural consultant providing Revit
content creation, implementation, training and support services. His career of nearly 30
years, includes experience in design, production, CAD management, coaching and
training. Paul is an active member of the Autodesk user community and has been a top-
rated speaker at conferences such as Autodesk University, BILT and Midwest University
for many years; and he recently gave the keynote address to the Campus FM Technology
Association annual conference. Paul is an associate member of the AIA, an Autodesk
Expert Elite and an Autodesk Certified Professional. He lives in Chicago with his wife and
their three children currently attending universities around the country.
Visit: www.paulaubin.com Follow: @paulfaubin

Class Description
Do you find yourself frequently having to perform the same task several times over the course of a
project? Are there workflows that your firm relies on that are not easily achieved with native Revit tools
and techniques? Do you ever find yourself thinking that your current procedures are just not maximizing
the promise or potential of your BIM? It's times like these where a little Dynamo can be just the thing. In
this session, we will walk through some complete workflows to automate common repetitive tasks and
more importantly, give end users the confidence they need to know that the resulting data they see is
correct and accurate. This session will explore using Dynamo to design a workflow that solves a simple
repetitive task in Revit. We'll discuss the problem, walk through the design of the solution, and explore
the Dynamo graph piece by piece. Don't worry if you are new to Dynamo or programming, we'll keep it
simple, approachable, understandable and free from complex code.

Learning Objectives
• Learn how to identify a good task for Dynamo
• Learn how to frame the problem and break down the steps
• Understand how to approach building a graph even if you are not a programmer
• Learn to organize and document your graphs so they are easy to understand and
modify
Software Version
This session will use Dynamo for Revit and will use Dynamo version 2.0.2 running in Revit
2019.2 (see Figure 1). More information on Dynamo versions and installation in the appendix.

Figure 1 –Dynamo and Revit version used in this session

Additional Resources
In this session, I am going to assume that this is not your first time using Dynamo. Therefore, the
basics of launching Dynamo, creating a graph, adding nodes and connecting wires are all
assumed. If you are not familiar with these tasks or are brand new to Dynamo, there are many
online resources that can help you on journey to learn more about Dynamo. There is a list in the
appendix that you can consult before and after the session. But we would like to share a few
useful resources with you right away:
LinkedIn Learning (powered by lynda.com content) has a growing collection of courses that are
well worth your time; including some by yours truly! (Dynamo: Practical) Check them out!
Visit: www.linkedin.com/learning/ to learn more and then search for: Dynamo (see Figure 2).

Figure 2 – Video courses on LinkedIn Learning (lynda.com)

Other popular resources:
dynamobim.org/ - the Dynamo home page.
http://primer.dynamobim.org/en/ - an introductory tutorial on getting started with Dynamo.
dictionary.dynamobim.com – this is a searchable database for Dynamo functionality.
dynamonodes.com – all about dynamo nodes.

Introduction
Got some mundane repetitive Revit task to do? Let Dynamo do it! This session explores the
identifying of repetitive Revit tasks that are good candidates for Dynamo and explores a couple
sample solutions in detail. Learn to create repeatable results with no complex coding required. In
this session and handout, we will walk through two quick and practical graphs that you can build to
solve real-world problems back at the office. These include:
• Calculating Room Occupancy Values based on building code guidelines
• Automatically determine and place Wall Type Details in use in a project

Calculating Room Occupancy Values

In this example, we will use Dynamo to calculate the occupancy load values for several rooms in a
project based on the code requirements for each type of space. For this example, we will be using
values taken from the International Building Code, 2015 edition.
IMPORTANT—If you adapt this graph to your own use, please double-check that all values match
the actual code requirements for the municipality having jurisdiction over your project.
For the purposes of this demo, the values in Table 1 will be used.

Table 1 - Occupancy Values per Room Type

SF SM SF SM
required required required required
per per per per
Room Name occupant occupant Room Name occupant occupant
Administration 100 9.2900 Lounge 15 1.3935
Advisors 100 9.2900 Media Review 50 4.6450
Cafeteria 15 1.3935 Men 100 9.2900
Computer Lab 50 4.6450 Office 100 9.2900
Conference 100 9.2900 Open Office 100 9.2900
Copy/Print 100 9.2900 Prep/Dish 200 18.5800
Corridor 100 9.2900 Sprinkler 300 27.8700
Drafting 100 9.2900 Stair 100 9.2900
Dry Storage 300 27.8700 Storage 300 27.8700
Electrical 50 4.6450 Toilet 100 9.2900
Instruction 20 1.8580 Vest. 100 9.2900
Library 50 4.6450 Women 100 9.2900
Lobby 5 0.4645
The out-of-the-box Revit Architectural Advanced Sample Project will be used in the demonstration.
The Room names in the table come from this project and have been compared to the National
Building Code to come up with the values listed. Once again, please check the values against your
own resources to ensure accuracy and compliance.
Why Use Dynamo for this task?
Calculating Occupancy Values is not difficult to do. You simply take the area of the room or space,
divide it by the number of required square feet [or square meters] per occupant and round down to
the nearest whole value. This is your maximum occupant load for that space.
So why not just do this calculation directly in Revit? You theoretically could do this, but it would
require a good deal of manual input. At minimum, you would be required to input the values from
Table 1 above somewhere in the model. The most likely place would be in a custom parameter
assigned to the Room Category. However, there would be no easy way to input this data based on
room function. So, you would be forced to manually input it for each room. And since room
elements do not have types, you would be required to input the value for every room individually.
Now clever use of schedule grouping and sorting could speed this process up if you group and
sort by like functions. But consider just the simple example presented here, Table 1 includes 7
unique occupancy values used by 25 unique room names.
This means you would first need to create a custom project parameter to receive the occupancy
value input, then create a schedule sorted by the 25 room names and finally make 25 separate
edits to input those 7 occupancy values into the custom field. While making 25 edits is arguably
not a tremendous amount of effort, it is certainly more than most of us wish to do manually; not to
mention the potential for error when performing such repetitive input tasks. Furthermore, many
projects (if not most) will have far more room types than the 25 used here.
Dynamo to the rescue! Dynamo is great for repetitive tasks like this one.
Framing the problem
So, what is involved in getting Dynamo to do this task for you? Well you must frame the problem in
a way that Dynamo will understand and be able to process regardless of the input you feed in.
This means thinking about how data flows through a Dynamo graph and ensuring that you
anticipate any issues or errors that are likely to occur along the way. The best thing you can do is
keep it simple and stay focused on the main task. Here’s what we want to do:
Have Dynamo gather all rooms in our project file, organize them by room type/usage and then
assign the correct occupancy value to each one based on the table and calculation outlined
above.

Explore the Graph

The sample graph provided here is grouped into logical chunks. In this topic, we will go
through each group and explore how data flows through the graph. This sample uses the
room names from the Advanced Sample Project. If you adapt this for your own use, you
will need to export your list of room names from your project first and then compile a table
in Excel that has the desired occupancy values for each room name in use. This can be
done using another Dynamo graph, or by simply exporting a Revit room schedule.
Groups in this graph are numbered. The explanations here will refer to them by number.
Group 1
Group 1 contains three nodes (See Figure 3).
Figure 3 – Selecting all of the room elements in the model

This group makes the selection of Revit elements. The first node chooses the category of
elements we want; Rooms in this case. And then the second node gathers all elements in
the model that belong to this category. In other words, it selects all the room elements in
the entire model. The Watch node is optional. But it can be nice to give feedback on the
graph as you work through it. In this case, it is listing the selection and shows us that
Dynamo has selected a total of 91 rooms. If you wanted to verify this, you could make a
room schedule in Revit and is would yield the same quantity of rooms.
Group 2
Group 2 also contains three nodes, but really there is one main one:
Element.GetParameterValueByName (See Figure 4).

Figure 4 – Retrieve the room names from the selection of rooms

The list of room names from group 1 feeds into the element port of the
Element.GetParameterValueByName node here in group 2. This is a very useful Revit
node. It allows you to grab the value of any parameter on a selection of Revit elements. In
this case, we are using a String node to feed in the name of the parameter we want into
the parameterName input. A String node is a text node. The computer science word for
text values are “strings.” The results here show up in another Watch node.
Group 3
Group 3 contains five nodes (See Figure 5). There are two “ByKey” nodes. Keys are used to sort
and group lists. In the first case, List.SortByKey, the node takes a list of values (91 total Revit
Room elements from group 1) and sorts them based on the list of room names from group 2. This
generates two outputs: a sorted list and a list of sorted keys.
These outputs are next fed into the List.GroupByKey. This node organizes the list into a
“structured” list. A structured list is a list of lists. In other words, there is a main list that contains
sub lists as its items. Here we end up with a sub list for each unique room name (the keys used for
sorting and grouping) and then the values on these sub lists are the unique rooms corresponding
to those name values. So, for example, the first list (0 List) contains three items. These are the
three rooms named: Administration. You can see this structured list in the first Watch node.

Figure 5 – Sort and group the list as a structured list using room name as the organizing key

The second Watch node gives us the output of the unique keys from the GroupByKey
node. This shows the 25 unique room names used in the project (and noted above).
The final node in this group gives us a count of each sub list. To achieve this, you must
use “list at levels.” This is the small chevron icon next to the input. You click this, check
the Use Levels checkbox and then set which level you want the node to apply at. Using
@L2 in this case gives us a list that counts each sub list instead of the main list and
therefore gives us 25 counts (corresponding to the quantity of sub lists). If you applied the
list at levels to either @L1 or @L3, you would get very different results (see Figure 6).
Figure 6 – Use List at Levels to control at which list in the nested structure the node function should apply

To summarize where we are at in the first three groups, we started by selecting all the
rooms in the model, querying their room names and then sorting and grouping the original
collection of rooms by those room name values and then counting the total number of
instances of reach room name. Next, we want to match up our list of occupancy values
with the rooms of each room type (based on names); onto group 4.
Group 4
Group 4 shows 7 nodes (See Figure 7). Part of being successful in Dynamo (and any
programming endeavor) is knowing what to do in Dynamo and what to do elsewhere. It is certainly
possible to build the building code table directly in Dynamo. Doing so would require more nodes
and make a more complex graph. Later editing of the values should the code change would
require reworking the Dynamo graph. Instead, this group does something much simpler. It uses
Excel. Excel is well known by most users and a great way to build a list of values. We can then
simply have Dynamo read the data directly from the Excel file and use the data in Dynamo and
Revit. Furthermore, since the data lives in Excel, it is easy to update when required.

Figure 7 – Read an Excel file into your Dynamo graph

The Data.ImportExcel node takes four inputs. The first two are required, the last two are
optional. The last two are Booleans (true or false). Attaching a Boolean node to these
inputs allows you to change the default value if you choose. If you leave them as-is, or
unconnected, they will use their respective defaults.
The first input: file, takes two nodes in series. Wire a File Path into a File From Path
and then into the file input. If you skip the File From Path node, it will fail. So, make
sure you have both. The Browse button on the File Path node lets you point to an Excel
file you want to read. The final input: sheetName tells Dynamo which sheet in the Excel
workbook you want to read. A simple String node allows you to type in whatever this
name is. We end this group with a List.RestOfItems node. This node drops the first item
on the list. This is useful here to eliminate the headers that are often included in the first
row of an Excel file. If you expand the preview bubble on this node and look at the output,
it will be a structured list. Each sub list was a row of data in Excel with the values on the
list being the columns of data.
Group 5
Moving on to Group 5, the first node is Transpose. Often you want to organize the Excel data by
columns instead of rows. This is what transpose does. Compare the two preview bubbles in the
first two nodes shown in Figure 8 to visualize this. The remaining five nodes in Group 5 are
devoted to matching up the correct occupancy multipliers with each room name value.

Figure 8 – Organize and match the Excel data to the rooms

Let’s dig into the logic a bit. We start with a List.GetItemAtIndex node. This node simply
uses the index value you feed it (from a Number node) to extract the corresponding value
from a list. In this case, we are feeding in the transposed list of Excel data, but since we
are only asking for index 2, we are getting just the metric occupancy multipliers. You can
see this in the first Watch node. But this is only 25 values since the Excel file only
contains one value for each unique room name. In order to make this work correctly with
our model, we must ensure that we match the original list and its data structure.
Remember our example above, the first list contained three instances of rooms called
Administration. We need each of these rooms to use the 9.29 occupancy multiplier.
This gets us back to why we wanted the count of each sub list in Group 3 above. Using
that list of counts we feed it into the List.OfRepeatedItem node. This node will repeat one
or more values fed into it using the quantity fed into the amount input. So here, we feed
out list of unique room occupancy multiplies from Excel (25 total) and repeat each one the
number of times coming from the List.Count node above. We will end up with the
structured list show in the final Watch node and if you compare its structure to the
previous structured lists, it is a perfect match and we are back to 91 items!
Group 6
Group 6 contains four nodes (See Figure 9).

Figure 9 – Perform the calculations

Here we are going back to the original list of Rooms and getting another parameter; the
Area this time. With this information, we can use the occupancy multipliers and calculate
our final required occupancy values. A simple division node (/) is used here for this
purpose. Math.Floor is similar to rounding, but eliminates any fractional value and rounds
down to the nearest whole number.
Group 7
Group 7, our final group has just three nodes (See Figure 10).

Figure 10 – Set the room occupancy values in the model

Earlier we used two “Get Parameter” nodes to read data from Revit. Here we will be
modifying the Revit model using a “Set” node. The Element.SetParameterByName node
writes data back to Revit. So, with our list of calculated values, this node will update all our
rooms and write the required occupancy values to them. Two things to note in this group.
First is the String from Object node. The Occupancy field in Revit is a text parameter.
Therefore, we must convert our list of numbers to text before writing to Revit, or it will fail.
This node does that. Second, the final node is “frozen.” This means that you must un-
freeze it before it will execute this final node. This is a nice way to run part of a graph and
wait till you are ready to complete the results. So be sure to right-click and choose Freeze
to uncheck it and then run the graph to complete the task. Once you have done this, you
can select any room in the model, and it will have an occupancy value added to it. Or you
can create a schedule that shows the occupancy values to see them all at once.
Automatically Determine and Place Wall Type Details
Many firms have standard wall type details that are used in each project. These are often already
included in the project template. In this example, we will use Dynamo to determine which wall
types are currently in use in a project and then use that information to place the required wall type
details.
Why Use Dynamo for this task?
Placing views on sheets is an easy task in Revit. The reason that this is a good task for Dynamo is
that as your list of partition types grows, you will find it better if we can reliably ensure that all
details called out in the project are properly represented on the partition type sheet. This is not
hard to do if there are only a few, but when there are many, it can become a tedious and possibly
error prone task. That’s why Dynamo can help.
Framing the problem
So, what is involved in getting Dynamo to do this task for you? As we did above, you must frame
the problem in a way that Dynamo will understand and be able to process regardless of the input
you feed in. Here we need Dynamo to look at our model, figure out which wall types we are using,
then make a sheet and place the required details on that sheet.

Explore the Graph

To start this example, we have a simple Revit model and a starter Dynamo graph. Like the
previous example, we’ll go through the graph one group at a time. The first group is incomplete. In
this example, we’ll add the missing nodes and wire them together using the notes included in the
group for some first-hand practice (see Figure 11).

Figure 11 – Starter graph

Build Group 1
The first note in group 1 indicates selection of all walls in the model. This is accomplished with two
nodes, both indicated by separate notes: Categories and All Elements of Category. You can find
both nodes in the library beneath Revit > Selection.
Click on the name of each node in the library to add it to the canvas. Position them beneath the
notes in group 1. From the Categories node, choose Walls, then wire its output to the input of All
Elements of Category.
At the bottom of the Dynamo window, click the Run button to execute the graph. Then hover over
the All Elements of Category node. The preview bubble will appear. Click the small pushpin icon
to pin this open. It will indicate that 16 walls have been selected. Note the green highlighted
element IDs next to each wall. These are the Revit element IDs and you can click on them to zoom
the Revit window directly to this item in the model. But another important factor of having those
green IDs is that they indicate that the item is a Revit element (see Figure 12).

Figure 12 – Select all the walls in the project with two simple nodes

From this list of individual wall elements, we next want to get the Revit Type name of each wall.
The FamilyType.Name node is used for this purpose and can be found on the Revit > Elements >
FamilyType branch of the library or by searching. Wire the output of All Elements of Category to
this node. Next, from the Revit > Elements > WallType branch (or by searching), place the
WallType.ByName node. Wire this to the output of the last node (see Figure 13).
Figure 13 – Select the wall types from the list of walls

It might not be clear why all these nodes are required. But the outputs of each node give some
clues. The All Elements of Category outputs individual model elements. The next node:
FamilyType.Name gives the names (as text, or “strings”) of the types used by each of those
elements. The final node selects the actual Revit Wall Types based on the names in the middle
list.
From the Revit > Elements > Element branch we next need an
Element.GetParameterValueByName node. As we have seen before, this allows us to grab the
value of the named parameter. A String node will allow us to indicate the parameter name we
need. In this case, that parameter is: “Type Mark.” It is case sensitive, so be sure to type is
correctly. Type Mark values are what show in our wall tags and how we indicate each wall type in
the model and their corresponding details (see Figure 14).
Figure 14 – Grab the Type Mark values of each wall type

After you run the graph and expand the preview bubble, you will note that some walls do not have
a Type Mark value. We’ll filter those out next. A FilterByBoolMask node is already in the graph
for this purpose. The String that we will use for filtering is empty. The != node checks if the values
fed into the x port are not equal to the one fed into the y port. This gives a list of true and false
values. This can be used to branch our output into two lists with the boolmask (see Figure 15).
Figure 15 – Filter the list into two lists, those with Type Marks and those without

The List.FilterByBoolMask node has two outputs. I will frequently use Watch nodes to report the
values when there are multiple outputs. This just keeps it cleaner. You can see those in the
orange group called “Outputs.” These are just for information only and are optional.
The remainder of the graph is already built in the starter file. Let’s walk through the rest of it now.
Group 2
Group 2 has three nodes. The first takes the list of “In” elements from the BoolMask and finds only
the unique items. Next this list is sorted, and then using a + node, we add a prefix to the front of
the names to make them match the names used for the drafting details back in our Revit project
file (see Figure 16).
Figure 16 – Find the unique Type Marks and edit the names to match the details names in Project Browser

Group 3
On to group 3. Here we will match up the detail views in the project with the names we just
constructed. First, using Categories and All Elements of Category again, we select all the Views
this time. From the list, we grab their names (Element.Name) and then use the List.IndexOf node
to figure out where each view name occurs on the list. This is asking for the specific index (or
address) of the named item on the list of view names (see Figure 17).
Figure 17 – Locate the required detail views from the list of all project views

Group 4
The final group uses the Sheet.ByNameNumberTitleBlockAndViews node. This node creates a
sheet and adds a list of views. Satisfying the first two inputs is accomplished with simple String
nodes. The titleBlockFamilyType input is satisfied with a Family Types node. To satisfy the
list of views, we simply feed in our list from group 3. The final node is frozen, so be sure to right-
click it and un-freeze before running.

Figure 18 – Create a sheet and populate with the list of required details

When you run the graph, you should see a sheet appear in Revit. If you open that sheet, each of
the views from group 3 will have been placed on the sheet. They end up in the lower left corner of
the sheet. Simply move them where you wish them to go on the sheet (see Figure 19).
Figure 19 – The resulting sheet with its placed details

This graph achieves the basic requirements. If you wish, you can enhance it to move the viewports
to a better location for you instead of doing that manually. You can also create a second graph to
update this sheet should the required details change. I will leave those tasks to you as a challenge
exercise if you are interested. But keep in mind that you can also just delete the sheet and run the
graph again in the future. It is up to you.

Conclusion
These were two fairly simple examples. But hopefully they help illustrate some of the tasks you
should consider using Dynamo for. Anytime you have a well-defined task that is repetitive or
laborious, you should consider Dynamo as an alternative to manual processing. Not every
repetitive task will be improved with Dynamo. The best candidates are those that you can clearly
and quickly define the logic and steps for. This will help you reap the benefits of automation. If you
spend hours building a graph that only saves a few minutes, that is probably not the best use of
your time. However, if the initial investment in building the graph can be recouped on the current or
future projects, then it is likely a good candidate for Dynamo automation.
UNITYREV - BRIDGING THE GAP BETWEEN BIM AUTHORING
PLATFORMS AND GAME ENGINES BY CREATING A REAL-TIME BI-
DIRECTIONAL EXCHANGE OF BIM DATA

KIERAN W. MAY1, JAMES WALSH2, ROSS T. SMITH3, NING GU4

and BRUCE H. THOMAS5
1,2,3,4,5
University of South Australia, Australian Research Centre for In-
teractive and Virtual Environment
1
[email protected] , 0000-0002-5461-4927
2,3,4,5
{james.walsh|ross.smith|ning.gu|bruce.thomas}@unisa.edu.au,
2
0000-0002-4822-990X, 30000-0002-9044-9199, 40000-0002-5555-
9165, 50000-0002-9148-085X

Abstract. We present UnityRev: An open-source software package that

enables a workflow designed to facilitate a real-time bi-directional and
synchronous exchange of Building Information Modelling (BIM) data,
by creating a direct link between a BIM authoring platform (i.e.
Autodesk Revit) and a game engine (i.e. Unity 3D). Although previous
works have explored the integration of BIM with game engines, the
currently available tools are limited to a non-synchronous or uni-
directional exchange of BIM data, and they do not address specific
design issues required to make a BIM authoring platform and game
engine compatible (i.e. parametric modelling). This paper describes our
software which consists of a compact overview of the system, including
design decisions, implementation details, and system capabilities. Two
example applications are presented as concept demonstrators to
showcase practical collaborative use-case scenarios between BIM
authoring platforms and game engines which were not previously
achievable without a real-time bi-directional workflow. This work will
expand future Computer Aided Architectural Design (CAAD) research,
and more specifically, Virtual Reality (VR)/Augmented Reality (AR)
based BIM development and integration, by providing new possibilities
and bridging the gap between BIM authoring platforms and game
engines. The application of the system as demonstrated in the paper for
real-time lighting performance simulation contributes to achieving the
UN Sustainable Development Goal 11: Sustainable Cities and
Communities.

Keywords. Building Information Modelling; Game Engines; Revit;

Unity; Virtual Reality; Augmented Reality; Lighting Performance
Simulation; SDG 11.

POST-CARBON, Proceedings of the 27th International Conference of the Association for Computer-Aided
Architectural Design Research in Asia (CAADRIA) 2022, Volume 2, 527-536. © 2022 and published by the
Association for Computer-Aided Architectural Design Research in Asia (CAADRIA), Hong Kong.
528 K.W. MAY ET AL.

1. Introduction
This paper presents UnityRev, an open-source and freely available software package
that enables a workflow designed to facilitate a real-time bi-directional and
synchronous exchange of Building Information Modelling (BIM) data between a BIM
authoring platform (i.e. Autodesk Revit) and a game engine (i.e. Unity 3D). Game
engines play a pivotal role in recent research, as they act as a stepping-stone for
researchers to virtually prototype and build software applications by providing them
with a set of software development tools. Previous works comparing game engines and
BIM authoring platforms have highlighted three primary motivations for using game
engines for architectural representation. Specifically, the interaction, visualisation, and
real-time capabilities associated with game engines provide a layer of functionality that
BIM authoring platforms are unable to provide (Pelosi, 2010, Boeykens, 2011). Over
the last decade, the usage of game engines within Computer Aided Architectural
Design (CAAD) research has risen significantly with a large focus on incorporating
BIM models with advanced visualisation tools such as Virtual Reality (VR) and
Augmented Reality (AR) displays. However, despite the importance of game engines
in current VR/AR BIM research, the ability to communicate BIM data between BIM
authoring platforms has remained a consistent issue for researchers working within this
particular field.
To bridge the gap between BIM authoring platforms and game engines, various
tools have been released to support the integration of BIM within game engines;
however, these tools lack the capability to support a natural real-time, and synchronous
exchange without loss of BIM data. Due to the uni-directional flow of data from these
tools, manipulations that occur to the BIM model within game engines are not
synchronised back to the BIM authoring platform that contains the original BIM
model. Due to the limited tools available, and lack of BIM support provided by game
engines, many researchers utilising game engines to prototype BIM-based applications
export BIM models from BIM authoring platforms into a file format that is natively
supported by the game engine. This process generally involves exporting a BIM model
from Revit as a Filmbox (FBX), Object (OBJ) file or other similar data formats
supported by game engines that only provide geometric or partial metadata (Bille et al.,
2014). As a result, a large portion of the metadata (e.g. cost, schedule, manufacturer,
etc.) associated with the geometric model is lost, subsequently transforming the
information-rich BIM model into a generic three-dimensional Computer-Aided Design
(CAD) model. We believe this limitation to be one of the major gaps in the adoption
of immersive BIM-based research within the Architectural, Engineering, and
Construction (AEC) industrial sectors. Recent works from the authors have a validated
this claim where a workshop was held by the researchers with four AEC industry
representatives. The AEC industry representatives stated that the loss of BIM data
caused by cross-platform BIM communication was one of the major barriers associated
with BIMs, and the integration of VR, and AR applications with BIM models (May et
al., 2022).
To address the aforementioned issues, an open-source workflow capable of
facilitating a real-time bi-directional and synchronous exchange of BIM data between
BIM authoring platforms and game engines could be particularly useful to addressing
one of the major research gaps associated with the process of integrating BIM with
 UNITYREV - BRIDGING THE GAP BETWEEN BIM 529
AUTHORING PLATFORMS AND GAME ENGINES

immersive VR/AR displays and game engines.

The specific contributions of this paper are:
1. An open-source software package that enables a workflow for linking Unity and
Revit through a bi-directional synchronous exchange of BIM data.
2. An approach for enabling parametric CAAD modelling within a physics-driven
game engine.
3. Two example applications highlighting the potential advantages of the proposed
workflow and demonstrating two scenarios that were not previously possible without
the use of a synchronous bi-directional BIM workflow.
In the remainder of this paper, we explore previous works in the field, and identify the
common gaps and limitations of currently available tools and literature. We then
present the system capabilities of the 'UnityRev' software package that enables the
workflow to achieve a bi-directional synchronisation of BIM data. Two example
applications are presented as concept demonstrators to showcase practical
collaborative use-case scenarios linking BIM authoring platforms and game engines
using UnityRev. The application of the system as demonstrated in the following
sections for a VR-based Lighting Performance Simulator addresses the UN Sustainable
Development Goal 11: Sustainable Cities and Communities. We released UnityRev as
an open-source GitHub repository under the MIT license
(https://github.com/kieran196/UnityRev-ProjectExchange).

2. Related Works
To identify common tools and previous research exploring the process of linking BIM
authoring platforms and game engines, we conducted a literature review focusing
specifically on asynchronous and synchronous workflows designed for CAD/BIM
authoring platforms to game engine integration.

2.1. ASYNCHRONOUS WORKFLOWS

The most widely adopted approach for the transferal of BIM data across BIM authoring
platforms is using the Industry Foundation Class (IFC). IFC is a standardised BIM file-
format supported by several BIM-driven CAD platforms. The IFC data format supports
the transferal of BIM data by storing the metadata, and geometric properties associated
with a BIM into a single file format. Although IFC can maintain partial metadata
properties associated with a BIM model, modern game engines such as Unreal and
Unity do not provide native support for IFC. As a result, third-party libraries have been
released to support parsing IFC files into game engines. Additionally, researchers have
developed their own systems capable of parsing IFC files into game engines to provide
partial uni-directional integration of BIM data. Previous researchers who utilised a
Revit to Unity workflow reported limitations associated with using an IFC-based
workflow due to IFC standard only providing partial metadata (Motamedi et al., 2017).
Due to the complex structure of the IFC data model, difficulties emerge when
attempting to write BIM changes directly back to the original IFC file, making it
significantly challenging to achieve a two-way transferal of BIM data when strictly
using IFC. However, (Nandavar et al., 2018) were successful in achieving this by
proposing an XML-based approach to store manipulations that occurred to the BIM
530 K.W. MAY ET AL.

model within VR (i.e. Unity). The XML file could then be parsed back to the original
IFC file using an open-source IFC management software: xBIM toolkit (Lockley et al.,
2017). Similar investigations have also been conducted by (Khalili, 2021); however,
using the FBX data model which is natively supported by game engines as opposed to
IFC. Our review shows that, the primary advantage of an IFC-based approach is the
interoperability and adaptability of the workflow, as it can be integrated with any BIM
authoring platform which provides support for IFC. This is a considerable step towards
achieving an intuitive integration of BIM data across all BIM authoring platforms and
game engines.

2.2. SYNCHRONOUS WORKFLOWS

Fewer works have demonstrated the ability to achieve a real-time exchange of BIM
data between BIM authoring platforms and game engines. (Du et al., 2018) created a
system called 'BIM-VR Real-time Synchronization' (BVRS), which can perform a
real-time synchronous uni-directional exchange of BIM data by autonomously
synchronising changes made to the BIM model in Revit back to Unity in real-time.
This was achieved by creating a Revit plugin that constantly sends manipulations made
to the BIM model within Revit to a cloud-based server that stores and transfers data
based on IFC.
In 2018, (Nandavar et al., 2018) identified Fuzor and BIMXplorer as the only two
publicly available software packages capable of achieving a complete exchange of
BIM data between BIM and VR. Earlier works by (Chotrov and Maleshkov, 2013)
also presented an approach using a TCP/IP network communication that achieved a bi-
directional synchronisation of CAD geometry between a CAD platform (Solid-works)
and VR application. However, all three described systems utilised a customised VR
rendering pipeline to achieve this communication as opposed to game engines.
The Unity development team recently released Unity Reflect (Reflect, 2021), which
we believe to date is the most advanced publicly available software package capable
of achieving a linkage between a BIM authoring platform (Revit) and game engine
(Unity). Unity Reflect provides a uni-directional exchange of BIM data by
instantaneously sending data from Revit to Unity across a server. The primary
limitation we have identified with Unity Reflect is that the transferal of data flows in
one direction, and as a result, manipulations that occur to the BIM model within Unity
are not sent back to the original BIM model. Furthermore, modifications made to the
BIM model in Revit are not updated within Unity in real-time, and users are required
to reload the model to synchronise changes from Revit. Both limitations are specifically
addressed in UnityRev.
(Edwards et al., 2015) demonstrated the ability to incorporate a network to bi-
directionally exchange BIM data between a BIM authoring (Revit) and game engine
(Unity). A custom OBJ data-model was used to facilitate the initial geometry
associated with the BIM model into Unity. The authors, however, reported they
encountered various issues such as manipulations made to the position of elements
within VR not updating correctly within Revit.
Recently, (Harlan et al., 2020) presented a three-module system to integrate a CAD
platform (Simens NX) and game engine (Unreal). The system presented a unique
 UNITYREV - BRIDGING THE GAP BETWEEN BIM 531
AUTHORING PLATFORMS AND GAME ENGINES

approach capable of loading and reloading meshes at run-time by accessing CAD

functionality through the NXOpen C++ API. The authors are actively using their
proposed software to research hand-tracking based natural user-interfaces for design
sketch creation in VR.

2.3. SUMMARY OF PREVIOUS WORKS

In summary, UnityRev addresses the following issues and limitations associated with
the prior works discussed above and the currently available tools that produce a link
between a BIM authoring platform and game engine:
Of the available CAD to game engine workflows: No tools provide a bi-directional
exchange of BIM data and only supports a CAD to game engine directional flow of
data. No tools support a real-time synchronous transferal of BIM data. Only one tool
(Unity Reflect) can achieve a complete integration of BIM metadata into a game engine
with constraints as discussed above.
Of the available CAD/BIM authoring platform to game engine workflows from our
review: No prior works produced a workflow capable of supporting a game engine to
adhere to the parametric CAAD modelling platforms. No prior works produced a
workflow capable of supporting a real-time two-way transferal of BIM data with
geometric orientation and geometric mesh manipulation.

3. UnityRev: System Overview

To enable the real-time integration between BIM and game engines, we developed a
customised network based on a Transmission Control Protocol and Internet Protocol
(TCP/IP) network architecture to facilitate the exchange of BIM data between Revit, a
BIM authoring platform and Unity, a game engine. A local server is set up, which is
hosted from the Unity software, with Revit connecting to the server as a client. To
achieve this connection from the BIM authoring platform, a plugin was developed
based on the Revit API, which is run as an add-in directly from Revit. The process of
transmitting data between the server and client consists of retrieving the element IDs,
position, rotation, scale, metadata, and mesh data via the Revit API and converting it
into a bytes array, which is then sent through a socket. This data is then decoded and
parsed by the receiver to synchronise modifications within the corresponding software.
A custom network protocol was developed to exchange commands between the server
and client to represent the transmission of specific data. Similarly, BIM elements are
identified when being transferred across platforms based on their unique IDs, which
are automatically generated within Revit. An error-checking system was integrated into
the system, ensuring that only valid actions adhering to Revit's parametric modelling
can be supported within the Unity engine. The software was written entirely in the C#
programming language.

3.1. ADHERING TO PARAMETRIC CAAD MODELLING

Typical BIM authoring platforms such as Autodesk Revit provide parametric
modelling to assist users in correctly designing architectural structures. However,
physics-based game engines such as Unity and Unreal were not designed to support
BIM or CAAD and therefore do not follow parametric modelling rules and
532 K.W. MAY ET AL.

conventions. For example, if a user manipulated the position of a door, causing it to

become unattached or floating in a scene within a game engine, this would be perfectly
valid manipulation. However, within a parametric based BIM authoring platform, the
same manipulation would violate the built-in parametric constraints, and result in an
exception to occur. As a result, ensuring that Unity adheres to the specific parametric
rules of Revit is a fundamental step in ensuring the compatibility of the BIM authoring
platform and game engine when linking the two. However, due to the complex nature
of parametric modelling, it was not realistic to re-write the parametric constraints
within Unity from scratch. Therefore, our solution to solve this problem is to leverage
the parametric functionality in Revit by querying the Revit API whenever a
manipulation occurs to an element's geometry within a game engine. For example, if
the position of an element is modified in Unity, the new coordinate values are sent to
the Revit client, where an error-check is performed to determine whether the new
coordinates of an element are valid based on the parametric constraints of Revit. If the
new position is invalid, an exception is thrown, and the Revit client sends a query back
to the Unity server, and the element within the Unity scene is automatically reverted to
its previous position.

3.2. REAL-TIME RETRIEVAL AND MANIPULATION OF BIM DATA

The ability to seamlessly transfer BIM metadata between a BIM authoring platform
and game engine in real-time with no loss of data is one of the significant features
provided by UnityRev. Upon running the Revit plugin, the Revit client will connect to
the server and instantaneously send all parametric metadata associated with each
element to the Unity server. The metadata is then retrieved in Unity and stored in a
'RevAttributes' class, which is attached as a component to each BIM element within
the Unity scene. Within this class, the parametric metadata associated with each
element is stored in a dictionary data structure where the Key is the unique name of
each parameter, and the value is the value of each parameter. Real-time manipulation
of BIM metadata is handled by having the Revit and Unity software continuously
checking whether the value of element parameters have been modified. Once a
modification occurs to an element's parameter value, the new parameter value is sent
back to the corresponding software and updated. Whilst the metadata is present within
the Unity inspector, it is not directly utilised within the scene. However, users can easily
extract and use the necessary metadata within their Unity applications. This is
demonstrated in Section 4.2 where lighting metadata is extracted from a Revit lighting
fixture and used directly within the scene by a Unity-based lighting performance
simulator.

3.3. GEOMETRIC DATA MANIPULATION AND SCALING

Initially, we encountered several issues associated with sending the direct coordinates
of elements from Unity to Revit. Therefore, we employed an approach that sends an
offset Vector representing the coordinate change between the previous and current
position of elements over a one-second interval. The purpose of this one-second delay
is to ensure the server is not overloaded by requests due to the Unity engine running at
multiple frames per second. This delay is not required in Revit due to the non-real-time
 UNITYREV - BRIDGING THE GAP BETWEEN BIM 533
AUTHORING PLATFORMS AND GAME ENGINES

structure of Revit when modifying the position, rotation, or scale of an element.

Current game engines typically utilised a three-axis vector-based scaling system a
scale of one is equal to the original scale of the geometric model. In contrast, Revit
splits the scaling of elements into two separate three-axis vectors: BoundingBoxMin,
and BoundingBoxMax. The scale is represented based on the constraints of an element
using an imperial-based measurement system. To convert this into a scaling-based
system supported by Unity, we rewrote a customised scaling system in Revit to adhere
to the scaling requirements of Unity. Additionally, this approach allowed us to bypass
the need to account for different measurement systems when sending scaling data
between the two platforms.

4. Demonstration of UnityRev's Capabilities

The real-time and synchronous capabilities of UnityRev present new opportunities for
collaboration between a BIM authoring platform and game engine, which were not
previously possible. In this section, we present two example applications that use
UnityRev as a workflow to demonstrate how it could be incorporated within practical
use-case scenarios. The first example application uses UnityRev to create a
collaborative design platform between a Revit (CAAD) user and a Unity (VR) user.
The second example application connects the Revit software with a real-time lighting
performance simulator developed in the Unity game engine.

4.1. COLLABORATIVE ARCHITECTURAL DESIGN BETWEEN BIM AU-

THORING PLATFORMS AND GAME ENGINES
The first application demonstrates the ability to create a collaborative architectural
design scenario between a Revit and Unity user. Using the Unity game engine, an
immersive VR application was developed, allowing users to manipulate the geometry
(e.g. position, rotation, and scale) of elements within a virtual environment (VE). The
following two three-dimensional interaction techniques supporting six degrees of
freedom (DOF) were implemented using the 3D User Interaction Toolkit (May et al.,
2019): 3D Bubble Cursor (Vanacken et al., 2007) and Flashlight (Liang and Green,
1994).
The motivation behind the presented example application is to explore and
encourage the development of alternative CAD tools in architectural design and
collaboration. In this case, we demonstrate a scenario where a VR user using alternative
6DOF 3D interaction techniques can manipulate elements whilst simultaneously
collaborating with a desktop-based user using a standard 2DOF mouse input. Although
we believe a cursor is overall more intuitive, and suited for the complex user interface,
and fine movements required in a CAD environment, limited research has been
conducted exploring the potential benefits of using immersive 6DOF interaction in
CAD. We believe one aspect linked to the limited research in this field could be due to
the difficulties associated with integrating sophisticated parametric CAAD modelling
within a game engine making it difficult to realistically compare a CAD platform with
a game engine-based VR application. However, using UnityRev enables this link to be
achieved by connecting the two platforms and providing a layer of support for
parametric modelling within a game engine.
534 K.W. MAY ET AL.

Figure 1. Two demonstrations of using immersive VR interaction techniques (left: 3D Bubble

Cursor, right: Flashlight) to manipulate building elements' positions within the game engine and
update their counterparts synchronously within Revit using UnityRev.

4.2. LINKING A REAL-TIME LIGHTING PERFORMANCE SIMULATOR

WITH A BIM AUTHORING PLATFORM FOR COLLABORATIVE DESIGN
The second application integrates a VR-based Lighting Performance Simulator
developed by the authors (May et al., 2020) using Unity to simulate the lighting
performance of the environment through BIM. The lighting metadata (lumens,
wattage, and range) is retrieved from the BIM model's lighting fixture elements to
initialise the simulated artificial lighting within the game engine. The lux and unified
glare rating (UGR) values outputted from the simulator are sent and linked back to the
Revit model in real-time using UnityRev.
The presented example application not only provides an approach for integrating a
game-engine based simulator directly with Revit, but also autonomously synchronising
lighting performance data back to the Revit model, thus maintaining and updating the
original BIM model. Additionally, typically architects would have to complete a draft
of their architectural design prior to using a cross-platform simulator. However, using
UnityRev provides the ability for users to run simulations much earlier and more

Figure 2. Two demonstrations of a VR-based Lighting Performance Simulator using a heatmap

visualisation to simulate the lighting in the building (left), and the calculated lux, and lighting
evaluation for each element sent directly back to the Revit model (right).
 UNITYREV - BRIDGING THE GAP BETWEEN BIM 535
AUTHORING PLATFORMS AND GAME ENGINES

readily within the design phase. This could potentially allow an architect to identify
design issues and discrepancies much earlier in the design and mitigate the need for
major re(iterations) later, resulting in time and cost saving.

5. Limitations
The initial development of UnityRev could be potentially improved in various aspects.
Firstly, the initial implementation of the network is not well optimised and is designed
to focus primarily on the functionality goals we set out to achieve as opposed to
performance. Additionally, limited user-testing has been carried out on the initial
software, and comprehensive user-testing to identify issues could significantly improve
the usability of the software. We also encountered limitations associated with using the
Revit API; for example, creating new elements is only capable of flowing from a Revit
to Unity direction. Lastly, the dependency of the Revit API to achieve this real-time
two-way communication between a BIM authoring platform and game engine prevents
us from providing future support for UnityRev on alternative BIM authoring platforms.
These limitations are being addressed in the current enhancement of the research.

6. Conclusion
This paper presented UnityRev: An open-sourced software package that enables a
network-based workflow designed to bridge the gap between a BIM authoring
platform (Revit) and game engine (Unity) by creating a real-time bi-directional
exchange of BIM data. In summary, we conducted a literature review in the field and
an analysis of previous CAD/BIM authoring platforms to game engine workflows and
their implementations. We then presented a system overview of UnityRev which
describes the system capabilities and how UnityRev addresses specific gaps identified
in the review and analysis. Next, we presented two example applications as concept
demonstrators that aimed to showcase two practical collaborative use-case scenarios
between a BIM authoring platform and game engine that were not previously
achievable without the use of the synchronous bi-directional workflow being proposed.
The general future directions of this work can be improving upon the software by
addressing the limitations described in Section 5. We are also motivated by the recent
announcements from Facebook and Microsoft that are working towards creating a
metaverse - a network of 3D virtual worlds. We envisage the tools presented in this
paper can provide a bridge between BIM allowing bi-directional communications to
extend the future capabilities of the metaverse. This work was specifically designed to
pilot for a larger project by the authors, which focuses on integrating immersive
displays with building performance simulators for real-time visualisation and
simulation of architectural design. Our broader motivation of this research is to advance
BIM research by encouraging new possibilities and use-cases that can be achieved
through VR/AR-based approaches adopting UnityRev. As described above, we
demonstrated in Section 4.2 that a game-engine based VR building performance
simulator could be efficiently integrated with BIM models to support the architectural
design process. This highlights a scenario where UnityRev could be used in green
building research, potentially leading to deigning more energy-efficient and sustainable
buildings and cities.
 536 K.W. MAY ET AL.

References
Bille, R., Smith, S. P., Maund, K., & Brewer, G. (2014, December). Extending building
information models into game engines. Proceedings of the 2014 conference on interactive
entertainment (pp. 1-8).
Boeykens, S. (2011). Using 3D Design software, BIM and game engines for architectural
historical reconstruction. Designing Together-CAADfutures (pp. 493-509).
Chotrov, D., & Maleshkov, S. (2013, July). Simultaneous bidirectional geometric model
synchronization between CAD and VR applications. In International Symposium on
Visual Computing (pp. 288-297).
Du, J., Zou, Z., Shi, Y., & Zhao, D. (2018). Zero latency: Real-time synchronization of BIM
data in virtual reality for collaborative decision-making. Automation in Construction, 85,
((pp. 51-64).
Edwards, G., Li, H., & Wang, B. (2015). BIM based collaborative and interactive design
process using computer game engine for general end-users. Visualization in Engineering,
3(1), 1-17.
Harlan, J., Schleich, B., & Wartzack, S. (2020). Linking a game-engine with CAD-software to
create a flexible platform for researching extended reality interfaces for the industrial
design process. Proceedings of the 31st Symposium Design for X (DFX2020) (pp. 169-
178).
Khalili, A. (2021). An XML-based approach for geo-semantic data exchange from BIM to
VR applications. Automation in Construction, 121, 103425.
Liang, J., & Green, M. (1994). JDCAD: A highly interactive 3D modeling system. Computers
& graphics, 18(4), 499-506.
Lockley, S., Benghi, C., & Cerny, M. (2017). Xbim. Essentials: a library for interoperable
building information applications. The Journal of Open Source Software, 2(20), 473.
May, K. W., KC, C., Ochoa, J. J., Gu, N., Walsh, J., Smith, R. T., & Thomas, B. H. (2022).
The Identification, Development, and Evaluation of BIM-ARDM: A BIM-Based AR
Defect Management System for Construction Inspections. Buildings, 12(2), 140.
May, K. W., Walsh, J., Smith, R. T., Gu, N., & Thomas, B. H. (2020). VRGlare: A Virtual
Reality Lighting Performance Simulator for real-time Three-Dimensional Glare
Simulation and Analysis. In ISARC. Proceedings of the International Symposium on
Automation and Robotics in Construction (Vol. 37, pp. 32-39). IAARC Publications.
May, K., Hanan, I., Cunningham, A., & Thomas, B. (2019, October). 3duitk: An opensource
toolkit for thirty years of three-dimensional interaction research. In 2019 IEEE
International Symposium on Mixed and Augmented Reality Adjunct (ISMAR-Adjunct) (pp.
175-180).
Motamedi, A., Wang, Z., Yabuki, N., Fukuda, T., & Michikawa, T. (2017). Signage visibility
analysis and optimization system using BIM-enabled virtual reality (VR) environments.
Advanced Engineering Informatics, 32, 248-262.
Nandavar, A., Petzold, F., Nassif, J., & Schubert, G. (2018). Interactive Virtual Reality Tool
for BIM Based on IFC-Development of OpenBIM and Game Engine Based Layout
Planning Tool-A Novel Concept to Integrate BIM and VR with Bi-Directional Data
Exchange. Proceedings of the 13th International Conference on Computer Aided
Architectural Design Research in Asia (CAADRIA).
Pelosi, A. W. (2010). Obstacles of utilising real-time 3D visualisation in architectural
representations and documentation. Proceedings of the 15th International Conference on
Computer Aided Architectural Design Research in Asia / Hong Kong (pp. 391-400).
Vanacken, L., Grossman, T., & Coninx, K. (2007, March). Exploring the effects of
environment density and target visibility on object selection in 3D virtual environments.
In 2007 IEEE symposium on 3D user interfaces. IEEE.

View publication stats

7.3
Generating Globally
Unique ldentifiers
for Game Obiects
Yongha Kim, Nexon Corporation
[email protected]

¡f ame objects that synchronize across the nerwork need identifiers (IDs) ro dis-
lI..i-irr",. .".h oth.r. O.r increasingly common multiselver sysrems that have
massive user access [Svarovsky02], millions of game objects are potentially generated
and destroyed every minute, and some of them need to be stored in, or synchronized
with, a database. If each game object is not identiûed uniquel¡ the objects may con-
flict, and dupiication of data is possible. This results in difficult synchronizarion of
game objects between the game seryers.
Because of this problem, generation of Globally Unique Identifiers (GUIDs) is a
required feature for game object systems of online games. Additionall¡ if these
GUIDs can contain useful information, such as the type of object and the time of
object creation, the GUIDs can be effectively utilized for tracing and managing
objects. This article suggests a method for generating64-bit GUIDs safely and effì-
cientiy using an ID server and object factones.

Requirements for Game Obiect GUIDs

First, let's look over what requirements we have for game object GUIDs and in what
ways we can satisft those requirements.

Sufficient GUID Space

To manage game objects, issuing an ID as a handle to the game object's pointer is
common not just in online games, but also in standalone games. Generall¡ 32-bit
unsigned integer data rypes are usecl, which on most platforms can create approxi-
mately 4 billion IDs. In most standalone games, this is more than enough IDs ro
accommodate all the objects that will be created. Some developers even divide the 32
bits into two 16-bit words, using the upper 16 bits to classify the object's rype and the
624 Section 7 Network and Multiplayer

lower 16 bits to store the ID of actual object instance. But for online games, especially
MMORPGs where persistent worlds need to be maintained, a GUID space of 4 bil-
lion isnt suffìciently large. In extreme cases, 10,000 game objects requiring GUIDs
can be created every second, filling the 4 billion ID maximum within five days.
Since Nexon, Incorporated released Nexus TK in 1996 (the first MMORPG),
they have released numerous games that require large numbers of unique object iden-
tifiers. Some cf them used 32-bit IDs; and in time periods that ranged from a few
months to three years, these games exhausted their entire 32-bit spáce. Some that
used 64-bit IDs also exhausted their potential space when bits were improperly uti-
lized. \JØhen ID systems filled up during service, ir was necessary to change ID-issuing
methods and replace every ID issued in the past, which was really painful. It was real-
ized that when issuing IDs, a secure space was needed that could be used for at least
10 years.

Efficiency
Creating a l29-bit GUID with compounded time or a MAC address is already widely
known IITU-T X.667). Howeve! using 16 bytes for an ID is expensive in processing,
persistent storage space, and network bandwidth. In addition, existing 128-bit GUID
creation methods are too complicated to use in object factories expected to produce
10,000 objects per second. For game object IDs, there needs to be a more affordable
data type and simple creation methods.

Globally Unique Gharacteristics

Since game objects move and synchronize across numerous systems in online games,
IDs that are locally unique on the creating system can clash during synchronization.
If mo different game objects own the same ID, different parts of the system may be
using different object properties or even entirely different object rypes in their pro-
cessing! The real problem here is that when those errors occur, they are very difficult
to detect and even harder to fix.
Let's remember the following requirements of a good GUID sysrem:
. Uniqueness of past and future IDs must be guaranteed.
. Uniqueness of IDs created by different object factories must be guaranteed.
. If IDs are synchronized ac¡oss databases or systems, the uniqueness of the ID
must be guaranteed across those databases and consistently refer to the same
game object.

lnformation About Obiects

An ID that contains information about the game object it identifies offers a number
of advantages over one that doesnt. For example, in most circumstances, system logs
 625
7.3 Generating Globally Unique ldentifiers for Game Obiects

only write IDs, and not additional information about the game object itself.
Seman-

tic information in an ID can increase rhe usefulness of these logs in diagnosing

errors.

It can also be helpful for data-mining trends, such as item populariry and other user-
that
influenced .-.rg..r, properries of thè persistent world. F.xamples of information
be .orrt"i.r-.d within an ID are creation time, the factory from which it was cre-
could
ated, and the ryPe of game object'
4

9:.*":rlirg 99.J9: above'

Now we explain how to generare 64-bit GUIDs that satis$' the requirements
As shown iå Fig,rr. 7 S.ll the 64-bitGUID is constructed from wo 32'bit parts that
are creared by rip"r"r. processes. The upper 32-6ittime tag is generated
by a globally
"ID i. th.tt to the object factory. The
owned ,yr..- ."ll.d ,tr. server" supplied
"Ãã The time tag and serial num-
objectfactory generares the lower 32-6itserial number'
ber are combined to create the final 64-bit GUID'

Issue
ID Server Time tag
Object Factory
----------.->

Attach
Serial nunrber

GUID

FIGURE 7.3.1 GLUD generatizn. A global ID seruer

generãtesatime tto
A seriøl number b
whicb is combined witb the time tag, and tbe f'nal
64-bit GUID is issued.

\X/hile the dme tagt uniqueness is guaranteed globall¡ the local uniqueness ofthe
^final
serial numbe, .o-pl.i., the gloU"l CUIO. Also, the ID server takes responsibil-
iry for the time ,"gi g....",ion, object factories bear responsibiliry for generetion
"nd
oiserial .rrrmb..s. A, a result, the structure becomes simple, roles are clear, and man-
aging ID generation is efficient.

Generating Time Tags

and 12-bit
As shown in Figure 7.3.2, timetags are formed with 20-bit time stamps
The value is incre-
chunk numbers-. Time stamps use January 1,2005 as 0x00001.
mented every 10 minutes and can be used for 20 years'
626 Section 7 Network and

OxTTTTTCCC T: Time stamp

20bits l2bits C : Chunk number
FIGURE 7.3.2 Tíme tag formøtion. In bexadecimal notation,
T is tbe üme stamp, C is the chunþ number.

If the game is åtp..t.d to be in service even longe¡ lowering granulariry

so the
time stamp is increased every 20 minures will allow you to ur. it fo, ao y.á".
Th.
chunk number is the cumulative count of time tags issued with the s"me tim. ,,"-p.
It increases every rime an object factory asks for a time tag from the ID server. \7h;
the time stamp increments, the chunk number resers ro 0x000.
Usin of 4,096 unique time tags
every10 tags be globally ,r.riq.r., å
there sho difficultin ,."Iiry oni rát,r_
tion is to number and use them as .r.riq.r. identi_
fier for each ID server. "

Generating Serial Numbers

The ct factories and is composed of B bits for object
Vpe, 16 bits of instance number (see Figure 7.3.3).
The to. reflect the type of game object tã which the
GUID refers. You can assign object rypes for every class of game object, but itt not
necessary. In MMORPGs, the most troubling, frequendy generated game objects are
items, so it may be helpful ro manage these by subdividing rhem, even if they share
the same class. The reserved portion is for dealing with exceptions or future require-
ments. If not needed, it can hold the object factoryt unique number or rype.

0x O O RRI I I I o:Objecttype
86its' s6iß Giñ= R :Reserved
I : Instance number
FIGUBE 7.3.3Serial ruumber generøtion. In
hexadecimal notation, C is the object type, R is
reserued, and I is tbe instance number

The instance number, like the time tag's chunk number, is a value increased every
time a serial number has been issued. \X/hen an object factory acquires a new rime tag
from the ID server, the instance number resets to zero. If there is a separete instance
number counrer for each rype of game object, object factories can generare n x 65536
serial numbers with one time tag, where n is the number of object rypes.
v.g Generating Globally Unique ldentifiers for Game Obiects 627

Handling Exceptions
A variery of problems can arise with a global GUID system if needs are not properly
anticipated and handled, including overflow and securiry issues. Here we briefly dis-
cuss how such problems can be addressed.

Generating Temporary lDs for Use

in Glient Obiect Factories
A game player's client might have object factories to replicate (synchronize) and
.o.rt.ol game objects, but for securiry reasons, the client's ob.iect factories usually
shouldni have the aurhorirF to create new game objects that can affect the global
state. Sometimes, though, theret a need to make temPorary game objects that do not
synchronize with other processes-for example, to manage the UI ot'respond to local
evenrs with a game object. Giving the object factory restricted authorization to gener-
ate IDs would be one solution. For these types of game objects, set the time tag's time
sramp ro 0x00000 and declare rhe serial number's object type as different from the
global objects that need synchronization.

Chunk Number Overflow

Chunk number overflow occurs when the chunk number reaches OxFFF. It occurs
when object factories exhaust their instance numbers too rapidl¡ or when there are
roo many object factories requesting time tags from the ID server. Itk important that
this exception never occurs; and if necessar¡ the number of object factories accessing
the ID sàrver should be restricted. For example, the normal users' client object facto-
ries should nor access the ID server. The number of object factories using time tags
supplied by the ID server should probably be kept under 100.
If this exception occasionally cannot be avoided, increase the time stamp and
reset the chunk number. If the time stamP was already incremented when the appfo-
priate time comes to update it, then itt not necessary to increase it again.

lnstance Number Overflow

Object factories can only combine serial numbers with given time tags, so when the
instance number reaches the maximum, no more GUIDs can be generated. \X/hen
this happens, object factories can request a new time tag from the ID server. This
pro..r, -"y not be instantaneous, so to generate GUIDs right awa¡ use the reserved
To prevent this, when
þortion of the serial number for the instance number overflow.
obj.., factories exceed a certain instance number, for example 0x8000, they can
preacquile the next time tag from the ID server.
 tt
Ì

62A Section 7 Network and Multiplayer

Gonclusion
Naive generation of IDs isnt much of a problem, but designing an ID-issuing
system
that doesn't have to be modified during se¡vice is a littlã triJ.y. \x¿. hop. ihát
ou.
experience, learned through mistakes, comes in handy for you.

References

IITU-T x.667'l ISO/IEC 9834-8:2004Information Technology, ,.procedures for the

operation of OSI Registration Authorities: Generation anã R.gistration
of Uni-
versally unique Identifiers (uulDs) and their use as ASN.r bb¡.ct Identifier
Components." ITU-T Rec. X.6G7, 2004.
[svarovsþO2] svarovsþ,Jan, "MinimizingLatency in Real-Tme strategy Games.,'
Game Programming Gerns 3, Charles River Media
,2002.