Category: Manual (page 2 of 2)

Archimatix Turtle Script API

Turtle graphics, originally developed as a feature in the Logo programing language, is an important tool for the description of line shapes. Each line of a turtle script draws a 2D line relative to the current position of the turtle cursor. While this may seem conceptually simple, it is a powerful concept in parametric graphics. For example, to draw circular arc, with five segments, one need not calculate each of the five vertices, if one can simply tell the turtle to draw an arc to the right through 45 degrees at a radius or 3 units. The command in turtle script may look like this.

arcr 45 3 5

Archimatix has its own implementation of a turtle scripting API, borrowing more closely from GSDL, a 4th generation language developed by GIST, Inc., than from Logo.

Absolute Commands

mov x y <a>

Before drawing a shape, we have to place the turtle somewhere in 2D space and point it in a certain direction.  This command moves the turtle to the point x, y with out drawing any lines. The optional argument a tells the turtle in which direction to face. The default direction is 90 degrees.

 dir a

dir sets an absolute direction.

This command, which reorients the turtle to a new direction,  can be called anywhere in the script whenever you would like it to abruptly change direction.

drw x y

Draw a straight line from the current point to x, y.

closed true|false

Closes the shape. Shapes are open by default. Note that you cannot yes an “=”, only a space between the function and the value.


Comments in follow the standard double-slash. Any text after this will be ignored by the script parser.

Relative Commands

rmov dx dy

Moves the turtle pen tip to a new point and resets the current direction to the line from the pervious to the moved point..

turnl avoila_capture-2016-12-03_07-37-00_pm

Turns the current direction a degrees to the left.

turnr a

Turns the current direction a degrees to the right.

fwd c <d>

Draws a line c units long in the current direction. For example, fwd 30, or if using a parameter, fwd height. Optionally, d offsets the point from the directional axis so that a diagonal line will be drawn c units forward and d units perpendicular to the current direction. This offset is useful for drawing a shape that fits with in box, but that has corners chipped off, so to speak.

For example, this is a box with the two top corners inset:

mov 0 0 angle
fwd height/2
fwd height/2 -inset
left width-2*inset
back height/2 inset
back height/2

 back c <d>

voila_capture-2016-12-03_07-57-33_pmDraws a line c units long, backwards, or in the opposite of the current direction.

right c

voila_capture-2016-12-03_07-58-27_pmDraws a line c units long to the right, without changing direction.

left c

Draws a line c units long to the right, without changing direction.

arcr a r s

voila_capture-2016-12-03_08-13-10_pm Draws a circular arc of a degrees, with a radius of r, beginning at the current point and tangential to the current direction and arcing to the right. After the command is execute, the turtle’s direction is automatically turned to the tangent of the end of the arc. For example, with a dir 45, arcr 45 3 5 will leave the turtle at a direction of 0 degrees so that if you follow with a fwd 4, the turtle will draw a line 4 units long at an angle of 0 degrees.

arcl a r s

Similar to arcr, but curving to the left.

Mathf Functions

All of the Mathf Functions have been mapped to AX Turtle Script. They follow the general form of:




A rad2degs conversion goes on inside the function, so the argument is in degrees.

Another example is

atan(x, y)

Mathf variables can also be used in your equations such as x*PI




AX Script has a limited looping syntax that basically repeats the code with a counter.

loop repeats <counterName> <step>

The loop command opens the scope of the loop. The repeats argument specifies the number of times to run through the loop. Th optional counterName  is a string name for the internal counter variable. The optional step is a number or expression that tells the loop how much to advance the counter by each time.


Teminates the scope of the loop.

In this example, the loop will draw a dotted line with 10 unconnected segments.  The counter variable i multiplied by span will start an unconnected line segment every 5 units with a segment length of 2.5.

let segs 10
let span 5

loop segs i
    mov i*span 0 90
    fwd span/2

In this example of a parametric gear shape, the loop will draw a gear shape with teeth number of teeth. No counterName is needed here.

let degs 360/(2*teeth)
mov radius 0 90

loop teeth
    arcl degs radius segs
    right tooth
    arcl degs radius+tooth segs
    left tooth

Note that in the above gear, all variables are Parameters in the node except for degs, which is a temporary variable defined in the script.

