Create a Script
This tutorial will show you the basic steps on how to create a simple script in the
main.scm using the latest version of Sanny Builder. This tutorial applies to Grand Theft Auto III, Grand Theft Auto: Vice City, and Grand Theft Auto: San Andreas.
Start your script
Prior to the advent of CLEO, this section was one of the first steps in understanding how to create scripts. First make sure you are working with a decompiled
main.scm file. If you don't have a decompiled file, go to Sanny Builder and press F5. Find and open the
main.scm file for decompiling. The program will create the
main.txt file in the same directory. That is the file you will be working with. Now we need a command to start your first script by using opcode 004F (or create_thread command). Find:
Insert before it:
004F: create_thread @simple_script
simple_script is an arbitrary but unique name for a label. It helps the game locate your script.
Create your script
Next create your script by inserting it in the appropriate place. Find:
That is where the MAIN section ends and the first mission begins. Insert your script between it. The simplest scripts have this format:
:simple_script // Insert your code here 004E: end_thread
Your script can include a series of opcodes like adding cash to you or setting your wanted level:
:simple_script 0109: player $PLAYER_CHAR money += 1000 010D: set_player $PLAYER_CHAR wanted_level_to 6 004E: end_thread
More complex code can be placed there instead, including spawning a ped, creating a clothes pickup, or creating a moving gate.
Your script can have an optional name with which the game can identify by using opcode 03A4. A maximum of 7 characters are allowed for the name. If needed, through different scripts you can end your script with opcode 0459.
:simple_script 03A4: name_thread 'SCRIPTA' :simple_script_start // Insert your code here 004E: end_thread
The example above shows you a script that ends immediately. If you want your script to run continuously, you have insert a loop. For most cases, looping requires opcode 0001 (or wait command) to be placed somewhere within the loop or else the game will crash. There are exceptions but it is safer to have it. The simplest loop has this format:
:simple_script while true 0001: wait 0 ms // Insert your code here end
This script will repeat itself indefinitely so be careful what you put in it. In older or decompiled scripts, you may see this format:
:simple_script 0001: wait 0 ms // Insert your code here 0002: jump @simple_script
This style is lower level and behaves equivalently to the prior example script.
Conditional opcodes are used to check whether the action is performed rather than to perform the action. If the condition is satisfied, it returns true, otherwise it returns false. In Sanny Builder, conditional opcodes are noted by spaces between the opcode and the description of the opcode. Conditions start with IF statements that checks if an action is performed.
:simple_script while true 0001: wait 100 ms if // Conditional opcode, e.g. 00E1: player 0 pressed_key 13 then // Command if the condition returns true, e.g. if the key is being pressed, then add $2000 0109: player $PLAYER_CHAR money += 2000 else // Command if the condition returns false, e.g. if the key is not being pressed, then subtract $10 0109: player $PLAYER_CHAR money += -10 end end
In older or decompiled scripts, you may see this format:
:simple_script 0001: wait 100 ms 00D6: if // Conditional opcode, e.g. 00E1: player 0 pressed_key 13 004D: jump_if_false @simple_script_check_failed // Command, if the condition returns true, e.g. if the key is being pressed, then add $2000 0109: player $PLAYER_CHAR money += 2000 0002: jump @simple_script_end :simple_script_check_failed // Command, if the condition returns false, e.g. if the key is not being pressed, then subtract $10 0109: player $PLAYER_CHAR money += -10 :simple_script_end 0002: jump @simple_script
Again, this style is lower level and behaves equivalently to the prior example script. Both of the examples above show if one condition is met (the CAMERA key is pressed), the condition is true and the first command will be performed (add $2000). Otherwise, the condition would be false and reaches the alternate command (subtract $10). For IF statements with more than one conditions, you need to either add and or or after if.
if and means if all of the conditions are met, then perform the command.
// ... if and 00E1: player 0 pressed_key 4 // first condition 00E1: player 0 pressed_key 19 // second condition then // command end // ...
This shows that if all conditions (if both keys 4 and 19 are pressed in this example) are met, the command will be performed. Otherwise, the code will skip the command and continue onwards.
if or means if any one of these conditions are met, then perform the command.
// ... if or 00E1: player 0 pressed_key 4 // first condition 00E1: player 0 pressed_key 19 // second condition then // command end // ...
This shows that if either condition (if either key 4 or key 19 is pressed in this example) is met, the command will be performed. Otherwise, the code will skip the command and continue onwards.
Opcodes normally starts with the number 0, but conditional opcodes can start with the number 8. This checks if the condition is not performed.
00E1: player 0 pressed_key 4 // IS pressed 80E1: not player 0 pressed_key 4 // is NOT pressed
Save your changes
Finally, after you have finished all the necessary changes, you have to compile the file you are working on by pressing F6. The compilation is successful when a "Report" dialog box pops up and your
main.scm file is successfully modified. In order to play the game with the modification, you must start a new game or else the game can crash. Check out the Tutorial Forum for more in-depth tutorials or the Mission Coding Forum for further help on coding.