our script file:
I hope that you have read the previous workshop, the one about variables. I don't know about you, but I have learned quite a few things about those vars. This chapter will teach you many new and hopefully interesting things about functions.
What are these functions, anyway? Let's see a small example:
function add_numbers( )
{
a = 3;
b = 5;
c = a + b;
}
Do you see what I see? A function is nothing more than a collection of statements; it consists of several C-Script instructions that use vars and stuff like that. Let's see some properties for these functions:
1. A function is defined using the keyword function followed by the name of the function and a pair of parentheses ( ). The parentheses are used to pass additional parameters to the function; in our case we don't pass any parameters, so they are empty.
2. The body of the function (its content) must be written inside a pair of curly brackets { }.
3. The body of the function consists of one or more lines of C-Script code that end with a semicolon.
4. The names used for the functions aren’t that restrictive but you should stick with the naming convention used for the vars.
5. You shouldn't use the same name for a var and a function; this will lead to errors.
If you can read this tutorial I hope that you know your age, too. Not in years, but in days! What, you don't know it? You would like us to write a function that computes the number of days? Ok, so let's try to write a function that computes the number of days spent by me (or you) on Earth. It will use some vars, so we'd better define them first:
var my_age = 33; // your age (in
years) goes here
var days_a_year = 365;
var number_of_days;
Nothing new so far, right? We have defined three vars and two of them have received initial values, because I know my age in years and I also know that almost every year has 365 days. I'm I little nervous - will this function work?
I know how to start! I write the keyword function and then the name of the function; let's name it compute_days:
function compute_days()
{
I haven't forgotten the parenthesis after
the name of the function and I have added the first curly bracket!
Now comes the scary part: how will I be
able to tell the engine to compute the number of days? Wait... how would
I do it if I would use a pocket calculator? I would do something like this:
number_of_days = 33 x 365 // number_of_days is just a name for the result
Now let's take a look at our vars; if I replace 33 with my_age and 365 with days_a_year I will get something like this:
number_of_days = my_age x days_a_year
This line starts to look like C-Script
but we have to fix two minor bugs first:
- C-Script uses *
to multiply values, not x
- Every line of C-Script code must end
with a semicolon
Ok, so our function should look like this:
function compute_days()
{
number_of_days =
my_age *
days_a_year;
}
I have remembered to add the second curly bracket so now the body of the function is enclosed by the two required curly brackets. I am really curious to see if this function works ok, so I have prepared a small script file for our tests. Fire up SED, and open the script03 file located inside the folder named workshop03:
////////////////////////////////////////////////////////////////////
var video_mode = 7; // 800x600 pixels
var screen_color[3] = 150,0,0;
var my_age = 33;
var days_a_year = 365;
var number_of_days; // we need to calculate this value
////////////////////////////////////////////////////////////////////
panel display_pan
{
digits (10, 10, 5, _a4font, 1, number_of_days);
flags = VISIBLE;
}
/////////////////////////////////////////////////////////////////////
The code looks pretty simple, doesn't it? We already know how to work with those vars, we know how to add comments... Let's copy function compute_days from this document and paste it into the script: select the whole text of the function with your mouse, right click, choose Copy, switch to SED, right click the script at the end of the script and then choose Paste to paste the new function:
////////////////////////////////////////////////////////////////////
var video_mode = 7; // 800x600 pixels
var screen_color[3] = 150,0,0;
var my_age = 33;
var days_a_year = 365;
var number_of_days; // we need to calculate this value
////////////////////////////////////////////////////////////////////
panel display_pan
{
digits (10, 10, 5, _a4font, 1, number_of_days);
flags = VISIBLE;
}
/////////////////////////////////////////////////////////////////////
function compute_days()
{
number_of_days = my_age * days_a_year;
}
Let's Test Run
our script file:
It works... but nothing has happened! I can see the blue screen and a zero... I am zero days old? I thought that I am much older!
There must be something wrong with this code... I know that I have copied the function correctly! What should I do?
Well, we wrote a function that is supposed to run ok, but we haven't "called" it, we didn't make it run. Let's imagine that you want to celebrate your birthday and you hire a band. They arrive at your house and they sit in a corner without doing anything, waiting for your command. And you stand there, you don't tell them to start playing and you are wondering why you can't hear their music... The same thing happens with our function: we write it, but then we must tell it to run.
Ok, so now we're getting somewhere: how do I run my new function? Let's not forget about our trusty friend - the console. Press the Test run button to run the level again, press Tab to show the console and then type the following text:
compute_days( );
It's a miracle! It works! I am 12045 days old! You should see a different value here if you have replaced 33 with your age.
Ok, now that the enthusiasm has diminished, I start to feel a little uncomfortable: do I have to type the name of the function at the console every time I run a script? The answer is no; we can call any function from within our script. Let's type a line that calls the function inside a new function main, like in the picture below:
////////////////////////////////////////////////////////////////////
var video_mode = 7; // 800x600 pixels
var screen_color[3] = 150,0,0;
var my_age = 33;
var days_a_year = 365;
var number_of_days; // we need to calculate this value
////////////////////////////////////////////////////////////////////
panel display_pan
{
digits (10, 10, 5, _a4font, 1, number_of_days);
flags = VISIBLE;
}
/////////////////////////////////////////////////////////////////////
function compute_days()
{
number_of_days = my_age * days_a_year;
}
function main()
{
compute_days();
}
Time to Test run our level again...
Ok, this time it worked, but I'm not sure what happened; is function main() special or what? Yes, main is a predefined function name, so don't try to create another function and name it main. This special function will run by itself every time we start our script. Let's take a look at the code inside main:
function main()
{
compute_days();
}
The way I see it, the code calls (it runs) our function. Ok, now that we are here let's see how we call a function: we write its name followed by a pair of parenthesis and then we end the C-Script line of code with a semicolon. Sounds logical, doesn't it?
Important tip: write the lines of code for your functions first and call them later. The engine reads the code the same way you read a book: it starts with the top of the script page and goes down to the bottom, reading the code line by line. If I would write my script this way
function main()
{
compute_days();
}
function compute_days()
{
number_of_days =
my_age * days_a_year;
}
the engine will say: oh, that's function main. I know function main; I need to run it every time. What does it say now? compute_days(). What's with this function? I don't know it! I don't know what it wants from me. I'm going to display an error message and I will take the rest of the day off:
Don't forget to define your function first, otherwise the engine will complain when you try to use it. On a side note, you can see why no sane person will want to share his / her 3DGS copy with other "friends" or co-workers: every engine has a particular registration name and internal number, so if I would want to share my engine with somebody, Conitec's head hunters would hunt me down and punish me... and trust me, they're good at it!
Aren't you anxious to learn more? Our journey through the wonderful world of C-Script proves to be pretty easy, doesn't it? The next workshop will teach us how to create panels: elements that can display all kinds of figures, bars, etc. Whenever you see a picture or a figure on the screen, there's a panel definition behind it.