General Stuff
1. Comments
To add a comment to your file, simply put the #
symbol right before your comment. For example:
# This is a
comment
It's a good idea to use comment markers to add a
title header at the top of your building file. The Triton Center
file has this header:
#The Triton
Center
#Copyright (C)2002-2013 Ryan Thoryk
2. Variables
Variables are marked with percent signs (%), and
most system variables will be described later. Variables can be
set using the Set command:
Set myvariable = 100
and then can be used later:
Height = %myvariable%
3. IF/While statements
Basic IF and While statements can be made, with
the following syntax:
if[expression]
command
while[expression] command
Available signs are = (equals), > (greater than), < (less than), ! (is not), & (and) and | (or). Expressions can also be enclosed in parenthesis. Note that IF/While statements only work with the current line, and do not currently support multiple lines within an IF/While block, an "else" statement, or nesting. A While statement will loop the current line until the expression is false, so be careful with this because it can create an infinite loop if the expression is always true. See the Functions section below for an example of a While statement.
For example, to set the height to 9.5 if the floor
number is less than 82:
if[%floor% <
82] Height = 9.5
This example shows a complex expression:
if[%floor% <
82 & (%height% = 3 | %height% = 5)] Height = 9.5
In the above example, the statement will be true
if the floor value is less than 82 and if the height
value is either 3 or 5.
4. Inline calculations
Values can be calculated inline by using the
following math operators:
+ (plus), - (minus), / (divide), * (multiply), and ^ (power of)
They can be used anywhere in the data file. Here's
an example of one being used with the Set command:
Set 1 =
%floorheight% + 10
Parenthesis are also supported, for grouped
operations. Here's an example of a complex math expression:
Set 5 =
%height% + (%interfloorheight% * (4 / %altitude%))
5. Object parameters from outside floor sections
Information about a certain floor can be obtained elsewhere in the script, by referencing the floor in this manner:
Floor(number).parameter
Available parameters are Base, Altitude,
Height, FullHeight and InterfloorHeight.
Note that this function must only be called after the specified
floor has been created.
If the InterfloorOnTop parameter in the globals
section is set to 'false' (the default), then Base
(slab height) refers to the floor's altitude plus interfloor
height; otherwise it refers to the altitude.
Example:
Set 1 = Floor(5).Altitude
6. Includes
Other script files can be included (inserted) anywhere in the current script by using the <Include> command. Scripts can be included multiple times, and included scripts can include other scripts.
Syntax:
<Include filename>
To include a file called test.txt that's in the
data folder, you would enter:
<Include data/test.txt>
7. Functions
Functions can be created to share code between sections of scripts, and also between entire scripts when used in conjunction with includes. An unlimited number of parameters can be specified for each function. If a function is specified with the same name as a previously defined function, the function will be skipped and a warning will be printed. This can only be used outside of any section, such as <Floor>.
Syntax:
<Function name>
(code)
<EndFunction>
The above is a function definition, and must be used before the function call. Functions can be called from anywhere in the script, and can also call other functions, resulting in nested functions. To call the function later in your code, use the function name followed by a list of parameters contained within parenthesis, or just parenthesis if you're not passing any parameters:
Syntax:
name(parameter1, parameter2, ...)
or
name()
The parameters appear as variables inside the function in the
form of %param#%
- so the first parameter passed is %param1%, the second is %param2%,
etc. For an example, I'll create a function called Test with a
single SetAutoSize command within it, and call that function:
<Function
test>
SetAutoSize = %param1%, %param2%
<EndFunction>
test(false, false)
In the above example, the command that ends up being performed is "SetAutoSize = false, false". Here is an example of using a While statement to loop a function:
set a = 0
<Function testing>
set a = %a% + 1
print %a%
<EndFunction>
while [%a% < 5] testing()
print finished
The console output of that ends up being:
1
2
3
4
5
finished
8. Advanced Math Functions
Several built-in advanced math functions are provided, mostly for trigonometric calculations.
Syntax and descriptions:
cos(x) - calculate cosine, x is angle in radians
sine(x) - calculate sine, x is angle in radians
tan(x) - calculate tangent, x is angle in radians
acos(x) - calculate arc cosine, x is a value from -1 to
1
asin(x) - calculate arc sine, x is a value from -1 to 1
atan(x) - calculate arc tangent
atan2(y, x) - calculate arc tangent with two
values, one for the y-coordinate and one for the x
sqrt(x) - calculate square root
abs(x) - calculate absolute value
exp(x) - calculate exponential function
log(x) - calculate natural logarithm
log2(x) - calculate binary logarithm
log10(x) - calculate common logarithm
mod(number, denominator) - calculate modulo
(remainder) of a division
hypot(x, y) - calculate hypotenuse
ceil(number) - calculate ceiling (round up)
flr(number) - calculate floor (round down)
rnd(limit) - generate random number from 0 to limit
round(number, decimals) - round number to nearest
value; the decimals parameter is optional
9. For loops
For loops can be created by specifying an iterator
variable, and the range to use, with the following syntax:
<For iterator
start To end>
(code)
<EndFor>
The For loop will loop until it completes the
"end" value, and can iterate up or down. The value of the
iteration is stored in the iterator variable and the variable
name must be unique.
In the following example, the iterator variable will be printed
out on each iteration:
<For i 1
to 3>
Print %i%
<EndFor>
When the code is run, this is the result:
1
2
3
When the code is run, this is the result:
1 : 1
1 : 2
1 : 3
1 : 4
2 : 1
2 : 2
2 : 3
2 : 4
3 : 1
3 : 2
3 : 3
3
: 4