Introducing Scripts in ECOTECT

Scripts have been available in ECOTECT from very early on in its development and are probably one of its most under-utilised features. Anyone can write and run a script in ECOTECT and they can be used to add new functionality, automate complex tasks, initialise or standardise a model to your firm's requirements, generate summary data, export to another application, etc. Pretty well anything you can imagine. This article is a brief description of what a script is and what it contains.

Natural Frequency

What is a Script?

A script is basically a series of coded instructions laid out in a human-readable text file, typically supplied by the end-user of an application and interpreted by that application line-by-line. The aim of a script is typically to automate a task or to combine the existing functions of an application with other logic or systems in order to extend or enhance its capabilities in ways the original programmers may not have envisaged.

These coded instructions in a script can contain:

  • Commands to be sent to the host application.
  • Numbers, Strings and _Variables for storing different types of data and information,
  • Expressions for manipulating and assigning numbers, strings and variables,
  • Flow control statements to determine the order in which everything occurs, and
  • Functions that group sub-sets of commands into re-usable blocks.

There are many different scripting languages available, but the above components are common to pretty well all of them. In ECOTECT, scripts are written in the LUA language and the examples that follow are all LUA.

Commands

Commands are built-in instructions that initiate actions within the script interpreter or the host application. The following code shows an example script with the commands highlighted in red.

function createFlatRectangle(left, right, width, height)
  o = add("object floor zone", true)
  if o > -1 then
    add("node", o, 0, left, right, 0.0)
    add("node", o, 1, left+width, right, 0.0)
    add("node", o, 2, left+width, right+height, 0.0)
    add("node", o, 3, left, right+height, 0.0)
    set("object.done")
  end
  return o
end

obj1 = createFlatRectangle(0, 0, 8000, 5000)
obj2 = createFlatRectangle(9000, 0, 8000, 5000)
cmd("view.redraw")

Commands are always immediately followed by round brackets that contain a comma-separated list of parameters that specify exactly how the command should work. Parameters can comprise any combination of numbers, strings and variables, or even be entirely empty.

Numbers

Numbers are simply fixed numerical values and can be given in any format. For example, all of the following are equal: 100, 100.0, 100.000, 1e2, 1.0e2, 1.000e2.

function createFlatRectangle(left, right, width, height)
  o = add("object floor zone", true)
  if o > -1 then
    add("node", o, 0, left, right, 0.0)
    add("node", o, 1, left+width, right, 0.0)
    add("node", o, 2, left+width, right+height, 0.0)
    add("node", o, 3, left, right+height, 0.0)
    set("object.done")
  end
  return o
end

obj1 = createFlatRectangle(0, 0, 8000, 5000)
obj2 = createFlatRectangle(9000, 0, 8000, 5000)
cmd("view.redraw")

Strings

Strings are sequences of characters and white-space that are enclosed within either single or double quotes. Whereas a number specifies a fixed value, a string specifies a fixed combination of characters that may represent something’s name or a message to display to the user. In the following code example, the strings represent ECOTECT function names.

function createFlatRectangle(left, right, width, height)
  o = add("object floor zone", true)
  if o > -1 then
    add("node", o, 0, left, right, 0.0)
    add("node", o, 1, left+width, right, 0.0)
    add("node", o, 2, left+width, right+height, 0.0)
    add("node", o, 3, left, right+height, 0.0)
    set("object.done")
  end
  return o
end

obj1 = createFlatRectangle(0, 0, 8000, 5000)
obj2 = createFlatRectangle(9000, 0, 8000, 5000)
cmd("view.redraw")

To include a quote within a string, you can use a backslash escape character just before it. For example, “To use a \” or \’ character in a string”.

Variables

Variables are words that you create from alpha-numeric characters and are used in the script to name and store specific bits of data. A variable name must start with a non-numeric character and cannot contain punctuation or spaces, but may include upper and/or lower case as well as the underscore (_) character.

function createFlatRectangle(left, right, width, height)
  o = add("object floor zone", true)
  if o > -1 then
    add("node", o, 0, left, right, 0.0)
    add("node", o, 1, left+width, right, 0.0)
    add("node", o, 2, left+width, right+height, 0.0)
    add("node", o, 3, left, right+height, 0.0)
    set("object.done")
  end
  return o
