San Andreas getting started in scripting(part 1)

I have been meaning to do a tut in English, as I know that many of know only speak that language , now this will explain things, for information on things please browse our mission coding forum. Anyway the point of this is to help, when you first get into mission coding, everything is going to be very hard, even if the task is generally easy.

Getting started, the tools you need to get started are the following Sanny Builder this is the best tool for compiling the scripts you make. Additionally there exist other tools such as Point, or Barton Water duck's Mission Builder, however none of these tools are as effective as Sanny Builder, if you choose to download one of these other than Sanny Builder that is your choice. However this tut actually does apply to Sanny Builder more.


Now this tool is generally for decompiling the main.scm file, the main.scm file is a binary type file, that contains most of the games script. If you open this file with a hexadecimal editor(e.g. Hex Workshop, Flex HEX, and Hex editor Neo), it will look something like the following:



When you downloaded Sanny Builder do not expect everything done for you, remember YOU are the programmer(scripter), Sanny Builder is your girlfriend , (if your a female, I'm not trying to call you a gay, I'm just assuming your a male), install Sanny Builder, follow the intrustions she gives you, once installed, open a new page in Sanny Builder copy-&-paste this small script for your first experience:

Code:


{$CLEO}
0000:

while true
wait 250
if
  0256:  player $PLAYER_CHAR defined
then
    if
      00E1:  key_pressed  0  17
  then
      00BA: text_styled 'FEM_OK'  1000 ms  style 1
    break
        end
    end
end
0A93: end_custom_thread


In the top of Sanny Builder there is a option which says "Run"(if you have your Sanny Builder in a different language for example in German "Run" is "Start" in Russian for example "Зеофсл"), anyway click on this and click "Compile" there is a screen(my Sanny Builder is in Russian language) :



F5 = De-compile a file
F6 = Compile
F7 = Compile & Copy
F8 = Run GTA: San Andreas

After you have did this you will see something like that(of course that the design of Sanny Builder is based up-on Windows Version):



The file becomes a CS file, now what you choose to do with this file now is up to you generally, you may delete it.


Download ZAZ's CLEO 3 basics from there And read the ReadMe file
{$CLEO .cs} = The CLEO script detective, and {$CLEO} also means the same, where as {$CLEO .cm} stands for a CLEO mission.

If you press # while in Sanny Builder a list of models name will appear, now obviously not all model are on this, only defined ones, as of Sanny Builder v3.04 Sanny Builder has the feature to convert model names to there ID and vise versa. Use the Ctrl+Alt+H feature to convert a model name to ID and vice versa.




A beginner in mission coding should start with the most easiest thing possible for example a car spawn script, thus, the user can learn, a beginner should never try to make a mission, experience comes slowly, if you are jump to a head of your limits your going to feel way out of your league,

A simple car spawn script:

Code:


{$CLEO}
0000:
0A95: enable_thread_saving
014B: 0@ = init_parked_car_generator #INFERNUS -1 -1  1 alarm  0 door_lock  0  0  10000 at  x y z angle 180.0
014C: set_parked_car_generator 0@ cars_to_generate_to  101
0A17: set_parked_car_generator 0@ to_player_owned 1
0A93: end_custom_thread


XYZ are the co-ordinates of where the vehicle is placed, and angle is the Z angle of the vehicle. 014C is needed to tell the vehicle to generate 0 means do not, and 101 means the vehicle can spawn, 0A17 sets the vehicle owned to the player, so if a cop sees you enter it you will not get a wanted star, 0A93 ends the thread, the thread is read once, because it is not in a loop, it is not necessary for it to be in one, as this will keep spawning that vehicle over and over again. (Note: If you save, this vehicle will always be present in the that save game file because of opcode 0A95). To get co-ordinates you can right click on your mouse on Sanny Builder and go to player coords(or CTRL+SHIFT+C, for player coords insert) (CTRL+SHIFT+E for the players angle). (Ctrl = Strg on a German keyboard).







Sanny Builder has built in tools go to tools in Sanny Builder menu



Going to "ID tools" in the "Tools" menu there is two options "Player Coords and angle" or "Opcode Search Tool"



