Mission Scripting (Overview)

Introduction

The original Mission Script looked something like this (taken from vice city debug.sc file):

IF IS_BUTTON_PRESSED PAD2 RIGHTSHOULDER1
AND flag_create_car = 1
AND button_press_flag = 0
	IF IS_CAR_DEAD magic_car
		DELETE_CAR magic_car
	ELSE
		IF NOT IS_PLAYER_IN_CAR player magic_car
			DELETE_CAR magic_car
		ELSE
			MARK_CAR_AS_NO_LONGER_NEEDED magic_car
		ENDIF
	ENDIF 
	flag_create_car = 0
	initial_car_selected = 0
	button_press_flag = 1
ENDIF

Easy to read and understand, and fairly basic, so anyone with an idea of basic coding (or even english) can understand it. However, very little code came with the game like that, the majority of the mission script comes in a file called main.scm (although in San Andreas there ar alternate mains and external scripts, but they all follow the same basic format - hex codes). Example, for the code:

IF IS_CAR_DEAD magic_car
	DELETE_CAR magic_car

The equivalent in the main.scm would look something like this:

D6 00 04 00 19 01 02 45 0E 4D 00 01 FE 3D 87 02 A6 00 02 45 0E

As you can see, this is nowhere near as easy to understand (infact, its pretty hard to understand, even for someone who knows the SCM format), the original code (which is easy for us to understand) is compiled into this format which is easy for the game to understand. Mission script, when compiled, is an opcode based language, this basically means all the commands are represented by (hex (base 16)) numbers, e.g. the command to tell the engine to wait is command 0001. In the original script, all you would need to do to make the game wait is type wait, and the length (in millseconds) you want the game to wait for, just with a simple 'WAIT 0' command. This is then compiled into commands the game can understand:

01 00 04 00

The first number is the SECOND HALF of the opcode, the second is the FIRST HALF of the opcode, the third is the data type (more on these later) and the fourth is the ammount of time (in milliseconds in hex - this is a parameter, any additional data to define the usage of an OpCode is a parameter) for the game to wait, but for anything but the most advanced editing (very few people can directly edit the SCM in its raw form), no knowledge of the compiled version is required.

Cracking the SCM

As has been said, very little of the code was supplied with the game in an uncompiled state (only two small files, both test scripts), so how, as asked, do we create our own scripts based on the original? With a decompiler - but how do these work (no deompilers have been provided by rockstar).

The original SCM format was cracked shortly after the release of GTA 3 (the first game to use this mission coding method), with people having to first figure out what all the sections did (there are 5 segments is an SCM - memory, objects, mission defines, MAIN and missions (SA has more, but only one of these (global variables) has had its use determined), where they started/ended etc, figuring out how many parameters each OpCode had and alot more. Once this was done, they knew where each OpCode began and ended, so they could split them up to make it more readable, but the data on what each one does was lost in the compiling, so they still only had something that looked like this:

:label035F78
0001: 0?
00D6: 0?
0256: 4??
004D: ££label67B3A7

That doesn't still doesn't mean alot though, so people had to try figure out what the different OpCodes meant.

(Note: this code is in early mission builder format:

:labelxxxxxx means this code was originally at this offset in the mission script (the 'label' is added in by the decompiler)
x? means a one byte number
x?? means a variable stored at this offset from the start
££labelxxxxxx is a reference to a label (i.e. for if we wanted to 'jump' to a label))

Some were easy, the very first line of a decompiled script (besides decompiler headers) looks something like:

0002: ££label0034B2

The only parameter this command has is a reference to a label, so this is most likely (and infact is) a jump statement, so we know all 0002's are jumps. Of course, finding what OpCodes do (and infact finding the original number of parameters took a while to confirm) takes time, you have to have an idea first and then have to test your theory - over half the OpCodes ave still not been named, so we still dont know exactly what a huge part of the mission script does.

Once the mission script had been cracked, people could write programs to read through it and output it in a form we could understand (based on a format of opcodes, text to say what they do and a list of parameter values - nothing like the original - the opcodes are needed to determine which opcode it is, the describing text is completely ignored). Originally there were two main decompilers, BWME (Barton Waterducks Mission Editor) and CyQ's disassembler, each with their own compilers (to compile the decompiled code back into an SCM file). BWME quickly became the most commonly used, especially among newer coders, probably due to the fact that the parameters were inter-mixed with the code, so you had something like:

00B1: is_car $car in_cube $lowerx $lowery $lowerz $upperx $uppery $upperz 0

As opposed to the disasm format:

is_car_in_cube $car, $lowerx, $lowery, $lowerz, $upperx, $uppery, $upperz, 0

(also note the lack of OpCode in the second example, this builder uses a lookup to find the opcode (if the function is known) instead of just quoting it)

Although you can't see much difference with that example, it can make a lot of difference.

The Builders

As previoulsy stated, there are two main builders for GTA 3 and VC, and a few under development for SA.

Mission Builder (BWME - note: although BWME was a slightly different tool, I shall be referring to this at that):

This tool uses only OpCodes to compile the code, all the text on the line is ignored. Traditionally, it decompiles to a file called main.scm.txt, which is just a big text file with all the code in it, expanded to be readable. This tool is used by the vast majority of mission coders as it is the most abundant and as most source code online is written for it, most people use it, the more people use it, the more code there is for it, so the more people use it.

Advantages

Widely used.
Commands related to the parameters.

Disadvantages

Creator retired (no future updates / bug fixes).
Decompilation bugs (especially in certain advanced jumps).
Many unofficially usable SCM features uncatered for (although these are mostly advanced problems never experienced by the average coder).
Inconvenient syntax.