Difference between revisions of "Mission Scripting (Overview)"

From GTAMods Wiki
Jump to navigation Jump to search
m (→‎Opcode)
m (→‎External Links)
Line 1: Line 1:
−
{{Cleanup-rewrite}}
+
'''WPL''' is the format of the map-related files similar to [[IPL]]s from the previous games. It can be edited with [[WPL Manager]].
−
This article deals with the general overview on the '''mission scripting''' in GTA 3D series. 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 mission details and even create an absoletely new story plot (although it's considered to be the most complex area in GTA modding, so most often the scripting results in small scripts adding new features in gameplay).
 
  
−
== Introduction ==
+
== File Format ==
−
The original mission script probably looked something like this (taken from Vice City debug.sc file):
 
  
−
IF IS_BUTTON_PRESSED PAD2 RIGHTSHOULDER1
+
Each world placement file starts with one single header followed by the object placement information. The structure for the header is very simple:
−
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 [[Mission Pack|alternate mains]] and [[external script]]s, but they all follow the same basic format - hex codes). Example, for the code:
+
  4b - UINT32  - Unknown
 +
  4b - UINT32  - Instances
  
−
IF IS_CAR_DEAD magic_car
+
The placement information corresponds to the previous [[Item_Placement#inst|instance]] section of the <code>.ipl</code> files. They have a binary structure like the [[Binary_IPL|binary ipl]] files introduced with [[San Andreas]]:
−
DELETE_CAR magic_car
 
  
−
The equivalent in the main.scm would look something like this:
+
'''Section 0 - INST'''
  
−
  D6 00 04 00 19 01 02 45 0E 4D 00 01 FE 3D 87 02 A6 00 02 45 0E
+
  4b - FLOAT  - Position X
 +
4b - FLOAT  - Position Y
 +
4b - FLOAT  - Position Z
 +
4b - FLOAT  - Rotation X
 +
4b - FLOAT  - Rotation Y
 +
4b - FLOAT  - Rotation Z
 +
4b - FLOAT  - Rotation W
 +
4b - UINT32  - Model name [[:Category:Static_Model_Hashes|hash]]
 +
4b - UINT32  - Unknown
 +
4b - UINT32  - [[LOD]] Index (Index of another model in the current file)
 +
4b - UINT32  - Unknown
 +
4b - UINT32  - Unknown
  
−
This is how the beginning of [[SA SCM]] looks like:
+
''Rotation information as [[Wikipedia:Quarternion|Quarternion]]''
−
{|
 
−
!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
 
−
|}
 
  
−
== Script instructions ==
+
'''Section 3 - Parked Cars'''
−
''The following information is valid for GTA 3D series (including LCS and VCS), except [[GTA 4]], that has completely different scripting engine. For more details on it see the [[SCO|SCO format]] article''.
 
  
−
A [[SCM]] file itself is a [[Wikipedia:Bytecode|bytecode]] containing instructions telling to the game what to do. An instruction consist of an opcode and its parameters (it there are any). Sometime the whole script instruction is called opcode.
+
4b - FLOAT  - Position X
 +
4b - FLOAT  - Position Y
 +
4b - FLOAT  - Position Z
 +
4b - FLOAT  - Unknown
 +
4b - FLOAT  - Unknown
 +
4b - FLOAT  - Unknown
 +
4b - UINT32  - Model name [[:Category:Static_Model_Hashes|hash]]
 +
4b - INT32  - Unknown
 +
4b - INT32  - Unknown
 +
4b - INT32  - Unknown
 +
4b - INT32  - Unknown
 +
4b - INT32  - Unknown
 +
4b - INT32  - Unknown
 +
4b - INT32  - Unknown
  
−
=== Opcode ===
+
'''Section 9 - LODcull'''
−
{{This|This section deals with the technical information on the opcode format. For the opcodes documentation see [[:Category:OpCodes|Opcodes]]}}
 
−
Each script instruction is represented by a number &ndash; opcode ('''op'''eration '''code'''), which is [[Wikipedia:UINT16|UINT16]]. By this number the game engine identifies an action to perform. Say, opcode [[0001]] tells to wait for amount of time, [[0003]] shakes the camera, [[0053]] creates a player, etc.
 
  
−
This is how an opcode [[0001]] looks in a scm file:
+
4b -  FLOAT  - Position X1
−
  {{Hint|0100|opcode}}&nbsp;{{hint|04|data type}}&nbsp;{{hint|00|parameter value}}
+
4b -  FLOAT  - Position Y1
 +
4b -  FLOAT  - Position Z1
 +
4b -  FLOAT  - Position X2
 +
4b -  FLOAT  - Position Y2
 +
4b -  FLOAT  - Position Z2
 +
4b  - UINT32  - number of lod models in wdd file
 +
  4b  - UINT32  - hash1
 +
4b  - UINT32  - hash2
 +
4b  - UINT32  - hash3
 +
4b  - UINT32  - hash4
 +
4b  - UINT32  - hash5
 +
4b  - UINT32  - hash6
 +
4b  - UINT32  - hash7
 +
4b  - UINT32  - hash8
 +
4b  - UINT32  - hash9
 +
4b  - UINT32  - hash10
 +
32b - String  - Model name 1
 +
32b - String  - Model name 2
 +
32b - String  - Model name 3
 +
32b - String  - Model name 4
 +
32b - String  - Model name 5
 +
32b - String  - Model name 6
 +
32b - String  - Model name 7
 +
32b - String  - Model name 8
 +
32b - String  - Model name 9
 +
32b - String  - Model name 10
  
−
* First part is the opcode number in a [[Wikipedia:Endianness|little-endian]] format.
+
'''Section 10 - Unknown Zon or Cull'''
−
* Second part is the [[#Data types|data type]]
 
−
* Third part is a parameter value
 
  
−
When a mission script is disassembled, opcodes are written in a human-readable format. The example above will look something like this:
+
4b - FLOAT    - Position X1
−
  wait 0
+
4b - FLOAT    - Position Y1
−
This is made for the end-user convenience only. The game does not know what the word ''wait'' means, but it knows what the opcode 0001 is, so when a mission script is assembled the commands are written back in raw byte form.
+
4b - FLOAT    - Position Z1
 +
  4b - FLOAT    - Position X2
 +
4b - FLOAT    - Position Y2
 +
4b - FLOAT    - Position Z2
  
−
As it has been said, an opcode is UINT16 number. It means the minimum opcode is [[0000]] and maximum opcode is 0xFFFF. However due to a specific of the SCM language, any numbers above 0x7FFF denote negative conditional opcodes. More on this [[Conditional statement|read there]]. The original unmodded game supports a way smaller amount of opcodes (maximum [[0A4E]] for [[San Andreas]]), but there are tools adding new ones, most notably [[CLEO|CLEO library]].
+
'''''X1, Y1, Z1''' = lower left vertex position'' and
 +
'''''X2, Y2, Z2''' = upper right vertex position''
  
−
After an opcode number the data types and parameter values follow{{Ref|05B6|[*]}}.
 
  
−
=== Data types ===
 
−
Data type is a single byte written before any parameter{{ref|vcstr|[*]}}. The purpose of it is to tell to the game how much bytes to read next and what kind of data it is.
 
−
{|{{Prettytable}} class="collapsible"
 
−
!Data type
 
−
!Parameter Length<br> (bytes)
 
−
!Game
 
−
!Description
 
−
|-
 
−
| 00  || 0  ||align=center|{{Icon|3}}&nbsp;{{Icon|vc}}&nbsp;{{Icon|sa}} ||end of argument list ([[004F]], [[0913]] and similar){{ref|partype0|[*]}}
 
−
|-
 
−
| 01  || 4  ||align=center|{{Icon|3}}&nbsp;{{Icon|vc}}&nbsp;{{Icon|sa}} ||immediate 32 bit signed int
 
−
|-
 
−
| 02  || 2  ||align=center|{{Icon|3}}&nbsp;{{Icon|vc}}&nbsp;{{Icon|sa}} ||global int/float var
 
−
|-
 
−
| 03  || 2  ||align=center|{{Icon|3}}&nbsp;{{Icon|vc}}&nbsp;{{Icon|sa}} ||local int/float var
 
−
|-
 
−
| 04  || 1  ||align=center|{{Icon|3}}&nbsp;{{Icon|vc}}&nbsp;{{Icon|sa}} ||immediate 8 bit signed int
 
−
|-
 
−
| 05  || 2  ||align=center|{{Icon|3}}&nbsp;{{Icon|vc}}&nbsp;{{Icon|sa}} ||immediate 16 bit signed int
 
−
|-
 
−
| 06  || 4  ||align=center|{{Icon|3}}&nbsp;{{Icon|vc}}&nbsp;{{Icon|sa}} ||immediate 32 bit float
 
−
|-
 
−
| 07  || 6  ||align=center|{{Icon|sa}} ||global int/float var array{{ref|varray|[*]}}
 
−
|-
 
−
| 08  || 6  ||align=center|{{Icon|sa}} ||local int/float var array{{ref|varray|[*]}}
 
−
|-
 
−
| 09  || 8  ||align=center|{{Icon|sa}} ||immediate 8 byte string{{ref|str8|[*]}}
 
−
|-
 
−
| 10  || 2  ||align=center|{{Icon|sa}} ||global 8 byte string var
 
−
|-
 
−
| 11  || 2  ||align=center|{{Icon|sa}} ||local 8 byte string var
 
−
|-
 
−
| 12  || 6  ||align=center|{{Icon|sa}} ||global 8 byte string var array{{ref|varray|[*]}}
 
−
|-
 
−
| 13  || 6  ||align=center|{{Icon|sa}} ||local 8 byte string var array{{ref|varray|[*]}}
 
−
|-
 
−
| 14  || 1+x ||align=center|{{Icon|sa}} ||immediate varlen string - first you read 1 byte which gives you length of the rest which is text{{ref|str16|[*]}}
 
−
|-
 
−
| 15  || 16  ||align=center|{{Icon|sa}} ||immediate 16 byte string{{ref|sa16|[*]}}
 
−
|-
 
−
| 16  || 2  ||align=center|{{Icon|sa}} ||global varlen string var
 
−
|-
 
−
| 17  || 2  ||align=center|{{Icon|sa}} ||local varlen string var
 
−
|-
 
−
| 18  || 6  ||align=center|{{Icon|sa}} ||global varlen string var array{{ref|varray|[*]}}
 
−
|-
 
−
| 19  || 6  ||align=center|{{Icon|sa}} ||local varlen string var array{{ref|varray|[*]}}
 
−
|-
 
−
|>31  ||8 ||align=center|{{Icon|3}}&nbsp;{{Icon|vc}} ||immediate 8 byte string{{ref|vcstr|[*]}}
 
−
|}
 
−
As it might be seen from the table two bytes <code>{{hint|02 00|little-endian format}}</code> could have 3 different meanings as a parameter: if it's preceeded by a data type of 2 it is a global variable (<span style="color:blue">$2</span>), data type of 3 &ndash; local variable (<span style="color:blue">2@</span>), data type of 5 - 16-bit number (<span style="color:maroon">2</span>), so only the data type allows the game to determine the correct parameter meaning.
 
  
−
Data types for [[Liberty City Stories]] and [[Vice City Stories]] are much different. First of all, many data types itself denote an immediate value. For example, data type 01 is a value of 0, data type 02 - 0.0, etc. The floating-point values are packed (1, 2 or 3 bytes of length instead of [[Wikipedia:IEEE_754-1985#Single-precision_32-bit|common 4]]). Some data types itself are the names of variables.
+
<!---
 +
;Header
 +
<source lang="cpp">
 +
struct Header_t
 +
{
 +
    BYTE byteUnknown01[4];
 +
    DWORD dwNbrOfBlockInst;
 +
};
 +
</source>
  
−
{|{{Prettytable}} class="collapsible"
+
;InstBlock (Start from 0x44)
−
!Data type
+
<source lang="cpp">
−
!Parameter Length<br> (bytes)
+
  struct Inst_t
−
!Game
+
  {
−
!Description
+
    float fPosition[3];
−
|-
+
    float fRotation[4];
−
| 00 || 0 ||align=center|{{Icon|LCS}}&nbsp;{{Icon|VCS}}||end of argument list{{ref|partype0|[*]}}
+
    DWORD dwModelNameHash;
−
|-
+
    BYTE byteUnknown01[4];
−
| 01 || 0 ||align=center|{{Icon|LCS}}&nbsp;{{Icon|VCS}}||0
+
    DWORD dwAttachedLod;
−
|-
+
    BYTE byteUnknown02[8];
−
| 02 || 0 ||align=center|{{Icon|LCS}}&nbsp;{{Icon|VCS}}||0.0
+
  };
−
|-
+
</source>
−
| 03 || 1 ||align=center|{{Icon|LCS}}&nbsp;{{Icon|VCS}}||packed float{{ref|lcsfloat|[*]}}
+
-->
−
|-
 
−
| 04  || 2 ||align=center|{{Icon|LCS}}&nbsp;{{Icon|VCS}}||packed float{{ref|lcsfloat|[*]}}
 
−
|-
 
−
| 05  || 3 ||align=center|{{Icon|LCS}}&nbsp;{{Icon|VCS}}||packed float{{ref|lcsfloat|[*]}}
 
−
|-
 
−
| 06 || 4 ||align=center|{{Icon|LCS}}&nbsp;{{Icon|VCS}}||immediate 32 bit signed int
 
−
|}
 
  
−
{{note|lcsfloat}} To get the value of a packed float, read the needed amount of bytes (1, 2 or 3) from a scm to a byte[4] array starting from the 3rd, 2nd or 1st element of it respectively. 0 byte of the array is always empty. Then cast this array as a float and that's it.<!-- the description suxxx. need some code -->
+
== XPL ==
 +
In the XBox 360's version of GTA 4 same files have the extension <code>.xpl</code>. The XPL and WPL formats  are same, but due to the fact XPL files are used on the Xenon platform its data is stored in the [[Wikipedia:Endianness|big-endian order]].
 +
<!--not sure where to put this: "They are used to map generic objects which are defined with another path in the [[Images.txt|image listing]] file."-->
  
−
{{Incomplete}}
+
== Tools ==
 +
* [[WPL Manager]] &ndash; by {{U|UZI-I|Yoann (UZI-I)}}
  
−
=== Parameters ===
+
== External Link ==
−
The game engine knows amount of parameters for each opcode (1 for [[0001]], 2 for [[0004]], 13 for [[014B]], etc). If the script contains another number of parameter it causes a crash.
+
* {{GTAF|389423|WPL file format specification}}
  
−
The parameters could be one of following kinds:
+
{{GTA4-navi}}
−
* Immediate values
+
{{File-stub}}
−
** integer numbers
+
[[Category:Map Formats]][[Category:GTA 4]]
−
** floating-point numbers
 
−
** [[#Strings|short strings]]
 
−
** {{icon|sa}} [[#Strings|long strings]]
 
−
* Variables
 
−
** global variables
 
−
** local variables
 
−
* {{icon|sa}} [[#Arrays|Arrays]]
 
−
{{Incomplete}}
 
−
 
 
−
==== Strings ====
 
−
''Strings'' are the sequences of symbols. Those including {{hint|letters|A..Z}}, {{hint|numbers|0..9}}, some other chars like {{hint|underscore|_}} or {{hint|at-sign|@}}. GTA has no limits on what symbols could or could not be used in the strings. Also, no matter with what symbol a string begins. It could be any, even a space.
 
−
 
 
−
There are two kinds of the strings used.
 
−
 
 
−
{{note|str8}} '''Short string'''. This is the most common type of a string, that is used in every game since [[GTA 3]]. The term ''short'' means that this string is strongly limited to its length. Maximum symbols it could contain is 7 and the last one (8th) is a [[Wikipedia:null terminator|null terminator]] byte. When compiled such strings occupy 8 bytes of a [[SCM]] file no matter if the string is actually shorter (the rest of bytes is filled with zero bytes).
 
−
 
 
−
{{note|sa16}} SA scripting engine also has data type 15 that denotes the short string containing up to 15 symbols. This kind of strings is only supported by [[Sanny Builder]]. They are handled in a same manner as 8-bytes strings, but occupy 16 bytes of a SCM file.
 
−
{|
 
−
!width="250px" align="left"|String
 
−
!width="250px" align="left"|Equivalent in SCM
 
−
|-
 
−
| <span style="color:red">'MAIN'</span>||{{Hint|09|data type}}&nbsp;&nbsp;&nbsp;{{hint|4D 41 49 4E 00 00 00 00|string}}
 
−
|-
 
−
| <span style="color:red">'MODDING'</span>||{{Hint|09|data type}}&nbsp;&nbsp;&nbsp;{{hint|4D F4 44 49 4E 47 00|string}}
 
−
|-
 
−
| <span style="color:red">'SAVE_YOUR_SOULS!'</span>||{{Hint|0F|data type}}&nbsp;&nbsp;&nbsp;{{hint|53 41 56 45 5F 4F 55 52 5F 53 4F 55 4C 53 21 00|string}}
 
−
|}
 
−
{{note|str16}} '''Long string'''. This type was first introduced in San Andreas. Maximum length depends on the opcode{{Ref|longstringslimits|[*]}}.
 
−
 
 
−
{{Incomplete}}
 
−
 
 
−
==== Arrays ====
 
−
{{note|varray}} Native ''[[Wikipedia:Array|arrays]]'' support was introduced in GTA SA, however there were different implementations of [[VC_Arrays|arrays in Vice City]]. In SA SCM arrays are assembled as 2 UINT16s and 2 bytes:
 
−
2b - UINT16 - array offset{{ref|arrayoffset|[*]}}
 
−
2b - UINT16 - array index{{ref|arrayindex|[*]}}
 
−
1b - BYTE  - array size
 
−
1b - BYTE  - flags{{ref|arrayflags|[*]}}
 
−
 
 
−
{{note|arrayoffset}} An array offset basically is a variable number. If it's a global array, the offset is a global variable index from which the array begins. For example, if the global array offset is 150 (<code>{{hint|96 00|little-endian}}</code>) it means that the first element of the array is <span style="color:blue">$150</span>, the second one is <span style="color:blue">$151</span>, etc. Same valid for the local arrays (offset is a local variable index). <!-- global variables are multiplied by 4-->
 
−
 
 
−
{{note|arrayindex}} An array index is a variable number (global or local one) that holds the value of array index. For example, if array index is 3 (<code>{{hint|03 00|little-endian}}</code>), the game will read either global variable <span style="color:blue">$3</span> or local variable <span style="color:blue">3@</span> depending on the flags. This variable holds the number which is array element ID to work with. For example, if the array index is <span style="color:blue">$3</span>, and <span style="color:blue">$3</span> holds number <span style="color:maroon">5</span>, the game will read 5th element of the array.
 
−
 
 
−
{{note|arrayflags}} Flags
 
−
{|{{Prettytable}}
 
−
|-
 
−
|0x0 - integer array with local variable as index||0x80 - integer array with global variable as index
 
−
|-
 
−
|0x1 - float array with local variable as index||0x81 - float array with global variable as index
 
−
|-
 
−
|0x2 - short string array with local variable as index||0x82 - short string array with global variable as index
 
−
|-
 
−
|0x3 - long string array with local variable as index||0x83 - long string array with global variable as index
 
−
|}
 
−
{|
 
−
!width="250px" align="left"|Array
 
−
!width="250px" align="left"|Equivalent in SCM
 
−
|-
 
−
| <span style="color:blue">{{hint|$150(3@,6f)|Sanny Builder syntax}}</span>||{{hint|07|data type}}&nbsp;&nbsp;&nbsp;{{hint|96 00|array offset}}&nbsp;{{hint|03 00|array index}}&nbsp;{{hint|06|size}}&nbsp;{{hint|01|flag}}
 
−
|-
 
−
| <span style="color:blue">{{hint|10@(9@,5s)|Sanny Builder syntax}}</span>||{{hint|0D|data type}}&nbsp;&nbsp;&nbsp;{{hint|0A 00|array offset}}&nbsp;{{hint|09 00|array index}}&nbsp;{{hint|05|size}}&nbsp;{{hint|02|flag}}
 
−
|}
 
−
 
 
−
=== Notes ===
 
−
{{note|vcstr}} In [[GTA 3]] and [[Vice City]] short strings (8 bytes) have no data type preceeding it. If the byte does not fit data type range (0..6 for GTA 3 and VC), it's recognized as a beginning of a string and next 8 bytes are read.
 
−
 
 
−
{{note|partype0}} Some opcodes have variable amount of parameters. Most known opcode is [[004F]] that creates a new [[thread]] and passes arguments to it. The number of such parameters could vary, so the special data type denotes the end of parameters.
 
−
 
 
−
The maximum amount of parameters for any opcode is 16 for GTA 3 and GTA VC, 32 for San Andreas.
 
−
 
 
−
{{note|05B6}} {{Icon|SA}} Opcode [[05B6]] is a special opcode that  defines a table. Immediately after opcode number the stream of data (128 bytes) follow, without a data type.
 
−
 
 
−
{{note|longstringslimits}} {{GTAF|post|261006|3940262|Post by Seemann describing limits for the long strings in SA}}
 
−
 
 
−
== Cracking the SCM ==
 
−
As has been said, very little of the code was supplied with the game in a decompiled 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 decompilers 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 ([[GTA 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 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:
 
−
 
 
−
:label035F78
 
−
0001: 0?
 
−
00D6: 0?
 
−
0256: 4??
 
−
 
−
 
 
−
That doesn't still doesn't mean a lot 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
 
−
 
−
 
 
−
Some were easy, the very first line of a decompiled script (besides decompiler headers) looks something like:
 
−
 
 
−
 
−
 
 
−
The only parameter this command has is a reference to a [[label]], so this is most likely (and in fact is) a jump statement, so we know all [[0002]]s are jumps.  Of course, finding what OpCodes do (and in fact 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 - many OpCodes have still not been named, but with the amount of OpCodes discovered so far, we have a general idea on what 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]] ([[User:Barton Waterduck|Barton Waterduck]]'s Mission Editor) and [[User:CyQ|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, [[User:Seemann|Seemann]] created an even more versatile decompiler, the [[Sanny Builder]]. It has become the most popular mission builder.
 
−
 
 
−
== The Tools ==
 
−
''Main article: [[Mission Scripting Tools]]''
 
−
 
 
−
There are three main builders for GTA 3, VC, and SA, and one for LCS and VCS.
 
−
 
 
−
=== Mission Builder ===
 
−
''Main article: [[Mission Builder]]''
 
−
''(BWME - note: although BWME was a slightly different tool, I shall be referring to this as 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.
 
−
 
 
−
;Code format:
 
−
 
 
−
Early builders used data type identifiers on all numbers, these were
 
−
 
 
−
 
−
 
 
−
Later versions of the builder got rid of number type definitions, assigning types based on the size of the number.  Integers were made integers by being not a whole number (e.g. 10.5 or 10.0 if you want a whole number defined as an integer).  They also replaced DMA variables with global variables where the name was the hex address in decimal divided by 4 (each variable uses 4 bytes of memory).
 
−
 
 
−
;Advantages: Widely used.<br>Commands related to the parameters.<br>Macros and program execution facilities inbuilt.
 
−
 
 
−
;Disadvantages: Creator retired (no future updates / bug fixes).<br>Decompilation bugs (especially in certain advanced jumps).<br>Many unofficially usable SCM features uncatered for (although these are mostly advanced problems never experienced by the average coder).<br>Inconvenient syntax.
 
−
 
 
−
;Other notes: GUI.<br>Compiler inbuilt.
 
−
 
 
−
=== Point ===
 
−
''Main article: [[Point]]''
 
−
This is still very much in the development stages, it is the first user made high-level scripting tool (in fact, first high-level at all, even Rockstar's compiler is only an advanced parser) made for coding GTA.  Originally developed for VC/III, this tool has been expanded to work for all three 3D games.  One major disadvantage to this is that the file headers it writes, while readable by the game, are unrecognized by any line by line decompilers.  So once a file has been compiled in Point, it cannot be decompiled again by another tool to see the exact generated code.
 
−
 
 
−
=== Sanny Builder ===
 
−
''Main article:'' [[Sanny Builder]].
 
−
 
 
−
Another new tool by [[User:Seemann|Seemann]].  This is being developed for SA initially (although porting to other games may be an option) and is loosely based on BWME code.  It was originally created using the SAscm.ini file from BWME 0.33 SA but has since been expanded to include many different features, some taken from Gtama, some new (such as a basic class system and direct HEX input (as requested by Y_Less)).  This tool is still being developed and has now introduced a basic class system so you can do things such as "player.health += 5", this system is also being adapted for point.
 
−
 
 
−
The code format is based on a combination of both Gtama and BWME formats, although you can't force data types as you could in early Mission Builders (e.g. 0004: $var = 0&& which would normally be assigned one byte, not four).
 
−
 
 
−
;Code format (note these are for SA, not VC as the others listed are):
 
−
 
 
−
;: $ - global variable<br>s$ - global string variable<br>v$ - global long string variable<br>@ - label (text directly AFTER used to reference this label in jumps)<br>@ - local variable (number BEFORE denotes variable)<br>@s - local string variable (number BEFORE denotes variable)<br>@v - local long string variable (number BEFORE denotes variable)<br><nowiki>'...'</nowiki> - string (first 8 bytes after opcode when compiled)<br>"..." - debug string text<br># - model identifier (means you can enter the id name of a model rather than the number)
 
−
 
 
−
=== Disassembler/Assembler ===
 
−
''Main article: [[gtama]]''
 
−
''(GTA Mission Assembler - gtaMa, Vice City Disassembler - DisAsm):''
 
−
 
 
−
These tools use one word commands, although they may consist of multiple words concatenated by an underscore ("_"), e.g. <code>is_player_defined</code>.  They still compile each line as-is (i.e. no interpretation or code generation) so the game will execute exactly the commands you enter. This is similar to programming in ASM mnemonics, whereas BWME is more similar to machine code.  The decompiled file is split up into a number of <code>.gsr</code> files, each one containing the code to one mission.  This reduces file sizes considerably as BWME generated files are huge (around 6 MB <code>.txt</code> files), containing the whole code.  The code is in the format of a command, followed by a list of parameters, separated by spaces - this can make named variables easy to distinguish from commands.
 
−
 
 
−
The disassembler (DisAsm) is written by [[User:CyQ|CyQ]] and the assembler (gtaMa) is written by Dan Strandberg.  These two tools work together to de- and re-compile the code.
 
−
 
 
−
;Code format:
 
−
 
 
−
;: $ - global variable (data type 02)<br>! - local variable (data type 03)<br>@ - label (text directly after used to reference this label in jumps)<br>"" - string (no data type, first 8 bytes after opcode when compiled)<br>% - model identifier (means you can enter the id name of a model rather than the number - data type 05 for the compiled number)
 
−
 
 
−
;Advantages: Small files sizes.<br>Clearer code - data and commands separated.<br>Active creator (although no longer developing).<br>More support for advanced features (supports memory hacking methods not widely used).<br>Open source.<br>Online updateable ini.<br>Format used on custom error handler for VC.
 
−
 
 
−
;Disadvantages: Not widely used.<br>Code spread across multiple files - harder for searching.<br>Data not easily related to code.
 
−
 
 
−
;Other notes: Command line based.
 
−
 
 
−
== External Links ==
 
−
* {{GTAF|section|49|Mission Coding Forum}}
 
−
* {{GTAF|section|65|Mission Mods Showroom}}
 
−
 
 
−
{{SA-navi}}
 
−
[[Category:Mission Scripting]][[Category:GTA 3]][[Category:GTA VC]]
 

Revision as of 15:12, 29 May 2009

WPL is the format of the map-related files similar to IPLs from the previous games. It can be edited with WPL Manager.

File Format

Each world placement file starts with one single header followed by the object placement information. The structure for the header is very simple: 

4b - UINT32   - Unknown
4b - UINT32   - Instances

The placement information corresponds to the previous instance section of the .ipl files. They have a binary structure like the binary ipl files introduced with San Andreas:

Section 0 - INST 

4b - FLOAT   - Position X
4b - FLOAT   - Position Y
4b - FLOAT   - Position Z
4b - FLOAT   - Rotation X
4b - FLOAT   - Rotation Y
4b - FLOAT   - Rotation Z
4b - FLOAT   - Rotation W
4b - UINT32  - Model name hash
4b - UINT32  - Unknown
4b - UINT32  - LOD Index (Index of another model in the current file)
4b - UINT32  - Unknown
4b - UINT32  - Unknown

Rotation information as Quarternion

Section 3 - Parked Cars 

4b - FLOAT   - Position X
4b - FLOAT   - Position Y
4b - FLOAT   - Position Z
4b - FLOAT   - Unknown
4b - FLOAT   - Unknown
4b - FLOAT   - Unknown
4b - UINT32  - Model name hash
4b - INT32   - Unknown
4b - INT32   - Unknown
4b - INT32   - Unknown
4b - INT32   - Unknown
4b - INT32   - Unknown
4b - INT32   - Unknown
4b - INT32   - Unknown

Section 9 - LODcull 

4b -  FLOAT   - Position X1
4b -  FLOAT   - Position Y1
4b -  FLOAT   - Position Z1
4b -  FLOAT   - Position X2
4b -  FLOAT   - Position Y2
4b -  FLOAT   - Position Z2
4b  - UINT32  - number of lod models in wdd file
4b  - UINT32  - hash1 
4b  - UINT32  - hash2
4b  - UINT32  - hash3
4b  - UINT32  - hash4
4b  - UINT32  - hash5
4b  - UINT32  - hash6
4b  - UINT32  - hash7
4b  - UINT32  - hash8
4b  - UINT32  - hash9
4b  - UINT32  - hash10
32b - String  - Model name 1
32b - String  - Model name 2
32b - String  - Model name 3
32b - String  - Model name 4
32b - String  - Model name 5
32b - String  - Model name 6
32b - String  - Model name 7
32b - String  - Model name 8
32b - String  - Model name 9
32b - String  - Model name 10

Section 10 - Unknown Zon or Cull 

4b - FLOAT     - Position X1
4b - FLOAT     - Position Y1
4b - FLOAT     - Position Z1
4b - FLOAT     - Position X2
4b - FLOAT     - Position Y2
4b - FLOAT     - Position Z2

X1, Y1, Z1 = lower left vertex position and X2, Y2, Z2 = upper right vertex position



XPL

In the XBox 360's version of GTA 4 same files have the extension .xpl. The XPL and WPL formats are same, but due to the fact XPL files are used on the Xenon platform its data is stored in the big-endian order.

Tools

External Link

v · d · e
GTA IV Grand Theft Auto IV
File Formats.dat • .gxt • .ide • .img • .ipl • .nod • .sco • .rpf • .rrr • .wad • .wbd/.wbn • .wdd • .wdr • .wft • .whm • .wpl • .wtd
DocumentationAudio • Bink Video • Cryptography • Cutscenes • GXT Text • Image listing • Keycodes • Map Listing • Native functions • Paths • Radar Blips • Radio Stations • Saves • Scenarios • VTable • Weapons
ToolsASI Loader • ENBSeries • G-Texture • GIMS IV • Ingame WPL Editor • IV Needle • OpenIV • SparkIV • XLiveLess • WPL Manager • X Mod Installer
Alice • C++ Script Hook • .NET Script Hook • Scocl
TutorialsImporting Textures with OpenIV • Importing Textures with SparkIV
ModificationsGostown IV • Four Multiplayer • IV Multiplayer • CitizenMP:IV Reloaded
Useful linksCommunity portal • Discussion forums • Modding forums • Mods on GTAGarage.com
ImportantBlue.png This file format article is a stub. You can help by expanding it.
Retrieved from "https://gtamods.com/mediawiki/index.php?title=Mission_Scripting_(Overview)&oldid=6670"