Supertux2 Level Editor - Squirrel Functions

The Squirrel language has a data type called a Function. The Function is similar to the function used in Algebra.

A value can be passed to the Function and another value returned. Such as a Function to use a Celsius value and return the Fahrenheit value, or vice versa. Values do not have to be sent to or from the Function. Functions can also allow for blocks of statements to be executed from a single command. By allowing a single block of code to exist once instead of several times, the script will take up less space and memory. An example will follow in a bit.

First, let's look at the structure of a Squirrel Function. The basic layout is:

function name (value1, value2, …){
    statement1;
    statement2;
     ….;
}

The number of statements in the block can be as many or few as needed. The name of the Function is how it is called to be executed.

For example, to convert Celsius to Fahrenheit, the Function could be:

function CtoF(celsius){
    local fahrenheit=0;
    fahrenheit=celsius*(9/5)+32;
    return fahrenheit;
}

The first line declares the function name (CtoF) as well as the arguments or values being accepted when the Function is called. The value accepted is in a variable called "celsius".

The second line is used to create the local variable called "Fahrenheit" and assign it an initial value of zero (0).

The third line is where the arithmetic occurs to determine the Fahrenheit Temperature form the Celsius Temperature.

The last line returns the value of Fahrenheit back to the calling statement.
Now, let's look at a calling statement for the Function:

local F=CtoF(40);

The calling statement sends the value 40 to the function. The result (104) returned from the function goes into the variable "F".

Now, let's look at a Function that doesn't return variables. We can use an example from SuperTux such as turning on/off Candles. A ScriptTrigger can be used to call the Function and pass a value to determine which set of Candles to manipulate. The example will be included in the file "Haunted Castle 2.stl". The file is an improvement on "Haunted Castle.stl". Instead of a long script for each set of Candles, there is one long script.

NOTE: To make the level work, you need to create a directory called "haunted" and place the STL file in it along with another called "default.nut". The function is stored in the "default.nut" file. The "haunted" folder should be in "/usr/share/games/supertux2/levels/". Be sure to also get the two sound files from the Article "SuperTux 2 Level Editor - Candle Object" and place them where they need to be so the music can be played.

Each Script Trigger calls the function by first importing the "default.nut" file. Once imported, the function is called by the line:

lighting(1);

NOTE: The file can be named whatever you wish and the statement should be "import default.nut". Change the name as you need to match the file being imported.
A portion of the function follows:

function lighting(x){
    candle1a.set_burning(false);
    candle1b.set_burning(false);
    candle1c.set_burning(false);
    candle2a.set_burning(false);
    candle2b.set_burning(false);
    candle2c.set_burning(false);
    switch(x){
        case 1:
            if(candle1a.get_burning()==true) {
                candle2a.set_burning(true);
                candle2b.set_burning(true);
                candle2c.set_burning(true);
            }else{
                caSuperTux 2 Level Editor Part 15 - Candle Objectndle1a.set_burning(true);
                candle1b.set_burning(true);
                candle1c.set_burning(true);
            }
            break;

    }
}

The first line sets the Function called "lighting" and accepts a value for "x".

The next six lines turn off the first two columns of Candles. The full script turns off all the Candles which have names.

The next line is the start of a Switch statement which will be covered in the next article.

Looking down the script you can see that there are not "return" statements. No "return" statement means that no value is sent back to the calling statement. This allows multiple lines of code to be placed into one place and help reduce the script size. It also means that the file can be imported into any level. It is easy then to place all functions for a whole world into one file and import it when needed in a level.

Take a look at the "default.nut" file and over the ScriptTriggers in the level file and see how they work. Also, look over the next article about the "switch" operator.

Further Reading

• Supertux Level Editor Articles (List) - https://dcjtech.info/topic/gaming/#supertux