end

obj1 = createFlatRectangle(0, 0, 8000, 5000)
obj2 = createFlatRectangle(9000, 0, 8000, 5000)
cmd("view.redraw")

Expressions

Expressions assign values to variables or test a variable against another value. The LUA language is a bit unusual in that you can actually assign multiple variables within the one expression, such as x,y = 10,20.

function createFlatRectangle(left, right, width, height)
  o = add("object floor zone", true)
  if o >  -1 then
    add("node", o, 0, left, right, 0.0)
    add("node", o, 1, left+width, right, 0.0)
    add("node", o, 2, left+width, right+height, 0.0)
    add("node", o, 3, left, right+height, 0.0)
    set("object.done")
  end
  return o
end

obj1 = createFlatRectangle(0, 0, 8000, 5000)
obj2 = createFlatRectangle(9000, 0, 8000, 5000)
cmd("view.redraw")

Flow Controls

Flow controls define the logic that determines which bits of code are interpreted, in what order and how many times. Thus they include loops, returns, and condition tests to decide between different code blocks. All flow control statements use the “end” keyword to define where a code block finishes.

function createFlatRectangle(left, right, width, height)
  o = add("object floor zone", true)
  if o > -1 then
    add("node", o, 0, left, right, 0.0)
    add("node", o, 1, left+width, right, 0.0)
    add("node", o, 2, left+width, right+height, 0.0)
    add("node", o, 3, left, right+height, 0.0)
    set("object.done")
  end
  return o
end

obj1 = createFlatRectangle(0, 0, 8000, 5000)
obj2 = createFlatRectangle(9000, 0, 8000, 5000)
cmd("view.redraw")

Functions

Functions allow for the definition and naming of blocks of code that are likely to be repeated many times in different parts of a script. You can create your own functions in script and assign them a unique name. This name has the same limitations as a variable name.

function createFlatRectangle(left, right, width, height)
  o = add("object floor zone", true)
  if o > -1 then
    add("node", o, 0, left, right, 0.0)
    add("node", o, 1, left+width, right, 0.0)
    add("node", o, 2, left+width, right+height, 0.0)
    add("node", o, 3, left, right+height, 0.0)
    set("object.done")
  end
  return o
end

obj1 = createFlatRectangle(0, 0, 8000, 5000)
obj2 = createFlatRectangle(9000, 0, 8000, 5000)
cmd("view.redraw")

Function Parameters

Like a command, function names are always immediately followed by round brackets that contain a comma-separated list of parameters that specify exactly how the command should work. Parameters can comprise any combination of numbers, strings and variables, or even be entirely empty. When you create a function, the parameter names you include in this list will then be available within that function’s code block.

To call a function from anywhere in your script, simply enter the function name followed by the bracketed list of numbers, strings and/or variable to use as parameters. These values with then be automatically assigned to the variable names you used when you defined the function and acted upon by the function’s code block.

function createFlatRectangle(left, right, width, height)
  o = add("object floor zone", true)
  if o > -1 then
    add("node", o, 0, left, right, 0.0)
    add("node", o, 1, left+width, right, 0.0)
    add("node", o, 2, left+width, right+height, 0.0)
    add("node", o, 3, left, right+height, 0.0)
    set("object.done")
  end
  return o
end

obj1 = createFlatRectangle(0, 0, 8000, 5000)
obj2 = createFlatRectangle(9000, 0, 8000, 5000)
cmd("view.redraw")

Thus, when calling a function you must specify a number or variable for each of that function’s parameters, separated by commas.

Commands are Functions

As you may already have deduced, commands are simply predefined functions already set up by the host system or application. They both work in exactly the same way, it’s just that commands are already available and don’t need to be defined.

Thus command parameters are exactly the same as function parameters. You can use the Help panel in the Script Manager to find out how many and what type are required for each command.

