Advanced Parameter Linking

Advanced parameter linking allows the user to define mathematical relationships between arbitrary parameters.

To create an advanced link, the user first add's a link and changes the name to something appropriate. Next, the user identifies one or more input parameters and defines a variable name to be used as an alias for each. The user then identifies one or more output parameters and defines their aliases. Finally, the user writes code to define how the output parameters depend on the inputs.

Advanced linking code is written in AngelScript. AngelScript is the scripting language embedded into OpenVSP. AngelScript is also used for general scripting and Custom Components - consequently, the entire OpenVSP API is available to advanced links through AngelScript.

A typical advanced link might look something like this:

This link determines the disk diameter for a vehicle given disk loading and gross weight. OpenVSP automatically defines the input (GrossWeight, DiskLoading) and output (Diameter) variables as double precision floating point numbers.

Most advanced links consist of a few lines of code that use standard mathematical notation with a semicolon at the end of each line. This can be thought of as a subset of the AngelScript language called 'Math with Semicolons'. The code for the example link is repeated below.

double Sdisk = GrossWeight / DiskLoading;
Diameter = 2.0 * sqrt( Sdisk / 3.1415926 );

Math with Semicolons

OpenVSP automatically defines input and output variables as double. These variables can be used to construct arithmetic expressions using common mathematical notation.

A standard suite of mathematical functions are also available.

Both C++ style // line comments and C style /* */ block comments are supported.

Troubleshooting

Output to the console can be easily achieved with the Print() function (note the capital P). The Print() functions are provided by the OpenVSP API. They can work with various data types directly. The lower case print() function is native to AngelScript and requires additional work to format numeric variables. For example, when debugging the example script, one might add print statements to display the intermediate values at each step.

double Sdisk = GrossWeight / DiskLoading;
Print( "Disk area: ", false );
Print( Sdisk );
Diameter = 2.0 * sqrt( Sdisk / 3.1415926 );
Print( "Disk diameter: ", false );
Print( Diameter );

The optional second parameter to Print() controls whether a line is terminated and a new line is started. Passing false allows multiple Print() commands to continue printing on the same line.

The output from the print statements goes to the console displayed behind the main OpenVSP window, or to the console used to launch the OpenVSP executable.

General AngelScript Programming

If using Math with Semicolons is insufficient for your advanced linking needs, you can also use any of the features from AngelScript. AngelScript is a scripting language similar to C++; it was designed to be embedded into other C++ programs. General documentation about the AngelScript language is available online.

Data Types

Since OpenVSP automatically defines input and output variables as double, most simple scripts will not need to define any variables at all. If you do need to use intermediate variables, all the common data types are available. In addition, AngelScript's string and array types are included and OpenVSP API provides vec3d and matrix4d types.

Operators and Order of Operations

AngelScript has a comprehensive set of operators expanded from those available in C++. In expressions, the operator with the highest precedence is always computed first. Parenthesis can be used to group expressions and to override the default precedence.

Unary operators

Unary operators have the higher precedence than other operators, and between unary operators the operator closest to the actual value has the highest precedence. Post-operators have higher precedence than pre-operators.

Binary and ternary operators

This list shows the dual and ternary operator precedence in decreasing order.

Control Flow

All of the looping and branching constructs from C++ are available in AngelScript. Users should be careful when using these constructs as it is possible to make computationally expensive (slow) advanced links, including advance links that enter into infinite loops.

Examples of the most common control flow constructs are given below.

if ( condition1 )
{
    // Do something if condition1 is true.
}

if ( condition2 )
{
    // Do something if condition2 is true.
}
else if ( condition 3 )
{
    // Do something if condition2 is false, but condition 3 is true.
}
else
{
    // Do something if both condition2 and condition3 are false.
}

int n = 5;
for ( int i = 0; i < n; i++ )
{
    // Do something five times.
}

Arrays

AngelScript's array are very similar to C++ STL's vector; they provide a dynamic container with random access. A summary of the methods available to work with array is given below.

OpenVSP Types

The vec3d and matrix4d types provided by the OpenVSP API are helpful for working with 3D position and direction vectors and also transformation matrices. The vec3d class performs vector math of various kinds including addition, scalar multiplication, dot and cross products, point projection, etc. The complete vec3d documentation is available online.

The matrix4d class provides an augmented transformation matrix used to perform rotations, translations, scaling, projections, and other transformations in 3D space. The complete matrix4d documentation is available online.

OpenVSP API

The entire OpenVSP API is available for use from advanced links. The complete OpenVSP API documentation is available online.

AngelScript API

The official AngelScript language documentation is available online. Angelscript comes with several optional packages that can be installed. Below is a table of the optional components installed in OpenVSP and a link to the documentation of each one.

Note: OpenVSP compiles AngelScript with the #define AS_USE_STLNAMES=1 option enabled. This causes the stdstring and array modules to behave more like their C++ STL equivalents.

Note: OpenVSP registers the array package with the defaultArray=true option enabled. This causes array to accept declarations in the form T[] arr;.