|
Lines beginning with
|
Display (string message, ...) Displays a message to the screen. It will be displayed in the standard message box, and centred in the middle of the screen. (description continues...) |
The key point here is the part of the first line inside the brackets.
This is called the parameter list and defines what parameters you
give to the function. A parameter is a number or some text that the
function uses to decide what to do.
Each parameter is listed, seperated by commas. They can be one of the
following:
"My text"
.65
.So, we know that our Display function needs a string and an optional parameter. The function description goes on to explain that the optional parameter is used for advanced things like displaying variable values, so we can ignore it for now.
To make our script call the function we write its name, then the parameters inside brackets, and finally a semicolon. This is very important, as without the semicolon the script won't compile. Also, note that we DO NOT write the parameter type (eg. "string" or "int"). So, we can add this line to our script:
Display("Hello from the script."); |
So, the script in the editor will look like this:
// script for hotspot1: LOOK AT HOTSPOT Display("Hello from the script."); |
Now, press Alt-F, X to exit the editor, and press Yes when it asks to save changes. Click the Setup Screen, Save Room button in roomedit to compile the script. If all is well the room will save, otherwise you will get an error message.
Load up the game, look at the hotspot and see it display your message.
What we've done so far has been fairly pointless, since it could have been done with a Display Message command rather than a Run Script. The main power of the script lies in its ability to process a sequence of function calls.
For example, suppose we want the player to be given a pink poster when
they look at the hotspot, as well as displaying the message. Assuming we
have inventory item 2 set up to be the poster (see the manual for how to
do this), the script enables us to easily do both.
For this job we want AddInventory. Its description in the manual says it
just takes one parameter, an int, which is the inventory item number to
add. So:
AddInventory(2); |
should do the job here. Our final script will look like this:
// script for hotspot1: LOOK AT HOTSPOT Display("Hello from the script."); AddInventory(2); |
Note that the script system is case sensitive, so writing addinventory(2);
will not work.
The script commands are processed from top to bottom in the order that you write them, so writing something like:
Display("Why did the chicken cross the road?"); Display("Because he was bored."); |
will make sure that the player gets the two messages in the correct order.
So, did you remember these vital points:
One of the script's main advantages is its ability to use variables. A variable is an area of memory storage that contains a value, which you can check and change with your script.
To declare a variable, you write the variable type, followed by the variable name, then a semicolon. The type is either "int" or "string", and the name can be anything you like - it is what you will use to refer to it later. For example,
int my_counter; |
The variable name can only contain letters A-Z, a-z and the underscore _ character.
You need to declare a variable before you can use it, so that the compiler can spot any mistakes and knows what type of things you can store in it.
Initially, your variable will have the value 0. Optionally, you can set the starting value within the declaration, like this:
int my_counter = 5; |
which would set it to contain the value 5 initially instead.
Variable Scope
An unfortunate side effect of the script's attempt to emulate the 'C' language is variable scope. In short, this means that you need to place your variable definitions OUTSIDE all the interaction event handlers, otherwise their values will keep getting reset.
So, to declare a variable for use by one of the room interaction scripts, you need to go here:
(ie. click the Edit Scripts button on the Room, Setup Screen tab).
When you click that button, you will see the the text editor containing all the scripts you have written for the room so far. You need to add your variable declaration to the top of the file, before any of the "function" lines. So, it should look something like:
// room text script file int my_counter; function hotspot1_a() { // script for hotspot1: LOOK AT HOTSPOT Display("Hello from the script"); } (rest of file follows) |
No script commands can be placed before the first function line - just variable declarations are allowed there.
Changing variables
You can change the value of a variable very easily in the script - simply write the variable name, the equals sign, then the new value, followed by the semicolon. So:
my_counter = 10; |
will change the value of our variable to be 10.
You can add to and subtract from a variable using the += and -= operators. So, to add 3 to the current value of my_counter, do the following:
my_counter += 3; |
Checking variables
Obviously we need a way to find out what value our variable contains, otherwise it's useless. We do this using conditional statements, called if statements. An if statement looks like this:
if (my_counter == 5) { my_counter = 0; } |
what this means is, if my_counter contains the value 5, then the script
inside the { } brackets will be run (which in this case changes the value
of my_counter to zero).
If my_counter does not equal 5, the script inside the brackets is skipped
and execution carries on from after the } .
Note the double-equals in the if statement. In an "if" statement, you ALWAYS use the double-equals operator, which compares the two values. If you used a single equals it would set the value instead, which will yield some strange results.
The ==
is called an operator, because it performs an
operation on the two values. The following basic operators are available:
Putting it into practice
Now let's do something useful with our variable. Suppose that we want to have different messages every time the player looks at the hotspot. So, the first time they look it will describe it, then if they look again they get a different message describing something in more detail. Our code will want to look something like this:
// script for hotspot1: LOOK AT HOTSPOT if (my_counter == 0) { Display("You see a bookshelf."); } if (my_counter == 1) { Display("Looking closer, you see a book called Hamlet."); } if (my_counter == 2) { Display("There is also a book called Harry Potter."); } if (my_counter == 3) { Display("There is nothing else of interest on the shelf."); } if (my_counter < 3) { my_counter += 1; } |
my_counter starts off set to 0, so the first time this Look script is
called, it will run the first Display command, but not the others. Then,
since 0 is less than 3, it will increase my_counter by 1, and since 0+1 =
1 it now holds the value 1.
Once the player has seen all the messages (my_counter == 3), it no longer
increases the value so if they click again they will keep getting the
final message.
When reading function descriptions in the manual, you will notice that some of them say they return a value. For example,
IsGamePaused () Returns 1 if the game is currently paused, or 0 otherwise. |
You use these much as you would use a literal value such as "9". For example, you can do:
// Put the return value into our variable my_counter = IsGamePaused(); // Test the return value directly if (IsGamePaused() == 0) { my_counter += 5; } |
Be sure to remember the parenthesis ().
The script system has a few nice shortcuts for common tasks which you will find yourself using but I haven't used so far so as not to confuse matters.
Firstly, the ++ and -- operators increase and decrease the variable by 1, respectively. So, the last part of our previous script could have been written:
if (my_counter < 3) { my_counter ++; } |
Also, the { } brackets are only needed if you are using more than one command inside them. Since we have only one command, the "my_counter++;" line, we can remove the { } completely and just be left with:
if (my_counter < 3) my_counter ++; |
However, this can lead to mistakes in scripts so I would advise always using the brackets anyway until you are very comfortable with the system.
We've covered the basics, so that hopefully you can now write a script of your own. There are many more advanced features that the system can do, but this should be enough to get you started. Hopefully I'll write an Advanced tutorial some day.
Enjoy AGS!
Tutorial last updated 26 Dec 2001. Copyright (c) 2001 Chris Jones.
Tutorial level:
Beginner
Assumed Knowledge:
Good working knowledge of roomedit