function createFlatRectangle(left, right, width, height)
  o = add("object floor zone", true)
  if o > -1 then
    add("node", o, 0, left, right, 0.0)
    add("node", o, 1, left+width, right, 0.0)
    add("node", o, 2, left+width, right+height, 0.0)
    add("node", o, 3, left, right+height, 0.0)
    set("object.done")
  end
  return o
end

obj1 = createFlatRectangle(0, 0, 8000, 5000)
obj2 = createFlatRectangle(9000, 0, 8000, 5000)
cmd("view.redraw")

Writing a Script

You can write scripts in either the ScriptManager or any text editor such as Scite or Notepad++. You can start the ScriptManager from within ECOTECT using the Tools » ScriptManager… menu item. Then either start typing a new script or open and edit an existing one.

Using the ScriptManager is the best way to get started as it includes ECOTECT-specific syntax highlighting as well as command completion and embedded help on all commands and constructs.

Syntax highlighting uses different colours and styles to indicate the different script components as you type. This is useful visual feedback that allows you to check that everything looks right before you test or run each script. An example of a syntax highlighted script is as follows:

function createFlatRectangle(left, right, width, height)
  o = add("object floor zone", true)
  if o > -1 then
    add("node", o, 0, left, right, 0.0)
    add("node", o, 1, left+width, right, 0.0)
    add("node", o, 2, left+width, right+height, 0.0)
    add("node", o, 3, left, right+height, 0.0)
    set("object.done")
  end
  return o
end

obj1 = createFlatRectangle(0, 0, 8000, 5000)
obj2 = createFlatRectangle(9000, 0, 8000, 5000)
cmd("view.redraw")

Running a Script

You can run a script in ECOTECT four (4) ways:

  1. Running it from the ScriptManager:
    Either create or load your script and choose the Run icon.

  2. Drag & Drop from Windows Explorer:
    This requires that you have both Ecotect and Explorer open, and some part of the ECOTECT window visible on the screen in order to drag onto. If you are in the SUMMARY Page, do not drop it into the embedded browser but in a border area.

  3. Double-click it in the Scripts & Wizards Panel:
    This is located on the right-hand side of the main application window and lists scripts in the directories you choose.

  4. Using the File » Open menu item:
    When the File Open dialog box appears, select the “ECOTECT Script (*.SCR)” option as the file type and choose your file. The script will then run automatically.

Alternate Ways to Run Scripts

  • Sending commands from a Training Package file:
    Training packages are special ECOTECT HTML help files that can contain embedded scripts to interact with and highlight elements in the user interface. There are several examples available on the Autodesk Ecotect website.

  • Sending commands from an embedded HTML page:
    The REPORTS page in ECOTECT contains an embedded browser. You can load normal web pages in this browser and, if it contains specially formatted links, clicking on them can actually run script commands inside ECOTECT.

  • Embedding LUA script segments within a HTML report:
    HTML reports are specially formatted web pages that contain embedded scripts to extract data and images from the current ECOTECT model and insert it into the HTML to create sophisticated reports. These can contain control logic to loop through the model and generate dynamic tables in HTML and pretty well entirely control the content of the resulting HTML page.

  • Sending commands from a web browser (port 51520):
    If you enable WinSockets Communications in the ECOTECT User Preferences, you can use any web browser to send script commands to ECOTECT via port 51520.

  • Sending commands via DDE from another application:
    Using a compiler such as Visual Studio or the free Visual Studio Express it is possible to create your own application that can use DDE to communicate with a running copy of ECOTECT. This takes a bit of work, but quite a few firms are doing this.

See the Remotely Controlling ECOTECT article for the specific details on using these alternate methods.

Conclusion

Writing and using scripts in ECOTECT is often simpler and more straightforward than people think. They can certainly help make difficult tasks easier. There are many online resources available for learning the basics of LUA, links to several of which are included at the end of this article. However, the most useful resource you will likely find is the embedded help in the ScriptManager as well as its own help file. This includes reference information as well as many examples.

References

Click here to comment on this page.

< PREV ARTICLE: Behaviour of Light NEXT: ECOTECT and the Average Energy Year ARTICLE >
© Dr. Andrew J. Marsh, 2023 - Some rights reserved.