This example will produce a stair shape:

loop steps-1
fwd ariser
left tread

Conditional Block

The conditional command does not use parentheses. There is currently no else or else if, though they are planned.

if var1 GT var2

You can also reference a bool parameter

if bool


Closes the conditional block.

The conditional uses the boolean operators:

LT for "less than"

LE for "less than or equal to"

GT for "greater than"

GE for "greater than or equal to"
EQ for "equals"

NE for "not equals"

There is currently no elseif, else, continue, or break but theses are planned. The workaround for else is to create a second block with the opposite conditional.


Terminates the turtle script execution early.

Parameter and Variables

set parameter value

The set command will set a parameter based on the parameter’s name. This is particularly useful for defining a max and min value for a parametr.

set width greater(width, .01)

Or for making sure a parameter never rises above another:

set width lesser(shaftHeight, columnHeight)

Thus, even as the user drags a handle or types a value in a float field, it will not break the rule defined in the set command.

let tempVar value

The let command defines or resets a temporary variable. This is useful in the case that you have a long expression that you need to use in multiple function calls while drawing.

let buildingLength sine(angle)*buildingHeight

To reset a temporary variable, you must use let again.

let buildingLength 5

Special Variables

DetailLevel - This is a read-only variable that reflects the current detail level setting for the model.

Absolute Commands (Cont.)

Special Curves

bezier   ax  ay   ahx  ahy   bhx  bhy   bx  by   segs

Draws a cubic Bezier curve between points a and b. The curve is modified by handles defined by absolute endpoints ah and bh.


molding  type  ax, ay  bx, by segs, tension

Moldings profiles are Shapes that have a very common use in architecture. This command uses one or more bezier curves to and makes certain assumptions about the handles so that you do not have to construct a sequence of beliers curves yourself. Borrowing from the timeless art of molding design, we have a few types that can be called in the molding command, including cove, ovolo, cyma recta, cyma reversa and onion.



An example of the molding command can be seen in the Turtle script for the 2D Library item CymaRectaMolding, which adds a square base and an apple lip to the basic molding curve of type “cymarecta”.

Mathf Functions

AX Turtle script also includes many of Unity’s Mathf functions. They are implemented as a straightforward mapping. For example, Mathf.Abs(float f) is written in AX script as:

let val=Abs(float f)

//or, for each function call, you can use lower case as well.

let val=abs(float f)

The Mathf functions currently implemented are:

Mathf Constants:


Mathf Functions
Atan2(opposite, adjacent)
Ceil(var, a)
Max(var, a)
Min(var, a)
MoveTowards(var, a, b)
MoveTowardsAngle(var, a, b)
Pow(var, a)
Repeat(var, a)

Int(var) // Synonym for Mathf.FloorToInt(a)

range(var, a, b) // Synonym for Mathf.Clamp(var, a, b)

greater(a, b) // Synonym for Math.Max(a, b)

lesser(a, b) // Synonym for Mathf.Min(a, b)

Other Functions

modulo( float, int)
// modulo gives the remainder form a division. The c# modulo expression 90%30 would give 0, meaning 30 is a multiple of 90. In AX script, this would be modulo(90, 30)

IsEven(a) // shortcut for (a % 2) ? 0 : 1;

Know Your Relations Better


Simple Relation for stacking: the Cylinder is always atop the Box.



Artful parametric modeling is all about managing relationships. Not the personal kind, but the algorithmic kind.

By defining meaningful relationships among your parameters, you can encode a new and powerful morphological genus – creating a new species DNA, as it were, that can be used to generate hundreds of variations of models.

There are two kinds of parametric relations in Archimatix: 1. inter-nodal connections, and 2. parameter expressions. In this tutorial, we will demonstrate inter-nodal connections.

When you connect parameters from different noes to each other, you are authoring behaviors for your parametric model. When you modify one parameter, all sorts of changes may ripple through the model according to the logic you encoded via Relation connections and mathematical expressions within the Relation. Furthermore, these Relations may be bi-directional, meaning that you can change a parameter anywhere in the graph and changes will ripple out from that parameter.  The default mathematical expression set  when you fist specify a Relation is equivalency, or simply “=”..

Equal Relations

