Difference between revisions of "Mission Scripting (Overview)"

From GTAMods Wiki
Jump to navigation Jump to search
m
 
(142 intermediate revisions by 15 users not shown)
Line 1: Line 1:
 +
{{This|This article deals with the general overview on the mission scripting in GTA 3D series (including [[GTA LCS]] and [[GTA VCS]]). It does not cover [[GTA IV]].<br>
 +
For more information about the GTA IV script read the article about the [[SCO|SCO format]].}}
 +
{{Cleanup-rewrite}}
 +
 +
'''Mission scripting''' is the process of writing scripts: small codes that control many aspects of gameplay. Although most of the game features are [[hardcoded]], still much things could be done via scripting. In fact, every single mission in Grand Theft Auto series comes from the scripts. That is, knowing the format of scripts and having a [[Mission Scripting Tools|proper tool]], it is possible to change the original missions or even create an absoletely new story plot (although scripts is [[Design Your Own Mission|not the only option]] for the latter).
 +
__TOC__
 
== Introduction ==
 
== Introduction ==
 
+
The original mission script is looked like this{{ref|src|[*]}} (taken from Vice City debug.sc file):
The original Mission Script looked something like this (taken from vice city debug.sc file):
 
  
 
  IF IS_BUTTON_PRESSED PAD2 RIGHTSHOULDER1
 
  IF IS_BUTTON_PRESSED PAD2 RIGHTSHOULDER1
Line 20: Line 25:
 
  ENDIF
 
  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:
+
Easy to read and understand, it is fairly basic so anyone with an idea of basic coding (or maybe 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 are [[Mission Pack|alternate mains]] and [[external script]]s, but they all follow the same basic format - hex codes).  Example, for the code:
  
 
  IF IS_CAR_DEAD magic_car
 
  IF IS_CAR_DEAD magic_car
Line 29: Line 34:
 
  D6 00 04 00 19 01 02 45 0E 4D 00 01 FE 3D 87 02 A6 00 02 45 0E
 
  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)
+
This is how the beginning of the [[SA SCM|San Andreas mission script]] looks like:
 +
{| class="wikitable"
 +
!width="250px"|Byte data
 +
!width="250px"|Decompiled data
 +
!width="250px"|Decompiled data with description
 +
|-
 +
| {{hint|A4 03|opcode}}&nbsp;&nbsp;&nbsp;{{hint|09|Data type}}&nbsp;&nbsp;&nbsp;{{hint|4D 41 49 4E 00 00 00 00|Parameter value}}||03A4: 'MAIN'||[[03A4]]: name_thread 'MAIN'
 +
|-
 +
| {{hint|6A 01|opcode}}&nbsp;&nbsp;&nbsp;{{hint|04|Data type}}&nbsp;&nbsp;&nbsp;{{hint|00|Parameter value}}&nbsp;&nbsp;&nbsp;{{hint|04|Data type}}&nbsp;&nbsp;&nbsp;{{hint|00|Parameter value}}||016A: 0 0||[[016A]]: fade 0 time 0
 +
|-
 +
| {{hint|2C 04|opcode}}&nbsp;&nbsp;&nbsp;{{hint|05|Data type}}&nbsp;&nbsp;&nbsp;{{hint|93 00|Parameter value}}||042C: 147||[[042C]]: set_total_missions_to 147
 +
|-
 +
| {{hint|0D 03|opcode}}&nbsp;&nbsp;&nbsp;{{hint|05|Data type}}&nbsp;&nbsp;&nbsp;{{hint|BB 00|Parameter value}}||030D: 187||[[030D]]: set_max_progress 187
 +
|}
 +
 
 +
== Cracking the SCM ==
 +
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 (GTA SA has more), where they started/ended etc, figuring out how many parameters each [[opcode]] had and a lot 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:
 +
 
 +
<source lang="scm">0001: 0
 +
00D6: 0
 +
0256: 4
 +
004D: 52000</source>
 +
 
 +
So the next step was to find out what each opcode does. Some were easy, the very first line of a decompiled script (besides decompiler headers) looks something like:
 +
 
 +
<source lang="scm">0002: @label0034B2</source>
 +
 
 +