To search for a opcode type something like if your search for a car opcode type "car", in the co-ordinates manger, you get the co-ordinates of your player, stand in a place of the game and go to this to get the players coords, you can also get insert the players coords and angle by clicking right mouse button, then select "Insert" then "Player Coords" (or CTRL+SHIFT+C, for player coords insert).

In the options menu also exist "code converter", "make opcodes text" "Add macro" and "Options", in the "Options" here you can select/change a lot of options. The "Options" menu has 4 tabs, "general", "Formats", "Editor", and "Highlighter", the "general" tab has options such as select different languages such as Russian, German, English, and more.



Selecting the language:



Now my Sanny Builder is in Russian:






0A93: end_custom_thread lets a CLEO script end.
The original version of this code of the main.scm is 004E: end_thread



This same opcode must be used when ending a CLEO mission script.

Code:


004E: end_thread


Again:

0A93: end_custom_thread should be used in normal CLEO scripts to end the thread:

Code:


{$CLEO .cs}
// ....script
0A93: end_custom_thread


004E: end_thread in s CLEO mission script:

Code:


{$CLEO .cm}
/ ....mission
004E: end_thread


004F: create_thread @Label(or create_thread @Label)starts an ordinary thread in the main.scm, in CLEO scripts/missions, we do not use this - there is no need. Scripts with the extension(*.cs) are loaded when the game starts, in addition we can make a file with extension(*.s), this is not loaded, when the game starts, and you can start the script through a normal CLEO script/mission:

Code:


0A92: create_custom_thread "ThreadName.s"


Read more about this opcode in Sanny Builder -> Help -> CLEO 3: opcodes
(ThreadName will be the name of the file your starting with the extension(*.s)).

In CLEO scripts, to start missions we create a normal script, and start the *.cm(Custom Mission) file through this script:

Code:


0A94: start_custom_mission "MyMission"


So this would start a mission file with the name "MyMission.cm" note; that the file extension is not needed to specify, this opcode was made to search for a file with the extension (*.cm)

Code:


0417: start_mission 4


This starts a mission script of the main.scm. This opcode can also be used in a CLEO script, to start a mission of the main.scm



CLEO scripts with the extension *.cs are loaded when the game has been started. If the script has a parked car generator, and if you save your game the vehicle will be copied. This happens with the parked car generators, pickups, and script placed objects.

To prevent you need to use this opcode in that CLEO script:

Code:


0A95: enable_thread_saving


To understand this you need to understand normal global and local variables,
using global variables in CLEO scripts can cause bugs or/and crashes, Seemann made such opcodes to help with this problem. Opcode 0AB3 and 0AB4 accordingly, var 0 up to var 999 can be stored.

Code:


0AB4: 1@ = var 15
0AB3: var 0 = 1@


