SCO - Revision history

A-Dust at 01:03, 22 September 2010

2010-09-22T01:03:06Z

← Older revision		Revision as of 01:03, 22 September 2010
Line 1:		Line 1:
	{{toc}}		{{toc}}
	'''SCO''' files contain [[~~GTA 4~~]]'s game scripts. Its new format replaces old [[SCM\|scm]] one.		'''SCO''' files contain [[Grand Theft Auto IV\|Grand Theft Auto IV's]] game scripts. Its new format replaces old [[SCM\|scm]] one.

	== File Format ==		== File Format ==

Gtabot: /* Opcodes */removing template:note, removed: {{note|1}}

2010-03-28T18:10:43Z

Opcodes: removing template:note, removed: {{note|1}}

← Older revision		Revision as of 18:10, 28 March 2010
Line 197:		Line 197:
	\|}		\|}

	~~{{note\|1}}~~ The Vectors on the stack are pointers to the memory containing the full vector. A Vector is characterised by this structure:		The Vectors on the stack are pointers to the memory containing the full vector. A Vector is characterised by this structure:

	4b - FLOAT32 - X		4b - FLOAT32 - X

Gtabot: clean up, replaced: {{TocRight}} → {{toc}}

2010-01-25T19:17:48Z

clean up, replaced: {{TocRight}} → {{toc}}

← Older revision		Revision as of 19:17, 25 January 2010
Line 1:		Line 1:
	{{~~TocRight~~}}		{{toc}}
	'''SCO''' files contain [[GTA 4]]'s game scripts. Its new format replaces old [[SCM\|scm]] one.		'''SCO''' files contain [[GTA 4]]'s game scripts. Its new format replaces old [[SCM\|scm]] one.

Gtabot: /* See also */clean up, replaced: {{GTA4-navi}} → {{gtaiv}}

2010-01-23T20:25:03Z

See also: clean up, replaced: {{GTA4-navi}} → {{gtaiv}}

← Older revision		Revision as of 20:25, 23 January 2010
Line 220:		Line 220:
	* [[Mission Scripting (Overview)]] – introduction to mission scripting in the previous games		* [[Mission Scripting (Overview)]] – introduction to mission scripting in the previous games

	{{~~GTA4-navi~~}}		{{gtaiv}}
	[[Category:Mission Script]][[Category:File Formats]]{{fdl}}		[[Category:Mission Script]][[Category:File Formats]]{{fdl}}

Gtabot: clean up,

2010-01-23T20:12:34Z

clean up,

← Older revision		Revision as of 20:12, 23 January 2010
Line 28:		Line 28:
	Opcodes can have varying sizes, but all opcodes are identified by their first byte. There are 79 opcodes which can occur and any opcode above 80 is a Push opcode which pushes '''it's own number - 96''' onto the stack. For example, opcode 100 will push 4 onto the stack. Opcodes 76,77,78 deal with XLive protected buffers and are available on the PC platform only. Undefined opcodes (i.e. opcode 79), will cause a forceful abort of the script execution.		Opcodes can have varying sizes, but all opcodes are identified by their first byte. There are 79 opcodes which can occur and any opcode above 80 is a Push opcode which pushes '''it's own number - 96''' onto the stack. For example, opcode 100 will push 4 onto the stack. Opcodes 76,77,78 deal with XLive protected buffers and are available on the PC platform only. Undefined opcodes (i.e. opcode 79), will cause a forceful abort of the script execution.

	{\|~~{{Prettytable}}~~ class="collapsible"		{\|class="prettytable collapsible"
	!ID		!ID
	!Name		!Name
Line 96:		Line 96:
	\|30\|\| vneg \|\| Reverses the sign on the first vector{{Ref\|1}} on the stack \|\| 1 byte		\|30\|\| vneg \|\| Reverses the sign on the first vector{{Ref\|1}} on the stack \|\| 1 byte
	\|-		\|-
	\|31\|\| iand \|\| Performs an [[Wikipedia:~~Logical_conjunction~~\|And]] operation to the first 2 integers on the stack \|\| 1 byte		\|31\|\| iand \|\| Performs an [[Wikipedia:Logical conjunction\|And]] operation to the first 2 integers on the stack \|\| 1 byte
	\|-		\|-
	\|32\|\| ior \|\| Performs an [[Wikipedia:~~Logical_disjunction~~\|Or]] operation to the first 2 integers on the stack \|\| 1 byte		\|32\|\| ior \|\| Performs an [[Wikipedia:Logical disjunction\|Or]] operation to the first 2 integers on the stack \|\| 1 byte
	\|-		\|-
	\|33\|\| ixor \|\| Performs a [[Wikipedia:XOR\|Xor]] operation to the first 2 integers on the stack \|\| 1 byte		\|33\|\| ixor \|\| Performs a [[Wikipedia:XOR\|Xor]] operation to the first 2 integers on the stack \|\| 1 byte
Line 210:		Line 210:

	==High Level Representation==		==High Level Representation==
	To turn the assembly of a SCO file into a high level representation some factors have to be considered. Arrays and structures can be defined, so it is reasonable to assume there is some kind of typecasting, even if it is only between the following types; [[Wikipedia:~~Integer_~~(~~computer_science~~)\|int]], [[Wikipedia:~~Floating_point~~\|float]], [[Wikipedia:~~String_~~(~~computer_science~~)\|string]] or a predefined structure. It is interesting to note that opcodes exist to typecast integers and concatenate them directly to strings, this suggests the SCO language has a java like way of handling strings (using + and += for concatenation). The SCO file does not seem to have native support for the notion of classes, however this is not to say they could not be implemented within SCO itself similar to how they are done at a low level in C++.		To turn the assembly of a SCO file into a high level representation some factors have to be considered. Arrays and structures can be defined, so it is reasonable to assume there is some kind of typecasting, even if it is only between the following types; [[Wikipedia:Integer (computer science)\|int]], [[Wikipedia:Floating point\|float]], [[Wikipedia:String (computer science)\|string]] or a predefined structure. It is interesting to note that opcodes exist to typecast integers and concatenate them directly to strings, this suggests the SCO language has a java like way of handling strings (using + and += for concatenation). The SCO file does not seem to have native support for the notion of classes, however this is not to say they could not be implemented within SCO itself similar to how they are done at a low level in C++.

	== Tools ==		== Tools ==
	* ~~{{GTAF\|396486\|Scone}} –~~ SCO (Dis-)assembler by {{U\|Sacky}}		* SCO (Dis-)assembler by {{U\|Sacky}}
	* [[OpenIV]] – contains a built-in decompiler		* [[OpenIV]] – contains a built-in decompiler
	* [[SparkIV]] – contains a built-in decompiler		* [[SparkIV]] – contains a built-in decompiler

Gboyers: 1 revision: Imported from gtamodding.com - under GNU FDL

2010-01-11T23:55:38Z

1 revision: Imported from gtamodding.com - under GNU FDL

← Older revision	Revision as of 23:55, 11 January 2010
(No difference)

gtw>Sacky@GTAM: Removed Inaccurate High Level Representation Documentation, will replace later

2009-04-09T14:51:34Z

Removed Inaccurate High Level Representation Documentation, will replace later

New page

{{TocRight}}
'''SCO''' files contain [[GTA 4]]'s game scripts. Its new format replaces old [[SCM|scm]] one.

== File Format ==
A SCO file is layed out into 4 segments. First the [[#Header|header]] containing information about the SCO file. Then the [[#Code Segment|code segment]] which contains the opcode's which govern how the script behaves. The next segment is the [[#Global Variables|global variables]] container which contains enough space to hold the scripts global variables. The last is the [[#Public Variables|public variables]] container, it is unclear what this segment actually does.

=== Header ===
There are 2 types of SCO files, an encrypted and unencrypted one. Each file however shares the same unencrypted header structure, and you can use this to determine which type of SCO file you are dealing with. The size of this header is '''24 bytes'''.

4b - CHAR[4]/UINT32 - SCO Identifier
4b - UINT32 - Code Size
4b - UINT32 - Global Var Count
4b - UINT32 - Public Var Count
4b - UINT32 - Script Flags
4b - UINT32 - Signature

The SCO Identifier will be "SCR\r" (or 0xD524353) in an unencrypted version, and "scr"+0xE (or 0xE726373) in an encrypted version. To decrypt an encrypted version you must decrypt each segment (except the header) separately using GTA IV's AES [[Cryptography]].
The Code Size refers to the amount of bytes the code section takes up.
The Global Var Count refers to the amount of global variables the SCO file contains. The segment for global variables starts at the end of Header + Code Size, and continues for 4x the global variable count (due to the global variables being stored in 4 byte's each).
The Public Var Size refers to the amount of public variables the SCO file contains. The segment for public variables starts at the end of Header + Code Size + Global Var Count * 4, and continues for 4x the public variable count (due to the public variables being stored in 4 byte's each).
The Script Flags are boolean bits which are currently unexplained.
The Signature only differs in navgen_main, but could possibly set the script priority.

===Code Segment===
The Code Segment contains the opcodes which govern the scripts behaviour.

====Opcodes====
Opcodes can have varying sizes, but all opcodes are identified by their first byte. There are 79 opcodes which can occur and any opcode above 80 is a Push opcode which pushes '''it's own number - 96''' onto the stack. For example, opcode 100 will push 4 onto the stack. Opcodes 76,77,78 deal with XLive protected buffers and are available on the PC platform only. Undefined opcodes (i.e. opcode 79), will cause a forceful abort of the script execution.

{|{{Prettytable}} class="collapsible"
!ID
!Name
!Description
!Length
|-
|0|| nop || No operation || 1 byte
|-
|1|| iadd || Adds the top 2 items on the stack || 1 byte
|-
|2|| isub || Subtracts the top 2 items on the stack || 1 byte
|-
|3|| imul || Multiplies the top 2 items on the stack || 1 byte
|-
|4|| idiv || Divides the top 2 items on the stack || 1 byte
|-
|5|| imod || Mods the top 2 items on the stack || 1 byte
|-
|6|| iszero || Checks the first item on the stack to see if it equals 0 || 1 byte
|-
|7|| ineg || Reverses the sign on the item on the top of the stack || 1 byte
|-
|8|| icmpeq || Compares the top 2 integers on the stack to see if they are equal || 1 byte
|-
|9|| icmpne || Compares the top 2 integers on the stack to see if they are not equal || 1 byte
|-
|10|| icmpgt || Compares the top 2 integers on the stack to see if the first one is greater than the second one || 1 byte
|-
|11|| icmpge || Compares the top 2 integers on the stack to see if the first one is greater than or equal to the second one || 1 byte
|-
|12|| icmplt || Compares the top 2 integers on the stack to see if the first one is less than the second one || 1 byte
|-
|13|| icmple || Compares the top 2 integers on the stack to see if the first one is less than or equal to the second one || 1 byte
|-
|14|| fadd || Adds the top 2 floats on the stack || 1 byte
|-
|15|| fsub || Subtracts the top 2 floats on the stack || 1 byte
|-
|16|| fmul || Multiplies the top 2 floats on the stack || 1 byte
|-
|17|| fdiv || Divides the top 2 floats on the stack || 1 byte
|-
|18|| fmod || Mods the top 2 floats on the stack || 1 byte
|-
|19|| fneg || Reverses the sign on the first float on the stack || 1 byte
|-
|20|| fcmpeq || Compares the top 2 floats on the stack to see if they are equal || 1 byte
|-
|21|| fcmpne || Compares the top 2 floats on the stack to see if they are not equal || 1 byte
|-
|22|| fcmpgt || Compares the top 2 floats on the stack to see if the first one is greater than the second one || 1 byte
|-
|23|| fcmpge || Compares the top 2 floats on the stack to see if the first one is greater than or equal to the second one || 1 byte
|-
|24|| fcmplt || Compares the top 2 floats on the stack to see if the first one is less than the second one || 1 byte
|-
|25|| fcmple || Compares the top 2 floats on the stack to see if the first one is less than or equal to the second one || 1 byte
|-
|26|| vadd || Adds the top 2 Vectors{{Ref|1}} on the stack || 1 byte
|-
|27|| vsub || Subtracts the top 2 Vectors{{Ref|1}} on the stack || 1 byte
|-
|28|| vmul || Multiplies the top 2 Vectors{{Ref|1}} on the stack || 1 byte
|-
|29|| vdiv || Divides the top 2 Vectors{{Ref|1}} on the stack || 1 byte
|-
|30|| vneg || Reverses the sign on the first vector{{Ref|1}} on the stack || 1 byte
|-
|31|| iand || Performs an [[Wikipedia:Logical_conjunction|And]] operation to the first 2 integers on the stack || 1 byte
|-
|32|| ior || Performs an [[Wikipedia:Logical_disjunction|Or]] operation to the first 2 integers on the stack || 1 byte
|-
|33|| ixor || Performs a [[Wikipedia:XOR|Xor]] operation to the first 2 integers on the stack || 1 byte
|-
|34|| jmp || Jumps to a section of code, using the next 4 bytes after the opcode as a placement || 5 bytes
|-
|35|| jmpf || Jumps to a section of code if the top of the stack is 0, using the next 4 bytes after the opcode as a placement || 5 bytes
|-
|36|| jmpt || Jumps to a section of code if the top of the stack is 1, using the next 4 bytes after the opcode as a placement || 5 bytes
|-
|37|| itof || Converts the top integer on the stack to a float, and puts that float on the stack || 1 byte
|-
|38|| ftoi || Converts the top float on the stack to an integer, and puts that integer on the stack || 1 byte
|-
|39|| ftov || Converts the top float into a Vector{{Ref|1}} containing 3 instances of the same float, and pushes the pointer to that Vector{{Ref|1}} onto the top of the stack || 1 byte
|-
|40|| ipush2 || Pushes a short onto the stack, the short is defined in the next 2 bytes after the opcode || 3 bytes
|-
|41|| ipush || Pushes an int onto the stack, the integer is defined in the next 4 bytes after the opcode || 5 bytes
|-
|42|| fpush || Pushes a float onto the stack, the float is defined in the next 4 bytes after the opcode. Performs exactly the same as Push || 5 bytes
|-
|43|| dup || Duplicates the first item on the stack, and pushes it back onto the stack || 1 byte
|-
|44|| pop || Pops the top item off the stack || 1 byte
|-
|45|| native || Calls a [[native function]]. The number of arguments for the native to take is defined in the next byte after the opcode. The number of return values is defined in the byte after that (it is always 1 or 0). The next 4 bytes are the hash of the native's name. || 7 bytes
|-
|46|| call || Calls a function within the script, and puts the return address on top of the stack. The location of the function is defined in the next 4 bytes after the opcode || 5 bytes
|-
|47|| enter || Indicates the beginning of an internal function. The byte after the opcode indicates the amount of arguments the function takes off the stack, and the next 2 bytes after that indicate the number of variables the function will have to generate on the stack. || 4 bytes
|-
|48|| ret || Indicates the end of an internal function. The byte after the opcode indicates the amount of arguments that will have to be popped off the stack, and the next byte after that indicates the stack number of the return address || 3 bytes
|-
|49|| pget || Pops a pointer off the stack and pushes the value stored in that pointer back onto the stack || 1 byte
|-
|50|| pset || Pops 2 items off the stack and stores the second item at the location of the first item (the first item being a pointer) || 1 byte
|-
|51|| ppeekset || Pops the first item off the stack and peeks at the second item on the stack, then stores the first item at the location pointed to by the second item on the stack || 1 byte
|-
|52|| explode || Pops 2 items off the stack, the first and second items being the beginning of the memory of the array and the end of the memory of the array. It then divides the difference of these 2 locations by 4 to get the number of items in the array, after which is pushes these items one by one onto the stack in 4 byte segments || 1 byte
|-
|53|| implode || Pops the first item off the stack to get the address of the array to write to, and then pops the stack off onto that array || 1 byte
|-
|54|| flvar0 || Pushes the pointer to the first function local variable onto the stack. || 1 byte
|-
|55|| flvar1 || Pushes the pointer to the second function local variable onto the stack. || 1 byte
|-
|56|| flvar2 || Pushes the pointer to the third function local variable onto the stack. || 1 byte
|-
|57|| flvar3 || Pushes the pointer to the fourth function local variable onto the stack. || 1 byte
|-
|58|| flvar4 || Pushes the pointer to the fifth function local variable onto the stack. || 1 byte
|-
|59|| flvar5 || Pushes the pointer to the sixth function local variable onto the stack. || 1 byte
|-
|60|| flvar6 || Pushes the pointer to the seventh function local variable onto the stack. || 1 byte
|-
|61|| flvar7 || Pushes the pointer to the eigth function local variable onto the stack. || 1 byte
|-
|62|| flvar || Pushes the pointer to a function local variable onto the stack where the index is above or equal to 8 || 1 byte
|-
|63|| global || Pops the index of the global variable off the stack, and pushes a pointer to the script global variable onto the stack || 1 byte
|-
|64|| public || Pops the index of the public variable off the stack, and pushes a pointer to the public variable onto the stack || 1 byte
|-
|65|| array || Pops the array location, element size and index off the stack, the pushes a pointer to the index of that array onto the stack || 1 byte
|-
|66|| switch || Pops the item to compare off the stack, and then jumps to location corresponding to that item. After the opcode byte it contains a byte defining the number of possible entries, and after that the number of possible entries times 8 are taken up with repeating instances of 4 bytes of the index identifier, and 4 bytes of the location to jump to if that index is correct || (Byte after opcode * 8) + 2
|-
|67|| spush || Pushes a string onto the stack. The byte after the opcode signals the string length, and for the amount of string length after that byte contains each character of the string || (Byte after opcode)+2
|-
|68|| null || Pushes a pointer to an empty memory container onto the stack || 1 byte
|-
|69|| scpy || Pops 2 pointers off the stack, and copies the second item to the first item || 1 byte
|-
|70|| itos || Pops an integer off the stack and pushes an array to a string representation of that integer onto the stack || 1 byte
|-
|71|| sadd || Pops 2 pointers off the stack, and appends the second item to the first item || 1 byte
|-
|72|| saddi || Pops 2 items off the stack, and performs a IntToStr on the second item (the integer), then appends that string representation to the first item || 1 byte
|-
|73|| catch || Sets up a safe area that has the ability to catch errors || 1 byte
|-
|74|| throw || Indicates an area that handles a script error relative to the catch opcode || 1 byte
|-
|75|| memcpy || Pops 3 items off the stack. Copies the third item's memory into the first item's memory with repeating defined by the second item. It then appends a null terminator to the first item's memory || 1 byte
|-
|76|| getxprotect || Pops a memory location off the stack and pushes its XLive unprotected value onto the stack (PC Only) || 1 byte
|-
|77|| setxprotect || Pops a memory location off the stack, pops another value off the stack. Protects the second value using XLive and stores the value in the memory location. (PC Only) || 1 byte
|-
|78|| refxprotect || Pops a memory location off the stack, pops another value off the stack to determine protection flags, and finally pops another value which indicates the number of items to operate on. If the 1st bit of the flags is set, the number of items at the memory location will be XLive unprotected. If the 2nd bit is set, they will be XLive protected instead. (PC Only) || 1 byte
|-
|79|| exit || Terminates the script under an error condition || 1 byte
|-
|80 -> 255|| ipush1 || Pushes an integer onto the stack. The integer is defined by the opcode number - 96. For example opcode 95 would push -1 onto the stack, and opcode 97 would push 1 || 1 byte
|}

{{note|1}} The Vectors on the stack are pointers to the memory containing the full vector. A Vector is characterised by this structure:

4b - FLOAT32 - X
4b - FLOAT32 - Y
4b - FLOAT32 - Z

===Global Variables===
This contains the Global Variables in the script. Each global variable is 4 bytes long, and can contain static information in the script file itself.

===Public Variables===
It is uncertain what this section actually does.

==High Level Representation==
To turn the assembly of a SCO file into a high level representation some factors have to be considered. Arrays and structures can be defined, so it is reasonable to assume there is some kind of typecasting, even if it is only between the following types; [[Wikipedia:Integer_(computer_science)|int]], [[Wikipedia:Floating_point|float]], [[Wikipedia:String_(computer_science)|string]] or a predefined structure. It is interesting to note that opcodes exist to typecast integers and concatenate them directly to strings, this suggests the SCO language has a java like way of handling strings (using + and += for concatenation). The SCO file does not seem to have native support for the notion of classes, however this is not to say they could not be implemented within SCO itself similar to how they are done at a low level in C++.

== Tools ==
* {{GTAF|396486|Scone}} – SCO (Dis-)assembler by {{U|Sacky}}
* [[OpenIV]] – contains a built-in decompiler
* [[SparkIV]] – contains a built-in decompiler

== See also ==
* [[Mission Scripting (Overview)]] – introduction to mission scripting in the previous games

{{GTA4-navi}}
[[Category:Mission Script]][[Category:File Formats]]{{fdl}}