Scripting and Allegro

Abstract

This is a discussion of scripting, using C++ and Allegro. I am going to describe a basic game which I want to add scripting to, then describe two methods. First, a simple home-made script, and second, a general-purpose scripting language. Finally there will be a discussion of some issues, and how I would go about tackling them. You should understand enough C++ and Allegro to be able to follow the base game. I use some STL, so go to Pixelate and read the STL tutorials. For the final part, you need to download and install a working copy of the Lua language.
Thanks to various members of Allegro.cc for help on this; in particular, Chris Barry (23yrold3yrold).

"I do not accept responsibility for any effects, adverse or otherwise, that this code may have on you, your computer, your sanity, your dog, and anything else that you can think of. Use it at your own risk."

Contents

• Introduction
• The host program: step1.cc
• A simple script: step2.cc
• General scripting language: step3.cc
• More complex scripting: step4.cc
• Some more issues
• Other scripting languages
• Conclusion

Introduction

This article discusses some issues relating to scripting for Allegro games. Scripting is quite a complex topic, so I am assuming that you have a good grasp of Allegro and C++, and you are already able to write a game without scripting. It's impossible to give step-by-step instructions that will be exactly what you need in all cases, so I am just going to cover as many of the issues as I can.

You might want a scripting language because:

• You want the program to be extendable by someone who doesn't have the source code
• A language like C or C++ does not adequately represent the kind of things you want to do
• It's cool and everybody else has one

I will start with some background and terminology. These are the definitions I will use in this article. A scripting language is a specialised language which runs inside, and controls another program. This is the host program; it's your game, in this case. Now you have two programs, the host and the script, and they must communicate. When you write the host program, you will build in places where scripts are called. These are called hooks. For example, when the player approaches an NPC and presses the 'action' key, you could start a script which represents a conversation. When the script wants to do something, it calls back to the host. This is the host API. For example, the host could expose a function that draws a message box. This is summarised in the diagram below.

What is a programming language?

Comp.Sci students are, by now, jumping up and down. I don't care so much what the proper definition is. If you think of it as being something like C, then writing a scripting language seems scary. But here's what I say: If you imagine writing a program to display this page, it might look like

int main(void) {
 clear_page();
 begin_style(STYLE_H1);
 draw_text("Scripting and Allegro");
 end_style(STYLE_H1);
 new_line();
....

In summary, a scripting language is a specialised language for a particular task, and we need to write hooks and APIs so that control can pass from one to the other. Next, I will describe the host program that I'm going to add scripting to.

The host program: step1.cc

For the host program, I'm going to keep it simple, as shown in the diagram below. There's going to be a player (the ugly guy on the right), a Wizard and a clock (not shown). Play will take place in an office and there's a status area at the bottom for messages. The player can go left and right, and activate things by pressing the left control key. To finish, press ESC, and to take a snapshot of the screen, press f1. In later stages, you can open up a console by pressing TAB and enter script commands directly. Finish entering commands by pressing RETURN on a blank line.

I don't want to spend time going through the code at length, but basically the classes Player, Wizard and Clock derive from a common base GameObj. To handle input there's an Input class, which could be overridden for joystick and user-defined key input, and a Flipper class, which gives double buffering, and could be overridden to use page flipping. I don't do that here, so the code is slightly more complex than needs be. Finally, there's a class Texter which has a very basic stream interface (i.e. you can write txt<<"a string";), to display messages to the user. The code that doesn't change from example to example is in the file 'common.cc' with a header 'common.h'. All the parts of the game that are 'global' are in the class _state, which has one instance, Game.

struct _state {
  Texter* ptxt;
  Input* pinput;
  Flipper* pflipper;
  Map* pmap;
  map<string, GameObj*> objects;
  vector<GameObj*> active;
  bool sorted;
  void add(const char* name, GameObj* o) {
    active.push_back(o);
    objects[name]=o;
    sorted=false;
  }
  void update();
} Game;

All the redrawing and timing stuff is held in the function Game::update(). Therefore, the main loop just looks like:

  do {
    kbd.clear();
// update logic etc.
    Game.update();
// handle keyboard input
    if (kbd.left()) {
...
    }
// do activation bit
    if (kbd.fire()) {
...
    }
// run until ESC is pressed
  } while(!kbd.esc());

while(!script_finished()) {
 do_script_line();
 Game.update();
 script_next_line();
}

To make it absolutely clear, I have put all the API functions as functions of the Game object. This doesn't serve any real purpose in C++ terms, but it just makes it clear which functions I am exposing.

  // API functions
  void say(const char* msg); // display a message
  void move(int steps); // move the player
  void pause(int cycles); // wait a while
  // end of API functions

 bool didHit=false;
 for (vector<GameObj*>::iterator i=Game.active.begin(); 
      i<Game.active.end(); 
      ++i) {
   GameObj* o=(*i);
   if (o!=me && o->isNear(*me)) {
     didHit=true;
     o->doActivate();
   }
 }
 if (!didHit) {
   me->doActivate();
 }

Running the programs

You should have unpacked the archive and found a DAT-file, some .cc files and some .h files. The supplied makefile should autodetect MinGW, DJGPP and Linux. For MSVC people, you might need to study the makefile and build your own project. In step one, you need to compile and link step1.cc and common.cc. The target is step1.exe or step1 for Linux. Compile and run the program. What fun!

A simple script: step2.cc

So, an example script, and C++ equivalent might look like this. Admittedly, the C++ could be simplified by defining functions closer to the M and P script commands.

# Quest script 'Wizard:How can I help? 'Peter:What is my quest? 'Wizard:Go over there and come back M-50 P10 M+1 P10 M-1 'Peter:Well, that was easy M+50 'Peter: I did it!

void quest(void) { Texter& txt=GetText(); txt<<"Wizard:How can I help?"; txt.draw(); txt<<"Peter:What is my quest?"; txt.draw(); txt<<"Wizard:Go over there and come back"; txt.draw(); for (int i=0; i<50; ++i) { me.move(-1); update(); } for (int i=0; i<10; ++i) { update(); } me.move(1); update(); for (int i=0; i<10; ++i) { update(); } me.move(-1); update(); txt<<"Peter:Well, that was easy"; txt.draw(); for (int i=0; i<50; ++i) { me.move(1); update(); } txt<<"Peter: I did it!"; txt.update(); }

The code for this section is in step2.cc. Most of it is carried over from the previous step; the main changes were to insert a call to the scripts, and a little bit of support code to load a script from a file. For each script, there is a Script object. The definition of it looks like this

class Script {
public:
  Script();
  void load(char* filename);
  void run();
private:
  vector<string> lines;
};

void Script::run() {
  for (vector<string>::iterator i=lines.begin(); i!=lines.end(); ++i) {
    string& s=*i;
    switch(s[0]) {
      case 'P': 
 	int cycles=atoi(s.substr(1).c_str());
	while(cycles>0) {
	  Game.update();
	  --cycles;
        }
        break;
// and so on...
    }
  }
}

Now I need to load and trigger the scripts. There's one that runs right at the start, which goes like this

  Script startup;
  startup.load("start.sc");
  startup.run();

class Clock: public GameObj {
public:
  Clock(Map&m);
  void draw(BITMAP*);
  void doActivate(GameObj&);
private:
  Script tick;
  BITMAP* img;
};
...
Clock::Clock(Map& m) : GameObj(m) {
  img=(BITMAP*) dat[DAT_CLOCK_BMP].dat;
  x=128;
  tick.load("clock.sc");
}   

Because the loader uses the Allegro packfile functions, in a real game, you could put the scripts into a datafile (using individual compression) and load them using the "file.dat#name" syntax. This avoids having all your scripts lying around as plain text files.

Running the programs

In step two, MSVC users need to compile and link step2.cc and common.cc. The target is step2.exe. For Linux, just make step2. Compile and run the program. What fun!

Next steps

This scripting language is OK for the kind of cut-scene scripts that are triggered by an event, but it has severe limitations. You can only move the player, not the wizard, and the script always does exactly the same thing each time. To progress, you can add extra commands. I am not going to implement these, but I will suggest how to.

Command	Example	Description	How-to
A	Agandalf	Activate - select object for future M commands	Have a GameObj* current_obj; set it using Game.objects["obj-name"]

To introduce some variety, implement script variables, which are named %1, %2, .. %99. You also need a 'current value'.

Command	Example	Description	How-to
!	!%1	set variable to current value	Have a member Script::vars[100] to keep them in
@	@99	set current value to variable or number	If it starts '%' it's a variable, or a constant number otherwise
+	+1	add variable or number to current value.	Do the same for -, *, /
=	=0	set current value to 1 if current value equals value or variable, 0 otherwise	Do the same for < >
J	J-2	Jump forward or backward	Use the property of iterators, e.g. i+=param where i is a vector<string>::iterator
B	B10	Branch forward or backward only if current value is non-zero	As J command, but test current_value first

Once you've done all that you can write a script like

# is variable %7 equal to 1? jump if so
@%7
=1
B5
# otherwise, show message and set variable 7
'Voice: Cut the red wire...
@1
!%7
J1
'Voice: I've told you once!
#end of script.

void script() {
 static int v7=0;
 if (v7!=1) {
  puts("Voice: cut the red wire");
  v7=1;
 }
 else
  puts("I've told you once!");
}

General scripting language: step3.cc

For this section, I am not going to write my own language. I will use Lua instead. Lua is a language somewhat like C, BASIC or Pascal, but specialised for scripting host programs. It's mature and has been used in several games already (see the Lua web site, which is also a good source of docs and tutorials). It's not object oriented, but it can simulate objects. If you've used objects in Visual Basic, the idea is similar. Lua has tables which are a bit like the STL map<..,..> class, so you can write address["city"]="London" for example. A Lua value has a type, number, string, function or table, but a variable itself has no type, so you can write x="hello" followed by x=99 without problem. Lua variables can hold numbers, strings, references to tables, references to user data, and functions. User data will not be covered here; it just means a void* pointer that the host program knows about but Lua does not process in any way. Using functions and tables together, you can make Lua 'objects.' There is a clever bit of syntactic sugar which says

• obj.prop is equivalent to obj["prop"]
• obj.prop(...) is a function call (obj["prop"])(...)
• obj:prop(...) is a method call (obj["prop"])(obj, ...)

mypoint {x=0; y=0; 
   draw=function(pt, bm) 
    putpixel(bm, pt.x, pt.y, 255) 
   end 
}
...
mypoint:draw(screen)
mypoint.x=99;

class pointclass {
 public:
  pointclass() {
   x=0.0; y=0.0;
  }
  void draw(BITMAP* bm) {
   putpixel(bm, int(x), int(y), 255); 
  }
  double x, y;
} mypoint;
...
mypoint.draw(screen);
mypoint.x=99.0;

The code for this section is in step3.lua. The script loader code has changed a little bit, for Lua, but the main difference is the change to the API declarations. Where I had

  // API functions - these are the ones we want to make
  // available to the scripts
  void say(const char* msg);
  void move(int steps);
  void pause(int cycles);
  // end of API functions

  
// API functions
  static int say(lua_State*);
  static int pause(lua_State*);
  static int move(lua_State*);
// end of API functions

int _state::say(lua_State* L) {
  // print out all the arguments, separated by spaces
  // e.g. say("You got",17,"out of",20)
  // prints "You got 17 out of 20"
  int n = lua_gettop(L);  // number of arguments 
  int i;
  Texter& txt=*Game.ptxt;

  for (i=1; i<=n; i++) {
    // if not the first arg, print a space
    if (i>1) txt<<" ";
    // Get the arg in position i and 
    // try and convert to a string
    const char* s=lua_tostring(L, i);
    if (s)
      // valid conversion: print it
      txt<<s;
    else
      // invalid: show the type name in angle brackets
      txt<<"<"<<lua_typename(L, lua_type(L, i))<<">";
  }
  // finish off with a new line
  txt<<"\n";
  txt.draw();
  // return no values
  return 0;
}

void LuaScript::run() {
  // st holds the script text
  TRACE("Running '%s'\n", chunkname.c_str());
  // just call lua_dobuffer
  lua_dobuffer(Game.lua, script, length, chunkname.c_str());
}

More complex scripting: step4.cc

In step3, we were limited to moving the player only. Now we take a different, more object-based approach. The scripts player2.lua, gandalf2.lua, etc. are run when those objects are constructed, and they define the functions they need, put them in a table, and return that table to C++. They can also store 'private' variables in there. As an example, here is the code from clock2.lua

clock={
	name="Clock",
	say=say_method,
	move=move_method,
	x=get_x_obj,
	activate=function(me) me:say(asctime()) end
}
return clock

To do this, we need a way to jump from the Lua code to a C++ object. There are several ways to do this in Lua; I will present one. When the script returns the newly-created table (clock in the case above) , the C++ code adds another property to it, id. This is a string which identifies the object. Step by step:

1. [C++]create a new object of class Clock
2. [C++]register it in Game.objects with name 'clock'
3. [C++]run the script 'clock2.lua'
4. [Lua]create a table with all the methods and variables we need
5. [Lua]return it to C++
6. [C++]add another property 'id' with the same name we registered in step 2
7. [C++]bind the table to the C++ object

1. [Lua]call clock:say "xx"
2. [Lua]call say_method(clock, "xx"), a C++ function
3. [C++]get clock.id and store in obj_name
4. [C++]get Game.objects[obj_name] and store in obj
5. [C++]call obj.say("xx")

Another thing we're missing are map scripts or triggers. These scripts run when the player enters a particular area of the map. There are three ways they could execute.

• Once only
• All the time the player is in that area
• Once when the player enters the area, and again if he re-enters

Some more issues

From here on in, there aren't really any answers, just questions. These are some of the problems that I have run up against, and some thoughts I have had. Please let me know if you've found a really good solution.

Our program assumed only one script at a time would operate. If you want something to run in the background, there are a couple of approaches. As an example, we want a guard to wander endlessly round in a square. I'll write it in C++ so it looks familiar, but this would be a script, of course. We could put

while(true) {
 for (int i=0; <10; ++i)
  move_right();
 for (int i=0; i<10; ++i)
  move_down();
 for (int i=0; i<10; ++i)
  move_left();
 for (int i=0; i<10; ++i)
  move_up();
 } 

while(true) {
 for (int i=0; i<10; ++i) {
  move_right();
  yield();
  } 
 for (int i=0; i<10; ++i) {
  move_down();
  yield();
  } 
 for (int i=0; i<10; ++i) {
  move_left();
  yield();
  } 
 for (int i=0; i<10; ++i) {
  move_up();
  yield();
  } 
 } 

switch(direction) {
 case UP:
  if (steps==0) {
   steps=10;
   direction=RIGHT;
  } 
  else {
   move_up();
  }
  break;
 case LEFT:
  if (steps==0) {
   steps=10;
   direction=UP;
  } 
else {
move_left();
}
break;
 case RIGHT:
  if (steps==0) {
   steps=10;
   direction=DOWN;
  } 
else {
move_right();
}
break;
 case DOWN:
  if (steps==0) {
   steps=10;
   direction=LEFT;
  } 
else {
move_left();
}
break;
}
--steps;

When I specified the API for an object, I used virtual functions. They are fast and easy to use in C++. However, in this implementation, you need to derive every object from the same base class, which means that class must implement every single virtual function used by any of it's derived classes. This adds bulk and means you constantly have to modify the base. A solution is to use a multiplex function. These are used in Windows, and also turn up in the Allegro GUI code. Basically it's a general-purpose function like int GameObj::handler(int msg, void* param1, void* param2);. In the body of the code is a switch statement for all the cases you're interested in, such as

int Player::handler(int msg, void* param1, void* param2) {
 switch(msg) {
  case MSG_GET: { // just asked to pick up an object
   GameObj& o=*(GameObj*) param1;
   ....
   }
   return OK;
   ....
   default:
    return GameObj::handler(msg, param1, param2);
 }
}

class Message {
 public:
  Message(int m, void* p1, void* p2) : msg(m), param1(p1), param2(p2) {
  }
  int apply(GameObj& o) {
   return o.handler(msg, param1, param2);
  }
 private:
  int msg;
  void* param1, * param2;
};
queue<Message> message_queue;

Other scripting languages

int a=0;
int square(x) {
 return x*x;
  } 
a=square(6);
printf("%d", a);

a=0
function square(x) return x*x end
a=square(6)
print(a)

(define a 0)
(define (square x) (* x x))
(set! a (square 6))
(display a)

0 variable a
: square dup * ;
6 square a !
a @ .

If you want to make your own language, the conventional way is to use a lexical analyser and a parser. For example, the C program would be split up by the lexical analyser as "typename: int" "identifier: a" "=" "integer: 0" ";" and the parser has lists of rules like "a valid line is a type name followed by an identifier followed by an optional assignment followed by a semicolon" and "an assignment is an equals sign followed by an expression", etc. It's all very complicated. Tools that can help you are Flex, Bison or ANTLR. For more information, consult Thomas Harte's article in Pixelate #5.

Conclusion

Definition List

hooks

Places where the host program calls a script

host API

Functions in the host program that the script can call

host program

Main program, written in C or C++

lexical analyser

A program to split an input file into tokens

parser

A program to assemble tokens into a program structure

scripting language

A specialised language that controls the host program

syntactic sugar

A language construction which makes syntax more convenient

tables

A lua table can be indexed by number or name

triggers

A command that runs when the user enters an area of the map