A common case for an equals Relation is when you want one object to always sit atop another, regardless of how tall the bottom object is. In the example to the right, the behavior illustrated is that the blue Cylinder is always atop the red Box.

Try This!

To set up this parametric behavior:

  1. Choose a Cylinder and a Box from the 3D Library (left sidebar in the NodeGraphWindow.
  2. Unfold the Controls of the Box and the

    A simple “equals” expression.

    Transformations of the Cylinder.

  3. Click on the red connector box on the parameter Extrude in the Box node palette.
  4. Click on the red connector button next to the Trans_Y parameter on the Cylinder node palette.
  5. To test: either click on the Box in the SceneView and then drag the green knob to make the Box taller, or click on the Cylinder and then drag the Y-Axis Position Handle.

You will notice that the relation is bi-directional. Modifying either parameter will alter the related parameter. This is a departure from other parametric modelers which feature uni-directional relations. The benefit of bi-directional is that, when playing with a parametric model in the SceneView, you can click just about anywhere you like and start modifying, rather than searching for the “master” parameter.

However, this freedom is not free: the bi-directionality requires inverse expressions to be input. In the case of our simple example, we did not edit the expression found in th relation, relying on the default equals expression. Let’s take a look at how we might make a slightly more complex relation expression.

Expressing Relations

When would like to have more interesting Relations, you can use the ExpressionEditorWindow that pops up when you click on the green button at the center of the Relation connector cable. In the ExpressionEditorWindow are two text fields allowing you to edit the bi-directional relationship between the two parameters.

Try This!


Simple piston with sinusoidal relation to shaft rotation.

Lets say that we would like to simulate the movement of a piston relative to the rotation of a crankshaft in a car engine. The piston rises and falls sinusoidally as the shaft turns. The expression is Piston.Trans_Y=Sin(Crankshaft.Rot_X). Lets go ahead and set this up:

  1. Choose a Cylinder from the 3D Library.
  2. Click on the name button at the top of the node palette and rename it “Piston.”
  3. Use your copy and paste short cuts to create a second Cylinder. Name it “Crankshaft.”
  4. Next to the Transformations foldout, click the axis button until it show “X.”
  5. Open the Transformations foldout and choose “Align_X” choose “Center.”
  6. Click on the Crankshaft in the SceneView and reduce the radius a bit.
  7. Connect the Piston.Trans_Y to the Crankshaft.RotX.
  8. Try rotating the Crankshaft – the Piston will continue upward or downward.
  9. Click on the green button in the middle of the red connector cable.
  10. archimatix-2016-09-07_11-47-12_pm

    The Edit Relation window lets you define the bi-directional mathematical expression.

    In the ExpressionEditor, in the field filled in with Crankshaft.Rot_X, change the expression to: Sin(Crankshaft.Rot_X) and then click on the Save button just below.

  11. Test by rotating the Crankshaft again. The Piston will oscillate up an down.
  12. Make the Piston more responsive to the rotation, decrease the stroke and lift it higher above the Crankshaft by editing the expression again to be: 1.5+.5*Sin(2*Crankshaft.Rot_X)

We will save more elaboration on this with the addition of a piston rod, etc. please see the tutorial The Parametric Engine.


Best Practice: Relating Translations


A simple parametric behavior: the red Box and blue Cylinder are always translated to the end of the gold Box.

If you find yourself connecting the Trans_X for one node and the Trans_X of another node to the same source, it is probably better to group the two nodes together with a Grouper and then relate the Grouper’s Trans_X to the source. This is analogous to parenting two GameObjects to an “Empty” GameObject in the Unity hierarchy window. While Archimatix can handle lots of relations, by using relation connections where a grouping would do, you will add more visual complexity to the NodeGraphWindow.

For example, the animation to the right depicts a parametric behavior whereby the red Box and the blue Cylinder are always positioned at the end of the gold Box. There are two ways we could encode this behavior:


Setting translations for each node will lead to many redundant Relations.

Method 1: This method is not preferable, but happens commonly while building up a graph. The Trans_X of the Cylinder has been related to the width parameter of the rectangular plan of the gold Box with an expression of Cylinder.Trans_X=Rectangle.width/2. When the red Box was added to the graph, a similar relation was added between the gold Box and the red Box, as shown in the figure to the right. Now when we drag the Handle for the Rectangle width, the blue Cylinder and the red Box translate accordingly.

The down side of this is that we have two connections and we have to enter the same mathematical expression twice (for the Cylinder and for the red Box). If we want to change that relationship, we have to change it in two places. Also, the graph will quickly get cluttered if such translations are maintained with Relation connections all the time.


Grouping Node

Grouping nodes allows fewer Relations.

Method 2: Alternatively, we can feed the Cylinder and Box into a Grouper and then relate the Trans_X of the Grouper to the width of the Rectangle.

The behavior of our parametric model will be exactly the same, but now, if we wish to edit the expression in the relations, we are editing in only one place. Also, the graph will have fewer parametric relations, which tends to make the graph more legible.





The BiChamferSide is a shape geometry that features independently adjustable top and bottom chamfers and a taper. It is most useful as the default sweep profile for an Extrude Node.

Archimatix 2016-09-05_08-44-20_AM

Node Selection

This page coming soon!


This page coming soon!

Lightmapping With Archimatix


Archimatix (AX) can prepare the models it creates for Unitiy’s Global Illumination (GI) , both realtime and baked. Since AX generates models frequently as parameters are modified, the system makes some assumptions about when in your workflow you are ready to have Unity render the metadata that supports GI.

Voila_Capture 2016-08-21_04-20-15_PM

Arch with Global Illumination

General Workflow

Depending on the complexity of the model, pre-computation for Unity’s GI lighting  can take a significant amount of time (to say the least!). By default, Unity tries to initiate this computation any time it senses that static meshes in the scene have been transformed, added or deleted. Although useful in many cases, this default mode of building the lighting model becomes burdensome when modeling with Archimatix, since, as you drag parameter AX handles in realtime, you are usually regenerating hundreds of meshes per second. Even after you stop dragging and AX generates actual GameObjects, you are likely to keep on modifying and tweaking parameters. While this fluid mesh generation is part of the magic of AX, such rapid changes set the  automatic lightmap build into unnecessary overdrive. There are two ways to avoid this this situation.

The first way to avoid unnecessary computation while modifying the parameters of a model is to simply turn the Auto build mode off. This is done by opening the Unity Lighting Window and unchecking the “Auto” checkbox, as show in the image to the right. With Auto off, you can modify AX meshes to your hearts content with out setting off the lighting computation. When you are ready to see the model rendered with GI, click the manual “Build” button to the right of the “Auto” checkbox.

However, if you have a preference to leave “Auto” on, then you can temporarily  disable Lightmap Static flags for your entire AX model by making sure the Lightmap Flags Enabled checkbox in the Inspector for the model is off. This means that, as AX generates GameObjects with meshes, it does not add the Lightmap Static flag to the the GameObjects and the light mapper will not be aware of the changes to the mesh. With this approach, you can model as much as you like, and then when ready to see it rendered with GI, you can click the Lightmap Flags Enabled checkbox.

Note: The Lightmap Flags Enabled parameter for the model is off by default. This means that, when you first create an AX model, you must check this to on before building the lighting.

Once you have finished a session of modeling and tweaking, and you are ready to take a coffee break, you can click the  “Lightmap Flags Enabled” checkbox in the Inspector for the model. If “Auto” is on, the light mapping will shift into high gear. Otherwise, after checking Lightmap Flags Enabled go to the Lighting window and click on the Build button.

In either mode, when the lighting model is being built, it will only take into consideration the objects that have been generated by nodes that have been designated as Lightmap Static, as we shall see next.

Lightmap Static Flags

If a AX ParametricObject, such as the Extrude_9 in the figure to the right, is set to LightmapStatic (red arrow), then when a GameObject gets generated AX, its static flag will be set to Lightmap Static (so long as the Lightmap Flags Enabled is checked when the model is built), and the Unity GI system will treat it as such when rebuilding. This static flags setting is analogous to the flag options for any GameObject in Unity, with the difference being that the flag is set internally in the AX node and transferred to GameObjects when they are built by AX.

When you set the static flag for a node, all its upstream nodes will be set to the same flags.

Secondary UVs for Baking

If you have selected Baked GI in the Unity Lighting Window, then you will want to have SecondaryUV’s generated for the meshes created by Archimatix. Since generating these extra UVs, which are used by the Unity lighting model to created rendered lightmaps, takes some extra computation, you must recreate the secondary UVs each time you bake the lighting.

The checkbox called Create Secondary UV’s appears only after the Lightmap Flags Enabled checkbox has been checked. When you check it, the Secondary’s will be generated for any meshes generated by nodes that have had their flags set to Lightmap Static..

Even if you check the Create Secondary UV’s, this box will become unchecked after the AX model has finished one of its frequent builds.


Although the Archimatix Shape Library ships with a variety of parametric shapes, such as Circle, Square, RoundedRectangle, Cross, IBeam, etc., that can be added and subtracted to each other, it may be worthwhile for you to “code” your own Shapes using Turtle scripting and defining your own SceneView Handles.

There are three main areas of focus to consider when authoring parametric shapes:

  1. Parameters
  2. Handles
  3. Logic

This list generally reflects the order of implementation of your custom Shape. When designing a Shape it is useful to create a drawing that helps you (or the users of your Shape) visualize its geometry and the parameters that control it.  It is also an interesting exercise to begin with parameters and handles since many geometries can use the same controls.

Archimatix 2016-03-26_11-10-26_AMIn the figure to the right, we see an example of a diagram that just shows parameters and handles for a Shape that might be a thought of as a molding profile.

Each handle in the diagram, represented by a red dot, can be defined in the handle editor to adjust certain parameters when dragged. For example, handle B could control both the edge and width parameters while handle A controls only width and handle C controls only the overall height.

These parameters and handles can be added to the node before any scripting is added to actually draw the geometry. In fact, this same setup could be used to control a variety of geometries. Below are some examples.
Archimatix 2016-03-26_11-25-09_AM
Particular Shape geometries are based on logic that uses the parameters as variables. The logic is coded using simple turtle graphics scripting implemented right in the node palette.

Using the above molding example, let’s take a look at how to create parameters and handles and then use them with logic.

Adding Parameters

Parameters serve as  variables in the logic of the Shape. For example, in a rectangle Shape, the main parameters are width and height. These parameters are then used to position the SceneView handles and as variables in the description of the rectangle in the logic section of the node palette.

Since we have these same parameters specified in our molding diagram above, it may be best to start our custom Shape with an instance of the Rectangle from the AX Library (choose the Rectangle Shape from the left-hand sidebar of the NodeGraph EditorWindow).

To modify the Rectangle Shape, we will need to add an new parameter called edge. In the Archimatix NodeGraph Editor Window, the parameters are found under the Geometry foldout in the node palette for the parametric shape. You can add as many parameters as you like to the node by clicking on the “+” button at the bottom of the parameter list. Once the add button is clicked, a new parameter will be added to the node and opened for editing.

Naming a Parameter

When the parameter is opened for editing, the name field will be an editable TextField. When choosing a name, be sure not to leave any spaces. This is important since you will need to reference this name as a variable in the script for the Shape’s logic.

For now, we will only edit the parameter’s name, however, you may notice that, in addition to editing the name, you can choose the data type for the parameter (float, int or bool) and start to define expressions for how other parameters in the node should be adjusted if this parameter is modified.

For our molding example, edit the name of the new parameter to be “edge.”

Creating a New Handle

In the Handles foldout of the node palette, you will find a list of named handles. Each of these generates a SceneView handle and defines the behavior of that handle with respect to how it modifies the node’s parameters.

Before adding our new handle, we need to adjust the current width and height handles to adapt them so they are not centered on the origin. Go ahead and click on the width handle and edit the position expression for X to width instead of width/2. Also, adjust the expression to width=han_x. Don’t worry that the Shape is not following these handles yet. Then click on the height handle and set the Y-position to height instead of height/2 and edit the expression so that it is height=han_y.

To create a handle for the edge parameter, click the “+” button under the Handles foldout and name the new handle “edge.” The default type of handle, “Point,” is fine for this. In the position fields, we want to describe where the handle should appear. In this case, the x-position of the handle should be width and the y-position should be the expression height-edge.

After entering these expressions into the x and y fields for Position, the handle should immediately appear in the SceneView, though it is not draggable yet. To make the handle interactive, we have to tell it how to set its parameters when dragged. To do this, edit the first expression for the handle to “width=han_x”. This says that what ever the x-value for the handle is, this should be the value for the width of our Shape. In the vertical direction, we will use the y-value of the handle, or the han_y. Click the “+” button to add a new expression and set it to “edge=height-han_y”.

Now you should be able to drag your new handle and reset the parameters for edge and width.



Now that we have our parameters (and SceneView handles to modify them), we can use these parameters to “draw” the geometry of our shape.

To draw, we use a sequence of commands that tell the virtual pen tip where to go next from the previous line of script. The mov x y dir  command tells the pen to move to the position x, y and orientate itself in direction dir. If the next line of script is fwd 10, then the turtle will draw a line from the starting x,y position to a point 10 units out in the current direction. For a full list of the AX turtle commands available, please see the API.

For our example, let’s start out with a simple molding that features a chamfer. Here is what the turtle script should look like:

mov width 0 90
fwd height-edge
arcl 90 edge 5
fwd width-edge



As you can see, after entering this script into the Logic TextArea of the node palette, we are using the parameters, or variables, width, height and edge to draw our Shape. Now, dragging the “edge” handle allows us to generate permutations such as these:

Archimatix 2016-03-27_12-57-33_AM Archimatix 2016-03-27_12-57-28_AM Archimatix 2016-03-27_12-57-24_AM

And now the shape is ready to be used for the section of a PlanSweep:

Archimatix 2016-03-27_01-01-57_AM

But, what if we wanted the molding to have more detail? Perhaps something to like the first section above with the quarter-round in the bevel. Lets recode the geometry a bit, but with the same parameters and handles.

mov width 0 90
fwd height-edge
left edge/3
arcl 90 edge/3 5
right edge/3
fwd width-edge



In this version, we have added a bit of mathematical expression such as edge/3. The resulting molding looks like this:

Archimatix 2016-03-27_01-09-18_AM


For full documentation on the Archimatix Script API, click here.






Getting into Shapes

Shapes are important in Archimatix because they are at the root of mesh generation. Unlike a topological modeler, where vertices and polygons are copied and manipulated directly, Archimatix is a parametric modeler in which meshes are typologically generated from sets of rules and modified by controllers. These rules and controllers can be authored by you or you can combine the dozens parametric shapes that come bundled with Archimatix. These “living” smart shapes can be rigged up with parametric mesh generators to author your own typology of vehicles, weapons, buildings and urban fabric. A shape, while itself parametric, becomes a parametric generator of many varied meshes.

While archimatix provides the ability to edit shapes topologically, for example, clicking on a vertex and moving it, the real power of the modeler comes in when shapes are manipulated by handles that embed logical relationships.

A simple example of a parametric shape that would be hard to make topologically, one vertex at a time,  is a circle. Many things in the world are generated from circles–barn silos, cannon barrels, mot & bailey castles, etc. One need not define each point in the circle, only a center and a point at a given radius away. The rules of a circle quickly generate all the vertices that form the shape. While no one would try to create a circle with a topological editor, the example provides a sense of the power of parametric curves with relatively few control handles.

Archimatix not only provides a host of bundled parametric shapes that reflect common architectural, mechanical and mathematical typologies, , but it supports the authoring of custom parametric curve logic that lets the designer define what handles would be best for that shape.

For example, let’s say that you want to create a certain kind of hut that would be made from an “I” shape with a semicircle extending off the shape somewhere. While each hut in the village is unique in its proportions, all huts share this I-with-a-circle” typology, which itself is a function of the villagers’ culture. If such a shape is not already in the library, based on example already in the library, you can “code” one and decide what parameters should be used to allow others to berate many I-shaped house variations. This shape can then be rigged up with mesh generators to easily generate dozens of unique houses that share a certain art. In this sense, you can make a new “type” of shape that can be instantiated in many permutations that go beyond the basic transformations of translation, rotation and scaling, thereby generating village after village in a certain cultural domain of your world.

Over time, you may build up a library of shapes that are specific to the art direction of your game. These shapes may be used by other artists on the project to make things “in the art” of your shape, while no to instance of the shape need be duplicates.


Newer posts

© 2021

Theme by Anders NorenUp ↑