GTA SA Main.scm coding Tutorial / english

Structure of main.scm

Index of the Lessons

startup for newbies

V. Structure of main.scm

subdivide the decompiled main.scm and script.img in to 8 segments
the game engine reads the script downwards from beginning at the top and so as first the First 5 segments
and then the Main Thread of 6. segment, the MAINPART
Scripts of 7. segment, the MISSION PART and 8. segment, the EXTERN SCRIPT PART are called by demand

First 5 segments:

OBJECT TABLE, MISSION TABLE, EXTERNAL_SCRIPT table, UNKNOWN_EMPTY_SEGMENT, UNKNOWN_THREADS_MEMORY

1.) OBJECT TABLE

DEFINE OBJECTS 3                   // max. amount of defined OBJECTS
DEFINE OBJECT (dummyobject)        // Object 0 is always unused. You can put anything here.
DEFINE OBJECT KEYCARD                 // Object number -1
DEFINE OBJECT A51_JETDOOR              // Object number -2

Objectlist to can use objects by modelname e.g. A51_JETDOOR:
0107: $2670 = create_object #A51_JETDOOR at 268.664 1884.06 15.925
also possible to use the count number of Objectlist e.g. A51_JETDOOR:
0107: $2670 = create_object -2 at 268.664 1884.06 15.925
----------------------------------------------------------------

2.) MISSION TABLE

DEFINE MISSIONS 3                      // max. amount of defined MISSIONS
DEFINE MISSION 0 AT @INITIAL           // Initial 1
DEFINE MISSION 1 AT @INITIL2           // Initial 2
DEFINE MISSION 2 AT @INTRO             // Intro; originally Intromission

these first 3 missions of originally  main.scm start immediately at gamestart
----------------------------------------------------------------

3.) EXTERNAL_SCRIPT table

DEFINE EXTERNAL_SCRIPTS 1                   // max. amount of defined EXTERNAL_SCRIPTS
DEFINE SCRIPT PLAYER_PARACHUTE AT @PLCHUTE  // 0 Player_parachute

------------------------------------------------------------------

4.) a unknown or unused segment (don't change anything)

DEFINE UNKNOWN_EMPTY_SEGMENT  0
------------------------------------------------------------------
5.) a unknown or unused segment (don't change anything)

DEFINE UNKNOWN_THREADS_MEMORY  0
------------------------------------------------------------------

-1

out

6.) MAINPART

MAINPART means: main thread and other normal threads, executed by 004F: create_thread

main thread (main script) at gamestart is the first thread of the MAINPART and will be initialized automaticly
then the reading process runs through the main thread, the source script to create the player-actor in the gameworld and to start all other scripts
Main Thread and MAINPART beginns here:

//-------------MAIN---------------

:MAIN_1
03A4: name_thread 'MAIN'
016A: fade  0 (in)  0 ms

04E4: unknown_refresh_game_renderer_at  2494.5 -1668.5
03CB: set_camera  2494.5 -1668.5 13.4
0053: $PLAYER_CHAR = create_player #NULL at  2494.5 -1668.5 13.4
01F5: $PLAYER_ACTOR = create_emulated_actor_from_player $PLAYER_CHAR
0180: set_on_mission_flag_to $ONMISSION // Note: your missions have to use the variable defined here
004F: create_thread @HOTR

"create_thread" starts a thread (script) that's placed in the MAINPART

a part of the threads of originally main.scm are initialized in the main thread directly by create_thread

other threads which are placed in the MAINPART are initialized indirectly
indirectly means to start a thread which starts also another thread

for example the Intro mission of originally main.scm starts the thread of the mobil phone for storyline

004F: create_thread @MOB_LA1

to start this thread which is also placed in the MAINPART:

:MOB_LA1
0111: set_wasted_busted_check 0
03A4: name_thread 'MOB_LA1'
....
..

"start_mission" starts a mission script in mission mode which is placed in the MISSION PART

The startcodes for the first 2 mission scripts of originally main.scm are placed in the main thread.
These missions are used in originally main.scm to setup a lot of parked cars, objects and predefined values
imediately at gamestart

0417: start_mission 0  // Initial 1
0001: wait 0 ms
0417: start_mission 1  // Initial 2

a mission script in mission mode means that you have to use some special methods
very important is to have this line in the main thread


0180: set_on_mission_flag_to $ONMISSION

