The engine behind Larry Vales, King's Quest VGA and Pleurghburg

| About | Forum | Support | FAQ | Resources | Links |

Current Version: 2.22


Text Scripting Tutorial

Probably the most common situation faced by newbies is this:
You've played around with Roomedit, made a basic game and it all works fine. Now, you want to start using more advanced features by using scripting - but where to start? The manual does include a section on scripting but it doesn't cater for newbies very well. Hopefully this page will go some way towards redressing the balance.


The Basics

Right, we'll start off by doing something very simple - displaying a message to the player when they click the Look icon on a hotspot. (Of course, you don't actually need to use a script to do this, a simple Display Message would work just as well).

So, fire up RoomEdit and load in a room. If you don't have one, load a room from the demo game, it'll work just as well. Add a new hotspot, and click its Interactions button. Add the "Look at hotspot" event, in the same way as you would to add a normal Display Message command. Now, click the "(Do Nothing)" item in the top section that you just added, and change it to "Run Script".  Now, click the little grey "..." button on the right hand side:

The screen will switch mode, and you'll be confronted with the text editor containing something like this:

// script for hotspot1: LOOK AT HOTSPOT     

Lines beginning with // are comments - AGS will ignore them, they are just there to help you remember what your script is doing. You can add your own comments to your script by starting the line with the // symbol.


Functions Explained

Each different command you can use in the script is called a function. The name of all the available functions is listed in the text script reference part of the manual, which also tells you how to use them.

We want to display a message to the player, so we want the Display function. Looking this up in the manual gives us the definition:

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:

  • string name
    This parameter is a string, ie. a piece of text. This means that for this parameter you supply text, surrounded by double-quotes. For example,  "My text" .
    name is the name by which the parameter is referred to in the function description, it is not relevant for writing your script.
  • int name
    This parameter is an integer, ie. a numerical value. This means that for this parameter you supply a number, for example  65  .
  • CHARID
    This parameter is a character script name. You need to supply the script name of one of the game characters.
  • ...
    This parameter is optional, and can be of any type. You do not have to supply it at all, but if you do the function description will tell you what type of value to use.

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.


Command Sequences

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.


Recap

So, did you remember these vital points:

  • Strings are surrounded by double-quote marks.
  • Semicolon after the closing bracket on each line.
  • Function names are case sensitive.


Variables

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:

  • ==
    compares the two values, and proceeds if they are the same.
  • <
    compares the two values, and proceeds if the left hand value is less than the right hand value
  • >
    compares the two values, and proceeds if the left hand value is bigger than the right hand value.
  • <=
    proceeds if the left hand value is equal to or less than the right hand value
  • >=
    proceeds if the left hand value is equal to or bigger than the right hand value

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.


Functions that return a value

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 ().


Common Shortcuts

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.


Summary

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