For beginners only simple struct should be used use 0A93: end_custom_thread in CLEO script to end the thread(in main.scm use 004E: end_thread to make the code be read more than once and be in a loop jump and re-loop it, a wait is needed if the code is within a running loop.

Code within a loop:

Code:


{$CLEO}
0000:

:Example
0001: wait 250 ms // -- this is needed at the code is within a loop
00d6: if
0256: player $PLAYER_CHAR defined
004d: jump_if_false @Example
00d6: if
0ab0:  key_pressed 8
004d: jump_if_false @Example
08b2: toggle_thermal_vision 1

:Example_02
0001: wait 0 ms // --
00d6: if
0256: player $PLAYER_CHAR defined
004d: jump_if_false @Example_02
00d6: if
0ab0:  key_pressed 8
004d: jump_if_false @Example_02
08b2: toggle_thermal_vision 0
0002: jump @Akt_01 // retrun to restart the script


Code:


0256:  player $PLAYER_CHAR defined


This is needed most of the time, usually it will not be needed if the code does not have the player in it, or does not check to check if defined - this opcode is used as a condition and if it's false, it means the player has been wasted or busted.



In the latest version of Sanny Builder, it has the option to convert
hexadecimal numbers to decimal ones and vice versa (Ctrl+H).



@ (at sign)is a common data type, this sign is used for two things:

1: In jump instruction to tell the script where what label to go to. These opcodes:

Code:


0002: jump @Label
0050: gosub @Label
004D: jump_if_false @Label


2: The local varible sign
The local variables are made with a number, and then the @ sign

In ranges 0@...31@ is possible in normal threads, 32@ and 33@ are for timers. In mission scripts you use local variables in ranges 0@...1023@


$ (dollar sign) is common data type, and is used to mark the global variables.

The global variables are made with numbers, words, and etc, and then the $ sign. As has been said, using global variables in CLEO scripts can cause stupid bugs bugs or/and crashes.
Some global variables such as $PLAYER_CHAR, $PLAYER_ACTOR, $ONMISSION are valid, and ones in the Customvariables.ini. global variables nubmers DO have a limit, to this limit is: 16383

# Marks a model name of a model:

Code:


0247: load_model #INFERNUS


In CLEO scripts models which are defined in vehicles.ide, peds.ide or default.ide can only be used. For the others use there ID, you can display a list by typing # in Sanny Builder, in the main.scm the list will also contain the models which have been defined at the beginning of the main.scm.

'...'

Short strings, like the GXT entry's:

Code:


07FB: set_interior 'GYM1' access 1  // Ganton Gym


"..."

Long string to insert body part names, particle names, IFP files, texture names, etc:

Code:


087B: set_player $PLAYER_CHAR clothes_texture "PLAYER_FACE" model "HEAD" body_part 1


@s - This repents a local short sting varible, it can be used like this:

Code:


05AA: 0@s = 'ENTRY'
00BC: show_text_highpriority GXT 0@s time 5000 flag 1


@v This repents a local long sting varible, it can be used like this:

Code:


06D2: 0@v = "IFPFILE" // @v = string
0812: AS_actor $PLAYER_ACTOR perform_animation "Name" IFP_file 0@v 1000.0 loopA 0 lockX 0 lockY 0 lockF 1 time -1


s$ - This repents a global short sting varible, it can be used like this:

Code:


05A9: s$_GXT_Reference = 'GXT' 
00BC: show_text_highpriority GXT s$_GXT_Reference time 5000 flag 1


sv - This repents a global long sting varible, it can be used like this:

Code:


06D1: v$1200 = "Bat_block"// 16-byte strings                   
0605: actor $PLAYER_ACTOR perform_animation_sequence v$1200 from_file "BASEBALL"  4.0  1  0  0  0 -1 ms


...more to come...

Keywords are a simple command in which can replace a opcode for a shorter one, but has the same meaning:

Code:


0002: = jump
00d6: = if
004d: = jf
004d: = else_jump
0051: = return
0050: = gosub
016a: = fade
01B6: = set_weather
03a4: = thread
04BB: = select_interior
0417: = start_mission
00d8: = mission_cleanup
0317: = increment_mission_attempts


As an example we would write jf instead:

Code:


jf @Label // -- opcode 004d
else_jump @Label // -- opcode 004d

004d: jump_if_flase @Label


The if condition checks if something is true or false it goes < if > the conditional opcode:

Code:


00d6: if
// something
004d: jump_if_false @Label2
//..............

:Label2
//..............


If the script uses more than one condition then use if and/ if or if and means BOTH of the conditions are true or false, where as if or would means if EITHER one of the conditions are true or false:

Code:


if and
00E1: key_pressed 0 14
00E1: key_pressed 0 18
004D: jump_if_false @NextLabel
//...continues here if BOTH are pressed


In this case it would mean BOTH of these keys are pressed, where as this would mean if either one:

Code:


if or
00E1: key_pressed 0 14
00E1: key_pressed 0 18
004D: jump_if_false @NextLabel
//...continues here if EITHER are pressed


Most of the question conditional opcodes can be changed to opposite by replacing the first digit(0) to 8 of the opcode, like this:

Code:


80E1: not key_pressed 0 14


The "NOT" does not actually make a difference, only the 8 is needed, to change the opcode opposite, but NOT is put there so it helps the reader of the code to understand it better, if your using a class keyword then you would need to just put NOT before the conditional opcode, like this:

Code:


NOT Actor.Driving ($PLAYER_ACTOR)


- To spawn there is only a couple of steps to follow:

1: Load the model's model - you can use the model name, ID, or hexadecimal ID:

Code:


0247: load_model #BULLET


2: You should ALWAYS check if the model is available, to prove to the game engine that is is really loaded, and available to use, so it can continue safely:

Code:


:Check
0001: wait  0 ms
00d6: if 
0248:  model #BULLET available
004d: jump_if_false @Check


3: Create the model like this:

Code:


00A5: 0@ = create_car #BULLET at 1@ 2@ 3@


4: If you do not need the model anymore then you can release it right-away after you spawned it:

Code:


0249: release_model #BULLET


5: If you want to just turn in to a normal thing you can remove it's reference with this( this means it's still available for us, but not for the script, anymore):