Other start_mission codes are placed in Mission Starter Threads, "mission sniffer"
For Example the "Sweet mission sniffer" of originally main.scm


:SWEET
03A4: name_thread 'SWEET'
...
..
.
00D6: if
0038:   $SWEET_TOTAL_PASSED_MISSIONS == 0
004D: jump_if_false @SWEET_180
0004: $ONMISSION = 1
00BA: show_text_styled GXT 'SWEET_1' time 1000 style 2  // Lighthouse Mutants
0417: start_mission 13  // Tagging Up Turf

"run_external_script" starts an external_script which is placed in the EXTERN SCRIPT PART


0913: run_external_script 66 (CARMOD1)

it needs first to load and check if the script is loaded
08A9: load_external_script 66 (CARMOD1)
00D6: if
08AB:   external_script 66 (CARMOD1) loaded
004D: jump_if_false @MAIN_4329
0913: run_external_script 66 (CARMOD1)

Some startcodes for Extern Scripts of originally main.scm like CARMOD1 are placed in the main thread
Other startcodes for Extern Scripts are placed in other threads or mission scripts as well in extern scripts

Ok, summery about MAINPART (6):
It contains the main thread and other normal threads.
The MAINPART ends where the MISSION PART beginns
These are the last lines of MAINPART of originally main.scm


:MOB_GF_3609
00BE: text_clear_all 
return

End of MAINPART Here can you place your modscript which is mostly just a normal thread
Below of the last thread of MAINPART
Above of the first mission script

Note:
The amount of data of MAINPART is limited to 200 000 byte

6.) MISSION PART

Here are the mission scripts placed, which must be defined in the MISSION TABLE
The MISSIONPART beginns where the MAINPART ends, at:


//-------------Mission 0---------------
// Originally: Initial 1

:INITIAL
03A4: name_thread 'INITIAL'

This mission is used in originally main.scm to setup a lot of parked cars, objects and predefined values



//-------------Mission 1---------------
// Originally: Initial 2

:INITIL2
03A4: name_thread 'INITIL2'
0004: $3407 = 25

This mission is used in originally main.scm to setup a lot of parked cars, objects and predefined values


//-------------Mission 2---------------
// Originally: Intro

This is the the originally Intromission where CJ arrived at Airport in originally main.scm

:INTRO
03A4: name_thread 'INTRO'
0050: gosub @INTRO_47
00D6: if
0112:   wasted_or_busted // mission only
004D: jump_if_false @INTRO_38
0050: gosub @INTRO_9994

:INTRO_38
0050: gosub @INTRO_9996
004E: end_thread

:INTRO_47
0004: $ONMISSION = 1

Mission scripts are running mostly in a special mode and writen therefor by a special method
they can use much more local vars and have more capcity for creating and managing more stuff than normal threads

Integration requires to insert the script label to the MISSION TABLE
Mission scripts must be placed in same order as they're listed in the Mission Table

also does it need to declare the mission mode indicator, by placing this code into Main Thread

0180: set_on_mission_flag_to $ONMISSION// Note: your missions have to use the variable defined here

The initializing requires the mission start code, can only be placed in the MAINPART

0417: start_mission 0

8. External Script part

Externscripts will be compiled to seperately script files and archived in script.img
The (un)modified source script of originally main will be compiled to main.scm and script.img

Important: It needs always to run main.scm and script.img of same compiling result

Changing script.img needs to quit the game
For testing is it possible to keep the script.img and update the main.scm without quitting the game, but if you test then external scripts like Basketball or Dance, will the game crash

Integration requires to insert the script label to the EXTERN SCRIPT TABLE
By using a stripped main without Extern Scripts should you set the entry for amount of Defined External_Scripts to -1, because
by decompiling of a modded main.scm without externscript becomes this entry 0 and compiling such a main with 0 let the compiler create a script.img with the empty dummyscript "AAA"

The first Externscript of the originally script.img is the player_parachute script

//-------------External script 0 (PLAYER_PARACHUTE)---------------

:PLCHUTE
03A4: name_thread 'PLCHUTE'
0247: load_model #GUN_PARA

:PLCHUTE_16
00D6: if
8248:   not model #GUN_PARA available
004D: jump_if_false @PLCHUTE_43
0001: wait 0 ms
0002: jump @PLCHUTE_16

next lesson >> V. Structure of main.scm

GTA SAN ANDREAS

MODS for