Skip to content

Instantly share code, notes, and snippets.

@thelink2012

thelink2012/0000-gta3script-cleo4.md

Last active December 17, 2016 21:13
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save thelink2012/25626c1d7ad052721f91f0b572a8a45f to your computer and use it in GitHub Desktop.
Save thelink2012/25626c1d7ad052721f91f0b572a8a45f to your computer and use it in GitHub Desktop.
Download ZIP
Raw
0000-gta3script-cleo4.md
  • Feature Name: gta3script-cleo4
  • Start Date: 11/11/2016

Summary

Proposal to define CLEO4 commands and semantics for the so called GTA3script language.

Detailed design

Entity types

The following entity types are defined by CLEO:

  • AUDIO_STREAM
  • DYNAMIC_LIBRARY
  • FILE
  • FILE_FIND

Procedures

CLEO has the means of calling procedures with the command 2737 and returning from them with 2738. The Stories chapters also have a similar, but not exactly the same, means of calling procedures. As such, GTA3script semantics to function calling can be defined.

To avoid conflicts with the Stories command, which differ a bit from CLEOs, the commands will be defined as CLEO_CALL and CLEO_RETURN.

The semantics of those procedures are defined as follow:

  • The first CLEO_CALL into a label defines its scope as a procedure, as well as its number of input values and types.
  • At such first call, the first CLEO_RETURN of the procedure must be known to determine the amount of output values.
    • This does not mean the procedure label should appear before the call happens.
  • The target label of a CLEO_CALL shall be within a scope.
  • The procedure shall have at least one CLEO_RETURN.
  • Every CLEO_CALL to a procedure shall send and receive the same amount of values, with the same types and same entity types.
  • Every CLEO_RETURN in a procedure shall return the same amount of values, with the same types and same entity types.
  • The input values of a CLEO_CALL may have the types INT, FLOAT and STRING.
    • Whenever the input type is STRING, the target scope should have a INT variable to accommodate a pointer to the string.
  • CLEO_RETURN may only return PARAM values i.e. INT and FLOAT.
  • The target scope of a procedure should be able to accomodate the specified number of inputs into the scope's local variables.
  • The first and second arguments to CLEO_RETURN and CLEO_CALL, respectively, shall be set to 0. The compiler should, during compilation, tweak the value appropriately to the number of inputs, for CLEO_CALL, and number of outputs, for CLEO_RETURN.

Enforcing good practices

Compilers are encouraged to disallow the use of the following commands and features in custom scripts/missions:

  • Global variables
  • START_NEW_SCRIPT, LAUNCH_MISSION, LOAD_AND_LAUNCH_MISSION, REGISTER_STREAMED_SCRIPT
  • TERMINATE_THIS_SCRIPT in custom scripts
  • TERMINATE_THIS_CUSTOM_SCRIPT in custom missions

Command list

Argument types still undefined.

