Basic Scripting Concepts

In this section we will discuss some of the more basic techniques used for scripting in Design 3D.

Writing Scripts in Lua

If you’ve ever written scripts in other programs, such as Adobe Photoshop, then some of this information will not be new to you. However, computer programming languages and scripting languages differ just as human languages differ. In this section we’ll review how to “speak” basic Lua.

The Words

To be able to communicate in any language you have to know the basic "words". In Lua these words are:

and break do else elseif

end false for function if

in local nil not or

repeat return then true until while

These words are used to build Lua "sentences" or command lines. In addition to these words, mathematical operators are provided:

+ - * / ^ =

~= <= >= < > ==

( ) { } [ ]

; : , . .. ...

These words and operators represent just a small portion of the Lua language (see Chapter 5, Scripting Reference for a complete listing). Lua also allows you to create your own words for which you define the meaning in the course of your script. These special words created by you are called "variables".

Working With Variables

A variable is just a container to hold a value. Variables can be "declared" at the beginning of your script or in the course of the script as you use them. Variables can be "local" (just for use in the current script) or "global" (for use across scripts and anywhere within Strata Design 3D). To illustrate this concept, let's look at the Quick Start Heartbeat scale script and its use of variables to create the effect of a beating heart:

The following bits still need some work, or at least some reformatting.

Lua in Strata Design 3D CX

If you didn't save the previous version of your Quick Start tutorial script rebuild it now following the instructions.

With this more complicated script we'll use the Initialization section of the dialog to write some preparatory script elements.

Create the "beatPercentage" Variable

Click in the Initialization field and type:

local beatPercentage = 20

If you're already familiar with using variables in other scripting languages you'll recognize that what we've just done is "declared" a local variable and gave it an initial value (20). Putting this variable at the top of our script gives us an easy to edit value that isn't buried in the body of the script. Using this variable value we can later easily alter how much the "heart" contracts on each beat.

Note: If we had wanted the beatPercentage variable to be available throughout the program we would have written this line as: global beatPercentage = 20

Note: the first letter of the variable name is not capitalized. This is not a requirement, but it is good practice and a standard convention when coding in Lua. You'll also note that the variable name is all one word - no spaces. This is a requirement for any name in Lua - putting in a space would make it two words, not just one.

Create the "beatsPerSecond" Variable

Just below local beatPercentage = 20 type:

local beatsPerSecond = 3

Like beatPercentage above, this variable will make it easy to change the number of rate at which the object contracts per second.

Compute Values for Script

As part of our initialization for this script we'll create some additional variables that will compute "precached" values for use in the Script Source section.

Define "beatScale"

Type in the following:

local beatScale = beatPercentage / 100

In this script line we're declaring a new variable (beatScale) and calculating its value by using our previously defined variable of beatPercentage and dividing it (using the forward slash "/") by 100. This math operation converts our beatPercentage to an actual fractional number to represent a percentage value (in this case 20 ÷ 100 = .2 or 20%).

Define "beatBase"

Type in the following:

local beatBase = 1.0 - beatScale

In this script line we declare the beatBase variable and use it to hold the inverse of the beatScale percentage number (in this case 1 - .2 = .8 or 80%). We'll use this percentage number in Script Source as a place to maintain the base value of the scale while beatScale will be changing throughout the exectution of the script.

Define "scaledBPS"

Type in the following:

local scaledBPS = math.pi * beatsPerSecond

In this script line we declare the scaledBPS variable. This variable will contain the precomputed beats per-second scaled by pi for use with the cosine function later. Precomputing anything that doesn't change in the main script body can improve the speed of execution for the script.

Write the Script Source.

As with the Quick Start script, the Script Source section is where all the action takes place. In this step we'll have you type in the entire script and then we'll dissect it:

local beatScale = beatBase + beatScale * math.abs (math.cos (time * scaledBPS))

scale.x = scale.x * beatScale

scale.y = scale.y * beatScale

scale.z = scale.z * beatScale

return scale

Note: the asterix * character is used to indicate multiplication

The first line of this script source calculates a new value for beatScale. This is done by adding beatBase and beatScale and then multiplying the result times a third number generated by using math operators. Math operators are followed by the "argument" value, or values, contained in parenthesis.

As you saw in step 6.3.3 above, math operators are pre-packaged formulas that make it easy for you to calculate important values. We use "math.pi" to turn the beats-per-second value into an angle expressed in radians. We use the current time to scale that and pass it to the cosine trig function to generate a periodic wave that simulates the heart beat. The absolute value function call "math.abs" causes every cycle to remain positive.

These "nested" math operators are doing two things: the first calculation that happens is always the deepest one in the nesting - in this case it's the "(time * beatPSScale)"

Function Arguments

The arguments for these math operations are ways that data is passed to the function and then passed back to our script.

Line One of the Script Source

To refresh, the first line of our script source says:

local beatScale = beatBase + beatScale * math.abs( math.cos( time * scaledBPS ) )

Specifically, the basic argument is "time * scaledBPS". This argument to math.cos takes the current time in the model (current as of this execution of the script) and multiplies it times the current value for scaledBPS. For example if the current value for scaledBPS is [this needs to be finished]

Click the OK button. Next, click on the Play button in the Project Window. You’ll see that the object expands and contracts as time moves forward.