No announcement yet.

An Introduction to DesignScript

This is a sticky topic.
  • Filter
  • Time
  • Show
Clear All
new posts

    An Introduction to DesignScript

    DesignScript is a fantastic piece of the Dynamo puzzle.

    It allows you to clean up messy definitions, nest node objects within each other and cycle through data using Replication Guides in a pretty efficient manner.

    Node2Code (Dynamo 0.8.2 and above) will allow you to convert standard nodes to DesignScript, but will do so in a rather inefficient manner.

    The basics of DesignScript are as follows:

    There is a triumvirate of Creators (+), Queries (?) and Actions (Zap), that mirrors the node style in the library.


    Creators will colour themselves green as shown below. Any time you partially type in a Creator, it should allow a dropdown menu showcasing the options you have.


    Creators require Creation Methods. This is how your creator is to be formed and are coloured blue. A couple of examples are shown below:


    After you have your chosen Method (Also available by a dropdown menu after your dot nomenclature), you need to put in values that the method requires to create your creator. These are always bound by brackets, and when you type in your open bracket you get an input prompt. You can cycle through this prompt with the arrow keys (For multiple creation methods). In the following example we can create a point by either a simple X and Y, or by X, Y and Z.


    The prompt will tell you what type of data needs to go in, as well as give you the name.

    After we put in our values, we close the Creator off with a Close Bracket and Semi-colon. The semi-colon wraps up that bit of code and calls it a day and is required for all DesignScript code.


    That's the basics of Creators. But usually we need to use this data later on in the piece (Rather than simply using it's wire output), so we give it a name. After giving it a name we can call that thing by its name and apply queries or actions against it.

    This is achieved by giving it a name followed by the equals sign as shown below:


    Once we have this we can move onto our second item in the triumvirate, Queries, which also show up blue. It will, however, only show up blue when fully completed and written with the correct Title Casing.

    Queries are achieved by putting a dot after a proper thing and subsequently writing out the query. Unfortunately, there is no dropdown list for these. You have to either know, or check the library - but it becomes second nature pretty swiftly.

    In the case of Queries you don't use brackets (As it's simply querying and you don't need any values for a creation method).

    An example of a query is shown below, where we want to get the Z-Value from our point, or get the Number of Cuves from a polycurve:

    Query_Zvalue.JPG Query_NumberOfCurves.JPG

    Any Query for that creation method type that can be done by nodes, can be done by code. If in doubt either use Node2Code to change a node or hover over the node in question and the DesignScript prompt will appear.

    Our last triumvirate object is the Action.

    This is where we want to do something to a thing.

    As an example, we'll add a vector to our original point.

    To action something, you also need to use the dot nomenclature, but as with queries, you don't get a prompt sadly, and will also show up blue. It will, however, only show up blue when fully completed and written with the correct Title Casing.

    As noted previously in the creation section, we will need a method as we have to tell our action how to action. For this example we'll be using Point.Add as our Action Method.


    Our chosen method will require values for it to action. So, as with our creator method, we need to use brackets to define these inputs. We need a little background knowledge on how our action works however as it won't give us prompts (Unfortunately).

    In this case you'll need to know that the Point.Add command requires a vector. So we can either nest a creator within our action, or create a new line and define our vector with a name. Either will accomplish what we desire - which is moving our point up by 10 units.

    Action_Method_Value.JPGVector Point Add.JPG

    You can also nest a whole bunch of methods together - and there are a couple of examples below courtesy of the extremely helpful folk at the forums (Namely for the images below: Dimitar Venkov, Vikram Subbaiah and Eprocauno).

    Dimitar_Venkov_DesignScript_Diamond_Grid.png Dimitar_Venkov_DesignScript_FilterByBooleanMask.png Eprocauno_Stepped_List_Definition.jpg Vikram_Subbaiah_ColourisationByDistance.jpg Vikram_Subbaiah_DesignScript_If_Statement.jpg
    Last edited by amoursol; December 17, 2015, 01:51 PM. Reason: Edit: Clarity

    Sol Amour

    Architectural Explorer, Digital warrior, Affectual adventurer and Curious Human Being
    Portfolio Website @ Cargo Collective

    Thanks! Good to have a basic explanation of the syntax etc.
    "One must imagine Sisyphus happy." Albert Camus - "The innovator has for enemies all those who have done well under the old conditions, and lukewarm defenders in those who may ​do well under the new." Nicolo Machiavelli -"Things that are too complex are not useful, Things that are useful are simple." Mikhail Kalashnikov


      An Introduction to Replication Guides:

      Replication Guides have changed behavior. Please refer to the following thread, and specifically the reply by Zach Kron, until this Introduction is updated:

      Replication guides are how we control list operations in DesignScript. While nodes have lacing, DesignScript has Replication Guides. They can function in the same way, but Replication Guides offer a much greater degree of control over your data.

      Replication guides are described by the Dynamo Language Guide as follows:

      "While range expressions offer a convenient means of generating one dimensional collections of elements, replication guides offer a convenient means of generating two and three dimensional collections.

      Replication guides take two or three one-dimensional collections,and pair the elements together to generate one, two or three dimensional collection. Replication guides are indicated by placing the symbols <1>, <2>, or <3> after a two or three collections on a single line of code."

      Jostein Olsen also explains replication guides thoroughly on his blog post Replication Guides for Semi-Dummies by utilising points as a case study.

      2D Array Example:

      Using a simple test case of two equal length lists of data, we can explore how these work:

      List A = A number range from 1 to 10, stepping by 1.
      List B = An alphabetic range of 10 characters ('a' to 'j').

      Baseline Functionality:

      Base line functionality of nodes in Revit defaults to 'shortest lacing', and in Code Blocks (Or DesignScript) this is also the case. So if we want to add two lists together, without replication guides, we'll get the following output.


      Joining lists in the default manner will simply pair the first item of List A with the first item of List B and result in an output list of 10 items, concatenated from List A and List B.

      Single Replication Guide:

      Adding in a single replication guide, either after the input of List A or List B, will change how the data of one list interacts with the other.

      Whatever list input has the single <1> replication guide next to it, will become the driving or primary list.

      If List A is the driving list, this single replication guide will take every individual item from List A (Our numbers) and pair them with the items from List B (Our letters). This will result in individual sublists of 1a, 2a, 3a ... 4c, 5c, 6c ... 8g, 9g, 10g and so on. We will have every single combination of our primary list with that of our secondary list.


      If list B is our driving list, it will iterate through every option by having the List B items as driving the data. Notice that as our Code Block data is being added together by 'List A' + 'List B', this formatting persists after the addition of the replication guides. With List B being the driving list, the resultant individual sublist data will be of the format 1a, 1b, 1c ... 3d, 3e, 3f ... 10g, 10h, 10i and so on.


      Matching Replication Guides:

      In both of the replication guide examples showcased below, the data arranges itself as the Baseline Case. This is because we are telling each list that their primacy is equal.



      Double Replication Guides:

      Adding in a double set of replication guides, one after the input of List A and one after the input of List B, will again change how the data of one list interacts with the other.

      Whatever list input has the higher number replication guide next to it, will become the drivinglist and this will tier down in order. So a replication guide of <1> is subservient to a replication guide of <2>, and a replication guide of <2> is subservient to a replication guide of <3> and so on.

      In a double replication guide situation, having List A being the primary list results in the Numbers being dominant.


      If List B is the primary list, the results will have the Alphabetic characters as dominant, or driving.


      Longest Lacing:

      You'll notice so far that we haven't been able to replicate the longest lacing option we have available in node form.

      There is a special syntax for this in Replication Guides that uses the form of <1L>, where the capital 'L' (Lowercase will fail) demarcates longest lacing. Longest lacing replicates the final item of the shortest list across the additional items of the longest list.

      Image credited to Andreas Dieckmann

      3D Array Example:

      The data type within Replication Guides matters: Our 3D array example cannot use the above format as a series of a<1>+b<2>+c<3> will simply result in null values. The data is too simple. For a 3D array we need to use ranges.

      We'll use Points to demarcate how replication guides work in a 3D setting.

      No Replication Guides:

      The default functionality, without replication guides, will give us a points list that matches the first input for each of the X, Y and Z variables, and cycles through list the lists matching index to index.

      The result of this is a series of points that run from 0,0,0 to 1000,1000,1000 (x,y,z).


      Single Instance of <1>:

      If we put a replication guide after a single variable (Either X, Y or Z) we'll allow that input variable to be dominant and it will run through it's list of inputs as the driving list, creating every single combination of that list by matching the first item of the secondary and tertiary variables.


      Within the base nodes, to follow our example, you can use a Point.ByCoordinates node of which has three lacing options: Shortest, Longest and Cross-Product. Both shortest and longest lacing will match with the default DesignScript variant. As shown below, cross-product is the only lacing option that will allow you to switch up your data.

      RevitForum_ReplicationGuide_03.JPG RevitForum_ReplicationGuide_04.JPG

      Double Instance of <1>:

      The single instance of <1> has already given us 3x options of how our data is formatted. If we choose to put another replication guide of <1> after a second input variable, we force our data to push through both replication guided lists, while pairing them with the first item of the non-replication guide list.


      As previously, putting a replication guide of <1> after every input variable will result in formatting that is the same as no replication guides.


      Note: In all of the 3D array examples above, the number <1> can be substituted for <2> or <3> and so on - with the caveat that they are all the same number.

      And Then We Get Funky:

      The higher the number in each replication guide, the more dominant that replication guide is. So when we start adding in multiple replication guides, we start formatting our data in a tiered fashion.

      If we choose to put a <2> beside our Y input variable and a <1> next to our X input variable, we'll get a 2D array of points, in the Y axis as the dominant replication guide, replicating a 2d grid of points by using each of the X input variables numbers. The Z input variable remains at zero (first item in the list) as we haven't told this data to 'join the party'.


      If we choose to put the <2> replication guide by the X input variable and a <1> next to our Y input variable instead, ostensibly our 2D array doesn't change but the way the data is formatted does: the driving list is now the X variable list.


      If we choose to put a replication guide next to the Z input variable instead, the quote unquote "2D" array will become a pseudo "3D" planar array.

      As previously, if we choose our secondary tier to be the Y variable, we'll get our planar array in the YZ-axes or if we choose our secondary tier as the X variable, we'll get our planar array in the XZ-Axes.


      If we choose to bring all three input variables to the party, we start getting more variations on data formatting. Instead of a vertical planar array, we now have a truly 3D planar array with our chosen tiered structure demarcating the dominant and subversive nature of the data formatting.


      As previously using replication guides in the form A<1>,B<2>,C<1> is the same as A<2>,B<3>,C<2> as its the hierarchy of the replication guide numbers that matters.

      Plumbing the Depths:

      The final variant to explore is that of using three tiers of replication guide number hierarchy.

      Ostensibly, when using replication guides to create a cross-product result (Every single possible option), the graphics will look the same for our points example. The data, however, will be based off the dominance of the replication guides.


      The location of the Points don't change to the eye - but they way they are created does.
      Last edited by amoursol; March 15, 2016, 08:29 AM. Reason: Addition: Replication Guide behavior changed. Link added to Zach Kron's post on the subject.

      Sol Amour

      Architectural Explorer, Digital warrior, Affectual adventurer and Curious Human Being
      Portfolio Website @ Cargo Collective


      Related Topics


      • Replace values in list, by list
        Im trying to replace a sequence in my view names: 1, 2, 3, 4, 5, 6.
        By A, B, C, D, E, F, G.

        See attached picture.

        March 17, 2020, 10:03 AM
      • List Replace Items
        Hello all!

        I am trying to "combine" two lists into one cohesive list.

        In List 1, I have list items that are "empty"...
        November 30, 2015, 04:28 PM
      • Boolean OR for list
        Hello all,

        Logic / Action / or you can insert any number of booleans and it will pass true if any of them are true. Is there a way to do...
        September 14, 2017, 06:08 PM
      • Input as List
        I'm stuck - probably due to my naivete with Dynamo, but I can't figure out why in the graph below, the Viewport.SetBoxCenter node won't accept a list...
        February 18, 2016, 05:12 PM
      • Help: getting volumes from Revit to Excel
        Hi all,

        I'm Mike and I'm from the Netherlands and I work for a large Engineeringsfirm that wants to explore the possibilities of Dynamo....
        April 6, 2016, 12:57 PM