ID Command Name Command Hash
2700 WRITE_MEMORY 0xc3cc351e
2701 READ_MEMORY 0x7fc4ddcc
2706 STREAM_CUSTOM_SCRIPT 0x0a39152e
2707 TERMINATE_THIS_CUSTOM_SCRIPT 0xa70e9e1c
2708 LOAD_AND_LAUNCH_CUSTOM_MISSION 0xbc6ac801
2709 SAVE_THIS_CUSTOM_SCRIPT 0x9dbb8e4d
2710 GET_PED_POINTER 0x0435bb80
2711 GET_VEHICLE_POINTER 0xe0b6474e
2712 GET_OBJECT_POINTER 0xa9de7705
2713 SET_CURRENT_DIRECTORY 0xc6e9c287
2714 OPEN_FILE 0xd4269fc0
2715 CLOSE_FILE 0x71064381
2716 GET_FILE_SIZE 0x03c7db92
2717 READ_FROM_FILE 0xebeb6b72
2718 WRITE_TO_FILE 0xb98a1f91
2719 GET_THIS_SCRIPT_STRUCT 0x18f8e9ba
2720 GOSUB_IF_FALSE 0xe0ce4bc9
2721 RETURN_IF_FALSE 0xadfd5905
2722 LOAD_DYNAMIC_LIBRARY 0x0c7895c3
2723 FREE_DYNAMIC_LIBRARY 0x0bce02c1
2724 GET_DYNAMIC_LIBRARY_PROCEDURE 0x8441dd71
2725 CALL_FUNCTION 0xd3b6abef
2726 CALL_METHOD 0x238fec28
2727 CALL_FUNCTION_RETURN 0xb8f2e637
2728 CALL_METHOD_RETURN 0x5a151db7
2729 IS_GAME_VERSION_ORIGINAL 0x5781af0a
2730 GET_SCRIPT_STRUCT_NAMED 0x99901253
2731 DOES_FILE_EXIST 0x90c73067
2732 LOAD_AUDIO_STREAM 0x3aa0733a
2733 SET_AUDIO_STREAM_STATE 0x5a2768ca
2734 REMOVE_AUDIO_STREAM 0xa3e6165b
2735 GET_AUDIO_STREAM_LENGTH 0x5fda28bf
2736 IS_KEY_PRESSED 0x400c1a58
2737 CLEO_CALL 0x4cb430f8
2738 CLEO_RETURN 0xa1352fbf
2739 SET_CLEO_SHARED_VAR 0x371eb889
2740 GET_CLEO_SHARED_VAR 0xade9b81a
2741 STORE_CLOSEST_ENTITIES 0x7cf6435a
2742 GET_TARGET_BLIP_COORDS 0xf032e185
2743 GET_CAR_NUMBER_OF_GEARS 0xb5a33a1b
2744 GET_CAR_CURRENT_GEAR 0x61c1141d
2745 GET_AUDIO_STREAM_STATE 0xf68eeafb
2746 TERMINATE_ALL_CUSTOM_SCRIPTS_WITH_THIS_NAME 0x26d7351d
2747 GET_AUDIO_STREAM_VOLUME 0x2cede2f0
2748 SET_AUDIO_STREAM_VOLUME 0x8f46738d
2749 IS_CAR_SIREN_ON 0xe7d7fac4
2750 IS_CAR_ENGINE_ON 0xf98c32c2
2751 CLEO_SET_CAR_ENGINE_ON 0xf4231beb
2752 SET_AUDIO_STREAM_LOOPED 0xff5c8216
2753 LOAD_3D_AUDIO_STREAM 0xc71ca466
2754 SET_PLAY_3D_AUDIO_STREAM_AT_COORDS 0x0581e4db
2755 SET_PLAY_3D_AUDIO_STREAM_AT_OBJECT 0x173f8062
2756 SET_PLAY_3D_AUDIO_STREAM_AT_CHAR 0x3af35994
2757 SET_PLAY_3D_AUDIO_STREAM_AT_CAR 0x8b10af0b
2758 GET_LABEL_POINTER 0xd287a6ce
2759 GET_VAR_POINTER 0xdfc15673
2760 ALLOCATE_MEMORY 0x3dfeff9e
2761 FREE_MEMORY 0x8533ff35
2762 PRINT_HELP_STRING 0x1f74954c
2763 PRINT_BIG_STRING 0xaf463d4a
2764 PRINT_STRING 0xedbc43b9
2765 PRINT_STRING_NOW 0x4091a169
2766 PRINT_HELP_FORMATTED 0x142eaa04
2767 PRINT_BIG_FORMATTED 0x873b5318
2768 PRINT_FORMATTED 0xb4e86f66
2769 PRINT_FORMATTED_NOW 0x85cb5ec5
2770 GET_CHAR_PLAYER_IS_TARGETING 0x24fe143f
2771 STRING_FORMAT 0xceb5b84c
2772 SCAN_STRING 0x48d3526f
2773 FILE_SEEK 0x6ac81649
2774 IS_END_OF_FILE_REACHED 0x3d0f9311
2775 READ_STRING_FROM_FILE 0x8e6649ba
2776 WRITE_STRING_TO_FILE 0x0e6353a6
2777 WRITE_FORMATTED_STRING_TO_FILE 0x369350ac
2778 SCAN_FILE 0x2feb5ff0
2779 GET_NAME_OF_VEHICLE_MODEL 0x13e5d1a0
2780 TEST_CHEAT 0x04990785
2781 SPAWN_VEHICLE_BY_CHEATING 0x67f919dd
2782 GET_TEXT_LABEL_STRING 0x9b52718b
2783 ADD_TEXT_LABEL 0xffc7b8cd
2784 REMOVE_TEXT_LABEL 0x9daa63ff
2785 GET_RANDOM_CHAR_IN_SPHERE_NO_SAVE_RECURSIVE 0x2e6c5c91
2786 GET_RANDOM_CAR_IN_SPHERE_NO_SAVE_RECURSIVE 0x16416536
2787 GET_RANDOM_OBJECT_IN_SPHERE_NO_SAVE_RECURSIVE 0x04dc82f4
2788 DOES_DIRECTORY_EXIST 0x25d29989
2789 CREATE_DIRECTORY 0xa9b8826c
2790 FIND_FIRST_FILE 0x3ca32387
2791 FIND_NEXT_FILE 0x7b5d1038
2792 FIND_CLOSE 0xe9b900c2
2793 POP_FLOAT 0x96d598a2
2794 GET_PED_REF 0xfd2a608e
2795 GET_VEHICLE_REF 0xf4db7227
2796 GET_OBJECT_REF 0x2d71931a
2797 STRING_FLOAT_FORMAT 0x5f3acf3f
2798 POW 0xe7a3f707
2799 LOG 0x1fb5b3ec
2800 READ_INT_FROM_INI_FILE 0x7bbf9213
2801 WRITE_INT_TO_INI_FILE 0xe0c7424d
2802 READ_FLOAT_FROM_INI_FILE 0x09be5524
2803 WRITE_FLOAT_TO_INI_FILE 0xa1d0b758
2804 READ_STRING_FROM_INI_FILE 0xa85fb541
2805 WRITE_STRING_TO_INI_FILE 0x1fe9b38f
2816 DELETE_FILE 0xdd49d9c1
2817 DELETE_DIRECTORY 0xd48a399c
2818 MOVE_FILE 0xcb9d1de4
2819 MOVE_DIRECTORY 0xa3360aff
2820 COPY_FILE 0xf29cb2cc
2821 COPY_DIRECTORY 0x79b66ee9
2832 BITWISE_AND 0x5e21b170
2833 BITWISE_OR 0x7e03c9ad
2834 BITWISE_XOR 0xe112b461
2835 BITWISE_NOT 0xc315e20e
2836 MOD 0xb40a4474
2837 BITWISE_SHR 0x12041cc6
2838 BITWISE_SHL 0xc3007ec0

Alternatives

  • WRITE_PROCESS_MEMORY / READ_PROCESS_MEMORY instead of WRITE_MEMORY / READ_MEMORY.
  • HAS_END_OF_FILE_REACHED instead of IS_END_OF_FILE_REACHED.

Unresolved questions

  • Definition of argument types.
  • Remark: The indice of variables in a CLEO_CALL scope must start at 0 (and currently, end at 32). That means for San Andreas Mission Scripts, the call scope indices must be fixed, since they start at 34.
  • Custom Missions are enclosed by MISSION_START...MISSION_END and Custom Scripts by SCRIPT_START...SCRIPT_END.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment