Extremely Simple Scripting Engine
by Cyberdrek


Introduction
Hi, I'm Cyberdrek from the boards. Some of you have seen me answer some posts in the forum. Ok, I have an attitude and I'm sometimes hard on people but I'm not all bad, the proof is this article that I'm giving the community about how I first wrote my scripting engine. Keep in mind that this engine was my first attempt at creating a scripting language and was actually pretty limited. At the time of writing, I'm still not sure if I'll give out any source code since the engine is proprietary code for HSSL (Headhunter Soft Scripting Language). Even though the new version of the engine has some major changes in it, most of the code still fits the bill. Enough for the intro, let's get to the planning.


Planning
I wanted to create a scripting engine that would allow me to manipulate certain aspect of my game that I was writing at the time so I started thinking about how I could implement it. At the time, I wanted to create an engine that would work like the one used by Sierra to create all their games. Having read a bit about compilers and how they work, I knew I needed to tokenize my input and that I'd need an interpreter (also known as a VM) to execute the code. I thought about it for a long time and decided to go with an OOP approach since it would help keep the code clean. NOTE: I used STL to create the engine so if you don't know much about it, grab a couple of STL tuts and go through them. You don't need to know much, just vectors and strings.


Language
Here's usually the fun part since everybody has his vision of how a scripting language should look. My vision was pretty simple. I wanted simple instructions (about 5 chars max) and I wanted syntax a bit like ASM. With that said, on a side note, I don't use any parsers to check the syntax in this version of the engine, even though the tokenizer is in a class called CParser.


Last Words Before We Start
Before we start, I have a couple of other things to clear up. At first, I had created the engine as standard header and source files. Once I had tested the engine and made sure it was working correctly, I moved on to putting it in a DLL file. What I'm trying to say is, don't be scared if you see __declspec(dllexport) before the definition of a function. Also, note that all header files are kept to a bare minimum; in other words, one class definition per header, and the same for source files. I've taken the liberty to encompass the engine in a namespace called HSScript. After trying both ways of using STL, I felt more comfortable without the command "using namespace std" so I don't use it and scope everything that's related to a certain namespace. It just makes it easier, IMHO, to follow the code.


Let's Begin
As I stated earlier, I started out by designing my HSSL class as follow.

Up to now, as you can see, it's just plain and simple definitions. Notice also that the handleTokens function is declared as private. And that I declare an instance of CParser into the declarations of the HSSL class. This is just an old habit. I know I could've done it differently but hey, every coder has his way of coding. I could have made, what I refer to as, a class function ( ie: A class that only defines the operator() but I wanted it to be simple to modify later on ).

With that header done, I knew I needed another one in order to put the CParser class and defined it like so:

Once more, nothing complicated here. An extremely simple class with only one function( in later versions, it holds a bit more stuff ). All that is left for use to do is simply write the code in source files. So here we go. The first file I created was the HSSL source file. Keep in mind that the engine was simple at that time. The handleTokens function is a bit long but that's been corrected and changed in the version we currently use.

Explanation: Hmm.. Looks complicated doesn't it. When I created the engine, I didn't want to go into any complicated stuff. So the handleTokens function basically run through a series of if statement to check the script function name and does whatever is appropriate. Now, here is a description of what is what in that code. Instruction[0] is the script function name; Instruction[1] is the first parameter before the ","; and Instruction[2] is the instruction after the comma until the end of the line. I've also had to be a bit creative about variables. You simply have 2 types. Either integers or floats and you only have 10 of each. The iPtr and fPtr variables store the location in the integer and float array, respectively, where you want to store the value. I've had to use the old atoi and atof functions as I didn't know how to convert from string to integer or float. As a matter of fact, I still don't know. Anyhow, I'll keep that for later. After the handleTokens function, I have my getters and setter for the variable arrays. Notice I also have a getCount and setCount function. These aren't used in this version of the engine but they are used in later versions. Before I forget, in this version, there are no loop functions at all. No while, no for, no do. The last function in the file and the one we are most interested in is execute. This function takes a filename as parameter. It then proceeds to open the file. From there, it reads a line, treats it using parser.tokenize and then takes the returned vector and passes it to handleTokens to execute the code. Note: notice that I have a global constant set for the return character definition. This is for the PRN function, if that character is met in the script file, it will add a "\n" to the cout statement if not, it won't change lines. You can also use the PRN BREAK statement which works fine also but it needs to be a separate PRN. Now with that said, we only have one last source to check out and that's the CParser code. Here it comes:

The way this works is simple. It takes the string that we've just read in, and checks for the first space. It then copies the part of the string before that space into a vector and moves on to search for the first comma, adding the part before the comma as another element in the vector. Finally, it takes the part after the comma and creates a last element in the vector. Finally, it returns that new vector.

Finally, I had to test the engine by creating a small program that would use the engine's DLL and lib to make sure it worked fine. Here's that file for you:

The program above does nothing more than create an instance of HSSL, execute a script file called test.hss. The test.hss file will be displayed in a couple of seconds. Notice the use of main and not winmain, there is a reason for that. The reason is that I simply wanted to test the file quickly without having to create a window, and create a function to ouput text, so a console app was the best choice. Let us now move on to the test.hss file.


End Notes & Conclusion
The script above simply prints a couple of things to the screen, stores values in the variable arrays and then does some math with those values. Here's a brief description of the commands:

prn = standard print
prni = prints the value located at x in the int array
prnf = prints the value located at x in the float array
prnbrk = breaks the text line( \n )

As for the rest of the functions, here's a brief descriptions of the last two characters in the name:
ii = first and second parameter are int
if = first param is int, second is float
fi = first param is float, second is int
ff = first and second param are float

The first three characters in the function names should tell you what they do. Now, I'm taking the liberty of adding the list of script functions available in this version of the scripting engine for you at the end.

In conclusion, this engine was version 1.00Beta( even though that's not the value that the version variable returns ). Now, for most of you, this engine will just be a piece of junk but to me, it was a first attempt at programming a script engine and I was also learning STL at the time so it was a first of firsts. And it has grown and gotten way better since then. It's now more of a Game Scripting Language rather than just a scripting language. None the less, I still like to mess around with that version once in a while. And it did teach me how to use some parts of STL. The latest version, HSGL 3.0 Beta, should be available for licensing sometime along the line of the beginning of 2003.


Commands For Script Language:
Comment Operator:

• %

Store values in variables:

• movi loc, val
• movf loc, val

Point for variable array to use with math functions:

• fptr loc
• iptr loc

Math functions :

• addii loc, loc
• addif loc, loc
• addfi loc, loc
• addff loc, loc
• subii loc, loc
• subif loc, loc
• subfi loc, loc
• subff loc, loc
• mulii loc, loc
• mulif loc, loc
• mulfi loc, loc
• mulff loc, loc

Print functions( do not put quote marks ) :

• prn val[,_]
• prni loc[,_]
• prnf loc[,_]
• prnbrk