|
This will add the Key to the EGO character's inventory. If you look up
AddInventory in the manual, you'll find it takes two parameters,
an InventoryItem * and an optional int. The InventoryItem*
means that you need to supply the Script Name of the inventory item;
this is something you can set in the script editor. As well as all the individual character instances such as cEgo, there is a special instance called player. This always corresponds to the current player character, so if you just want to perform a command on the player character (especially useful in games where the player can control different characters) then you can use the player instance to do so.
|
Display(It's quite a large, ominous looking door."); cEgo.AddInventory(iPoster); |
Note that the script system is case sensitive, so writing for
example addinventory(iposter);
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 mean that the player gets the two messages in the order you specified.
So, did you remember these vital points:
The script is case sensitive.
Scripts in AGS can 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", "String" (note the capital S) or "float", and the name can be anything you like - it is what you will use to refer to it later. For example:
int myCounter; |
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 myCounter = 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 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 place the definition above the main function
body. So, it should look something like this:
// room script file int myCounter; (other event scripts) function hDoor_Look() { Display("It's quite a large, ominous looking door."); } (rest of file follows) |
No script commands can be used outside functions (or AGS wouldn't know when to run them!) - only 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:
myCounter = 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 myCounter, do the following:
myCounter += 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 (myCounter == 5) { myCounter = 0; } |
what this means is that if myCounter contains the value 5, then the script
inside the { } brackets will be run (which in this case changes the value
of myCounter to zero).
If myCounter does not equal 5, the script inside the brackets is
not run 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:
if (myCounter == 0) { Display("You see a bookshelf."); } if (myCounter == 1) { Display("Looking closer, you see a book called Hamlet."); } if (myCounter == 2) { Display("There is also a book called Harry Potter."); } if (myCounter == 3) { Display("There is nothing else of interest on the shelf."); } if (myCounter < 3) { myCounter += 1; } |
myCounter starts off set to 0, so the first time this script is
called it will run the first Display command, but not the others. Then,
since 0 is less than 3, it will increase myCounter by 1, and since 0+1 =
1 it now holds the value 1.
Once the player has seen all the messages (myCounter == 3), it no longer
increases the value so if they click again they will keep getting the
final message.
Global variables made easy
Sometimes, you may want to set a variable value that can be shared between a room script and your global script. There are two ways to do this -- you can export the variable from the global script and then import it in the script header, but that's a bit advanced for this tutorial. A simpler way is to use one of the 300 GlobalInts, which use the script functions SetGlobalInt and GetGlobalInt to access them. See their manual descriptions for more information.
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 myCounter = IsGamePaused(); (OR) // Test the return value directly if (IsGamePaused() == 0) { myCounter += 5; } |
Be sure to remember the parenthesis ().
The script system has a few nice shortcuts for common tasks which you will find yourself using regularly.
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 (myCounter < 3) { myCounter++; } |
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 (myCounter < 3) myCounter++; |
However, this can lead to mistakes in scripts that are hard to spot, so I would advise always using brackets just to be safe.
Finally, if you want to test whether a value is zero or not, you can just write it as follows:
if (myCounter) Display("counter is non-zero"); |
which is equivalent to:
if (myCounter != 0) Display("counter is non-zero"); |
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.
When you're ready, feel free to proceed to the Tutorial Chapter 2 - The Patronising Text Returns which covers more advanced topics.
Enjoy AGS!
Page created 6 June 2002; updated 19 August 2007. Copyright (c) 2002-2007 Chris Jones.