Code:


01C3: remove_references_to_car 0@  // Like turning a car into any random car


Example CLEO script, press the "~Conversation No~" key to spawn a Bullet before the player:

Code:


{$CLEO}
0000:

:script_01
0001: wait 250
00d6: if
0256: player $PLAYER_CHAR defined
004d: jump_if_false @script_01
00d6: if
00E1:  player 0 pressed_key 10
004d: jump_if_false @script_01
0247: load_model #BULLET
038B: load_requested_models

:script_02
00d6: if
8248:  not model #BULLET available
004d: jump_if_false @script_03
0001: wait 0 ms
0002: jump @script_02

:script_03
04C4: store_coords_to 0@ 1@ 2@ from_actor $PLAYER_ACTOR with_offset 0.0 4.0
1.4
0395: clear_area 1 at 0@ 1@ 2@ radius 5.0
00A5: 3@ = create_car #BULLET at 0@ 1@ 2@
0249: release_model #BULLET
01C3: remove_references_to_car 3@  // Like turning a car into any random car
0001: wait 1500
0002: jump @script_01


An example to spawn a actor(press the "~Conversation Yes~" key:

Code:


{$CLEO}
0000:

:script_01
0001: wait 250
00d6: if
0256: player $PLAYER_CHAR defined
004d: jump_if_false @script_01
00d6: if
0038:  $ONMISSION == 0
004D: jump_if_false @script_01
00d6: if
00E1:  player 0 pressed_key 11
004d: jump_if_false @script_01
00A0: store_actor $PLAYER_ACTOR position_to 0@ 1@ 2@
0247: load_model #BIKDRUG
038B: load_requested_models

:script_02
00d6: if
8248:  not model #BIKDRUG available
004d: jump_if_false @script_03
0001: wait 0 ms
0002: jump @script_02

:script_03
009A: 3@ = create_actor_pedtype 4 model #BIKDRUG  at 0@ 1@ 2@
0173: set_actor 3@ Z_angle_to 180.0
0223: set_actor 3@ health_to 2000
0446: set_actor 3@ immune_to_headshots 0
04D8: set_actor 3@ drowns_in_water 0
03FE: set_actor 3@ money 500000
0946: set_actor 3@ actions_uninterupted_by_weapon_fire 0
060B: set_actor 3@ decision_maker_to 32
05E2: AS_actor 3@ kill_actor $PLAYER_ACTOR
0249: release_model #BIKDRUG

:script_04
0001: wait  0 ms
00D6: if 
0256:  player $PLAYER_CHAR defined 
004D: jump_if_false @script_05
00D6: if 
8118:  not actor 3@ dead
004D: jump_if_false @script_05
00D6: if
00FE:    actor 3@ sphere 0 in_sphere 0@ 1@ 2@ radius 380.0 400.0 400.0
004D: jump_if_false @script_06
0002: jump @script_04 // -- loop back to the main checks

:script_05
01C2: remove_references_to_actor 3@ // Like turning an actor into a random pedestrian
0002: jump @script_01 // -- back to start of the script

:script_06
034F: destroy_actor_with_fade 3@ // -- back to start of the script
0002: jump @script_01