CLEO Library

Features
Report a Bug

CLEO 5.1

Input Plugin

CLEO 5.1 introduces the new Input.cleo plugin, providing comprehensive keyboard and controller input handling capabilities.

The plugin includes the following new opcodes:

Calling Game Functions as a Condition

Commands CALL_FUNCTION, CALL_FUNCTION_RETURN, CALL_METHOD, CALL_METHOD_RETURN now additionally set the condition result. It allows for ergonomic code: 

if CGarages_IsPointWithinHideOutGarage(pos)
then
    trace "In a garage"
end

function CGarages_IsPointWithinHideOutGarage<cdecl, 0x448900>(point: int {CVector}): logical

Also it can be used to defensively validate returned pointers against nullptr:

if int pCheatCar = CCheat_VehicleCheat(#NRG500)
then
    Car hCheatCar = get_vehicle_ref {address} pCheatCar
    Blip hCarBlip = add_blip_for_car {vehicle} hCheatCar
end

function CCheat_VehicleCheat<cdecl, 0x43A0B0>(vehicleModelId: int): int

Improved Error Reporting

"Previously called" information in error messages shows commands from the current script only, also appear in more messages.

Added warnings when 3D_AUDIO_STREAM commands are used with non-3D audio streams to prevent common scripting errors.

Added a proper error message for scripts compiled with Sanny Builder's extra SCM information when the execution flow goes beyond the last instruction due to missing terminate_this_script or goto at the end of the script.

CLEO 5.0

CLEO Modules

CLEO Modules are a new way to organize and share code in CLEO 5.

Sanny Builder 4 supports CLEO Modules using import and export syntax. To create a module, you need to create and then export functions. 

{$CLEO .mod}

export function sum(a: int, b: int): int
    int result = a + b
    return result
end

You can import the module in your main script using the import command:

{$CLEO .cs}
wait 2000

import sum from "my.mod" // see an example module above

int res = sum(10, 20) // call imported function with 2 arguments and store the result
print_help_formatted "10 + 20 = %d" res

terminate_custom_script

To learn more about CLEO Modules visit https://docs.sannybuilder.com/language/import-export

Better Functions

New return commands CLEO_RETURN_WITH and CLEO_RETURN_FAIL. 

function GET_PLAYER_CAR: optional int
    if
        not does_char_exist $scplayer
    then
        cleo_return_fail
    end

    if
        not is_char_sitting_in_any_car $scplayer
    then
        cleo_return_fail
    end

    int car_handle = store_car_char_is_in_no_save $scplayer
    
    cleo_return_with true {args} car_handle
end

RETURN can be used as an alternative to CLEO_RETURN 0.

Functions can return strings:

function get_name(): string
    return "CLEO"
end

Functions maintain its own GOSUB stack (up to 8 calls).

Enhanced Runtime

CLEO's support of strings pointers has been extended to all native commands. For example, PRINT_HELP can now read strings from memory addresses. 

PRINT_HELP 0x008599EC // shows text using 'GA_7' GXT key

Script commands can use special path prefixes to reference files in common folders:

  • root:
  • cleo:
  • user:
  • .\
int f = open_file {filePathName} "user:\gta_sa.set" {mode} "rb" // read from GTA San Andreas User Files
int f = open_file {filePathName} ".\config.ini" {mode} "rb" // read from script directory

Use of unsafe command SET_CURRENT_DIRECTORY is not needed anymore.

See RESOLVE_FILEPATH for more examples

CLEO 5 is less tolerant to script errors. Previously it would ignore errors and let the game crash. Now it minimizes the crashes by doing upfront parameter validation and notifying the user about the error. CLEO provides detailed error messages, including script and code location.

Some benign errors result in on-screen warnings and can be ignored. Ideally, they should be fixed in the code, but if that is not possible, then a special compatilibity mode can be used.

To run the script with maximum compatibility to CLEO 4 behavior, give the script a .cs4 extension.

Audio Enhancements

Audio enhancements, including new commands for better control over audio streams and support for the Doppler effect for 3D audio.

CLEO's audio now obeys game volume settings and follows game speed changes for better synchronization.

Implemented proper support for 3D audio stream source size and updated distance decay to match in-game sound behavior.

Fixed sound glitches and crashes related to 3D audio streams, ensuring smoother playback.

See the Audio Demo script for inspiration.

Debug Utilities

New debug utilities, such as commands for tracing and logging, breakpoints, and optional support for Rockstar's original debugging opcodes, like WRITE_DEBUG, WRITE_DEBUG_WITH_INT, and WRITE_DEBUG_WITH_FLOAT. 

debug_on

trace "Hello world!"
wait {time} 1000
trace "Time: %d, ~g~Variable: %d" TIMERA 0@
breakpoint "Time is: %d" TIMERA // pause game with formatted message

Plugins & SDK

Dozens of new methods and helper functions in the SDK.

Plugins and their configuration files have been moved to the cleo_plugins folder to declutter the main CLEO directory.

FileSystemOperations plugin includes new commands to copy content of the file to the memory address, dump memory to the file, or get the script filename.

New Math plugin with opcodes for bit manipulation, random number generation, and more.

New MemoryOperations plugin with enhanced memory access and validation features.

New Text plugin with opcodes for text manipulation, formatted text display, and FXT file handling.

CLEO 4 Compatibility Mode

CLEO 5 introduced multiple script error checks and validation mechanisms to prevent faulty scripts from crashing the game. These features provide developers with a way to notice non-critical bugs. However, to maintain compatibility with older scripts, CLEO 4 compatibility mode was introduced.

To enable CLEO 4 compatibility mode, rename the script's filename extension from .cs to .cs4. For the main.scm, modify the MainScmLegacyMode property in the cleo\.cleo_config.ini configuration file. All scripts spawned from a script in legacy mode will inherit the same mode.

Using CLEO 4 mode disables warning messages about non-critical problems displayed on screen and logged into files. It also changes opcode behavior as follows:

Parameter Type Validation

CLEO 5: Validates input/output parameter types for most opcodes. For example, providing a float instead of an integer will result in an error.
CLEO 4: No validation is performed. Providing a float instead of an integer is allowed without any warnings.

Out-of-Bounds Code Execution

CLEO 5: Checks that script execution can't go beyond the last instruction. Violating the script boundary results in an error.
CLEO 4: No checks are performed. Scripts can continue executing past their intended end without warnings.

SCM Functions and RETURN

CLEO 5: SCM Functions can exit with RETURN opcode
CLEO 4: SCM Functions cannot exit with RETURN opcode

SCM Functions and Output Count

CLEO 5: SCM Functions returning less results than expected are reported.
CLEO 4: SCM Functions can return less arguments than expected.

Native Function Calls and Input Count

CLEO 5: Reports errors for mismatched input argument counts in call_function, call_method, etc.
CLEO 4: Ignores mismatched argument counts, replacing missing values with zeros.

3D Audio Stream Default Type

CLEO 5: 3D Audio streams use the default stream type (SFX).
CLEO 4: 3D Audio streams use the default stream type defined in SA.Audio.ini.

INI File Handling

CLEO 5: Returns errors for invalid keys or missing values in INI files. Output variable is not modified.
CLEO 4: Returns default values (e.g., 0x80000000 for integers, 0.0 for floats) without reporting errors.

String Scanning

CLEO 5: Validates target string variable sizes to prevent buffer overflow.
CLEO 4: Disables size checks, allowing potential buffer overflow.

Deleting Content from INI File

CLEO 5: Requires explicit commands to delete sections or keys from INI files (DELETE_KEY_FROM_INI_FILE, DELETE_SECTION_FROM_INI_FILE)
CLEO 4: Allows deletion of sections or keys by passing 0 to WRITE_INT_TO_INI_FILE, WRITE_FLOAT_TO_INI_FILE, or WRITE_STRING_TO_INI_FILE.