GTA SA Main.scm coding Tutorial / english


startup for newbies

add code to stripped main

add a script to originally main


Structure of main.scm


    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
    ------------------------------------------------------------------ 
    
    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"


    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
    the last External_Script ends at the end of the Main.scm source text


     

    next lesson >> V. Structure of main.scm