SCO

SCO files contain GTA 4's game scripts. Its new format replaces old scm one.

File Format

A SCO file is layed out into 4 segments. First the Header containing information about the SCO file. Then the Code Segment which contains the opcode's which govern how the script behaves. The next segment is the Local Variable container which contains enough space to hold the local variables. The last is the Global Variable container, which contains enough space to house the global variables, as well as setting them by default.

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 - Local Var Size
4b - UINT32 - Global Var Size
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. The Code Size refers to the amount of bytes the code section takes up. The Local Var Size refers to the amount of local variables the SCO file contains. The segment for local variables starts at the end of Header + Code Size, and continues for 4x the local variable size (due to the local variables being stored in 4 byte segments). The Global Var Size refers to the amount of global variables the SCO file contains. The segment for global variables starts at the end of Header + Code Size + Local Var Size * 4, and continues for 4x the global variable size (due to the global variables being stored in 4 byte segments). 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 80 opcodes which can occur, any opcode above 80 is a Push opcode which pushes it's own number - 96 onto the stack.

ID	Name	Description	Length
0	Nop	No operation	1 byte
1	Add	Adds the top 2 items on the stack	1 byte
2	Sub	Subtracts the top 2 items on the stack	1 byte
3	Mul	Multiplies the top 2 items on the stack	1 byte
4	Div	Divides the top 2 items on the stack	1 byte
5	Mod	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	Neg	Reverses the sign on the item on the top of the stack	1 byte
8	CmpEq	Compares the top 2 integers on the stack to see if they are equal	1 byte
9	CmpNe	Compares the top 2 integers on the stack to see if they are not equal	1 byte
10	CmpGt	Compares the top 2 integers on the stack to see if the first one is greater than the second one	1 byte
11	CmpGe	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	CmpLt	Compares the top 2 integers on the stack to see if the first one is less than the second one	1 byte
13	CmpLe	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	AddF	Adds the top 2 floats on the stack	1 byte
15	SubF	Subtracts the top 2 floats on the stack	1 byte
16	MulF	Multiplies the top 2 floats on the stack	1 byte
17	DivF	Divides the top 2 floats on the stack	1 byte
18	ModF	Mods the top 2 floats on the stack	1 byte
19	NegF	Reverses the sign on the first float on the stack	1 byte
20	CmpEqF	Compares the top 2 floats on the stack to see if they are equal	1 byte
21	CmpNeF	Compares the top 2 floats on the stack to see if they are not equal	1 byte
22	CmpGtF	Compares the top 2 floats on the stack to see if the first one is greater than the second one	1 byte
23	CmpGeF	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	CmpLtF	Compares the top 2 floats on the stack to see if the first one is less than the second one	1 byte
25	CmpLeF	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	AddVec	Adds the top 2 Vectors[1] on the stack	1 byte
27	SubVec	Subtracts the top 2 Vectors on the stack	1 byte
28	MulVec	Multiplies the top 2 Vectors on the stack	1 byte
29	DivVec	Divides the top 2 Vectors on the stack	1 byte
30	NegVec	Reverses the sign on the first vector on the stack	1 byte
31	And	Performs an And operation to the first 2 integers on the stack	1 byte
32	Or	Performs an Or operation to the first 2 integers on the stack	1 byte
33	Xor	Performs a Xor operation to the first 2 integers on the stack	1 byte
34	Jump	Jumps to a section of code, using the next 4 bytes after the opcode as a placement	5 bytes
35	JumpFalse	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	JumpTrue	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	ToF	Converts the top integer on the stack to a float, and puts that float on the stack	1 byte
38	FromF	Converts the top float on the stack to an integer, and puts that integer on the stack	1 byte
39	VecFromF	Converts the top float into a Vector containing 3 instances of the same float, and pushes the pointer to that Vector onto the top of the stack	1 byte
40	PushS	Pushes a short onto the stack, the short is defined in the next 2 bytes after the opcode	3 bytes
41	Push	Pushes an int onto the stack, the integer is defined in the next 4 bytes after the opcode	5 bytes
42	PushF	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	CallNative	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	FnBegin	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	FnEnd	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	RefGet	Pops a pointer off the stack and pushes the value stored in that pointer back onto the stack	1 byte
50	RefSet	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	RefPeekSet	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	ArrayExplode	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	ArrayImplode	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 -> 61	LocalVarPtr	Pushes the pointer to a local variable onto the stack	1 byte
62	LocalVarPtrEx	Pushes the pointer to a local variable onto the stack where the index is above or equal to 8	1 byte
63	LocalVar	Pops the index of the local variable off the stack, and pushes a pointer to a script local variable onto the stack	1 byte
64	GlobalVar	Pops the index of the global variable off the stack, and pushes a pointer to a script global variable onto the stack	1 byte
65	ArrayRef	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	PushString	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	NullObj	Pushes a pointer to an empty memory container onto the stack	1 byte
69	StrCpy	Pops 2 pointers off the stack, and copies the second item to the first item	1 byte
70	IntToStr	Pops an integer off the stack and pushes an array to a string representation of that integer onto the stack	1 byte
71	StrCat	Pops 2 pointers off the stack, and appends the second item to the first item	1 byte
72	StrCatI	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	StrVarCpy	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	GetProtect	Pops a memory location off the stack and pushes its protection details onto the stack	1 byte
77	SetProtect	Pops a memory location off the stack as well as its protection details and sets the memory locations new protect details	1 byte
78	RefProtect	?	1 byte
79	Abort	Aborts the script	1 byte

^ The Vectors on the stack are pointers to the memory containing the full vector.