The only parameter this command has is an offset within the file, so this is most likely (and in fact is) a GOTO statement, so we know all [[0002]]s are GOTOs. With trials and errors people discovered meanings of many opcodes. With the release of the mobile version of GTA San Andreas, the complete [[list of opcodes]] names became available.
 +
 
 +
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, [[Mission Builder|BWME]] ({{U|Barton Waterduck}}'s Mission Editor) and {{U|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:
 +
 
 +
<source lang="scm">00B1: is_car $car in_cube $lowerx $lowery $lowerz $upperx $uppery $upperz 0</source>
 +
 
 +
As opposed to the gtaMa/DisAsm format:
 +
 
 +
<source lang="scm">is_car_in_cube $car, $lowerx, $lowery, $lowerz, $upperx, $uppery, $upperz, 0</source>
 +
 
 +
(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. Since Barton left the modding community, {{U|Seemann}} created an even more versatile decompiler, [[Sanny Builder]]. It has become the most popular scripting tool.
 +
 
 +
==See also==
 +
* [[Opcode]]
 +
* [[SCM language]]
 +
* [[SCM language III/VC definitions]]
 +
* [[Mission Scripting Tools]]
 +
* [[List of opcodes]]
 +
* {{Icon|SA}} [[Design Your Own Mission]]
 +
 
 +
== External links ==
 +
* {{Icon|trilogy}} {{GTAF|section|317|Coding Forum}}
 +
* {{GTAF|section|326|Mission Mods Showroom}}
 +
* {{note|src}} [http://gtamodding.ru/wiki/%D0%9A%D0%B0%D1%82%D0%B5%D0%B3%D0%BE%D1%80%D0%B8%D1%8F:%D0%98%D1%81%D1%85%D0%BE%D0%B4%D0%BD%D0%B8%D0%BA%D0%B8 Sources of the GTA 3 missions at GTAModding.ru]
 +
* [http://public.sannybuilder.com/sources/gta3scmsrc.zip GTA 3 Script (scm) Rockstar's original sources found in the iPad version]
 +
 
 +
{{N|SA|VC|3}}
 +
 
 +
[[Category:Mission Scripting]]

Latest revision as of 16:08, 30 October 2016

This article deals with the general overview on the mission scripting in GTA 3D series (including GTA LCS and GTA VCS). It does not cover GTA IV.
For more information about the GTA IV script read the article about the SCO format.
40px-Ambox rewrite orange.svg.png This article may need to be rewritten.
Please help improve this article. The discussion page may contain suggestions.

Mission scripting is the process of writing scripts: small codes that control many aspects of gameplay. Although most of the game features are hardcoded, still much things could be done via scripting. In fact, every single mission in Grand Theft Auto series comes from the scripts. That is, knowing the format of scripts and having a proper tool, it is possible to change the original missions or even create an absoletely new story plot (although scripts is not the only option for the latter).

Introduction

The original mission script is looked 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, it is fairly basic so anyone with an idea of basic coding (or maybe 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 are 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

This is how the beginning of the San Andreas mission script looks like:

Byte data Decompiled data Decompiled data with description
A4 03   09   4D 41 49 4E 00 00 00 00 03A4: 'MAIN' 03A4: name_thread 'MAIN'
6A 01   04   00   04   00 016A: 0 0 016A: fade 0 time 0
2C 04   05   93 00 042C: 147 042C: set_total_missions_to 147
0D 03   05   BB 00 030D: 187 030D: set_max_progress 187

Cracking the SCM

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 (GTA SA has more), where they started/ended etc, figuring out how many parameters each opcode had and a lot 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:

0001: 0
00D6: 0
0256: 4
004D: 52000

So the next step was to find out what each opcode does. 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 an offset within the file, so this is most likely (and in fact is) a GOTO statement, so we know all 0002s are GOTOs. With trials and errors people discovered meanings of many opcodes. With the release of the mobile version of GTA San Andreas, the complete list of opcodes names became available.

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 Waterduck's 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 gtaMa/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. Since Barton left the modding community, Seemann created an even more versatile decompiler, Sanny Builder. It has become the most popular scripting tool.

See also

External links