CLEO Library

Script Logs

CLEO 5.2 adds built-in script logging via the Debug Utilities plugin. It allows you to record script commands to a log file for debugging and analysis. Log is saved in cleo\_cleo_script.log.

Logs can be configured in cleo_plugins\DebugUtils.ini:

Logging Modes

• Off - No logging
• On Crash - Only logs when game crashes
• Always On - Records every command

Additional Options

• Filter by script type (custom scripts only or everything)
• Log only scripts using debug_on command
• With code offsets and opcode numbers
• Set file size limits (default 250 MB)

Memory Usage Limits

Memory Operations plugin sets various memory limits for scripts. Default values configured in cleo_plugins\SA.MemoryOperations.ini are:

• MemoryAllocations = 2000 memory blocks per script
• MemoryTotalSize = 16 MB per script

Exceeding these limits will result in runtime warnings, helping to prevent excessive memory usage and leaks.

TXD Sprite Corruption Fix

Infamous CLEO 4 bug causing texture sprites to become invisible or display junk graphics has been fixed. Scripts can now safely use sprites from multiple TXDs without risk of corruption or memory leaking. For more technical details, see Script-TXD Issues

More Improvements

• Stack overflow check added to gosub and gosub_if_false commands to prevent crashes
• Added check for preceding gosub call in 0AA1 (return_if_false) to ensure proper usage
• Added error message when script crashes in SAMP due to coding issues, previously the script would silently stop or produce a misleading "Opcode Not Found" error
• CLEO removes trailing whitespace from FXT entries that prevent them from being displayed in game
• 0AD4 (scan_string) command now supports string pointers as output type, providing more flexibility in string operations.

Input Plugin

New Input.cleo plugin for keyboard and controller input handling.

New opcodes:

• 2080 (is_key_just_pressed) - Check if a key was just pressed this frame
• 2081 (get_key_pressed_in_range) - Get any key currently pressed within a range
• 2082 (get_key_just_pressed_in_range) - Get any key just pressed within a range
• 2083 (emulate_key_press) - Simulate a key press
• 2084 (emulate_key_release) - Simulate a key release
• 2085 (get_controller_key) - Get key assigned to game action
• 2086 (get_key_name) - Get keyboard/mouse key name

Calling Game Functions as a Condition

Commands CALL_FUNCTION, CALL_FUNCTION_RETURN, CALL_METHOD, CALL_METHOD_RETURN now set condition results for cleaner code:

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

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

Also useful for pointer validation:

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

Error messages now show "previously called" info from current script only and appear in more places.

Warnings when 3D_AUDIO_STREAM commands are used with non-3D audio streams.

Better error messages for scripts that run beyond their end without terminate_this_script or goto.

CLEO Modules

New way to organize and share code in CLEO 5.

Sanny Builder 4 supports modules using import and export syntax.

{$CLEO .mod}

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

Import the module in your script:

{$CLEO .cs}
wait 2000

import sum from "my.mod"

int res = sum(10, 20)
print_help_formatted "10 + 20 = %d" res

terminate_custom_script

Learn more: Import/Export Documentation

Better Functions

New 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 replace CLEO_RETURN 0.

Functions can return strings and maintain their own GOSUB stack (up to 8 calls):

function get_name(): string
    return "CLEO"
end

Enhanced Runtime

CLEO extends string pointer support to all native commands. For example, PRINT_HELP can read strings from memory addresses:

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

Script commands support special path prefixes for 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

The unsafe command SET_CURRENT_DIRECTORY is no longer needed.

See RESOLVE_FILEPATH for more examples.

CLEO 5 validates parameters upfront and provides detailed error messages with script and code location. This prevents crashes but shows errors that CLEO 4 would ignore.

Benign errors show on-screen warnings and can be ignored. For maximum CLEO 4 compatibility, use .cs4 extension.

Audio Enhancements

New audio commands provide better control over streams and Doppler effect support for 3D audio.

Audio now follows game volume settings and speed changes for proper synchronization.

Improved 3D audio with proper source size support and distance decay matching in-game sound.

Fixed sound glitches and crashes for smoother playback.

See the Audio Demo script for examples.

Debug Utilities

New debug commands for tracing, logging, breakpoints, and support for Rockstar's original 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 config files moved to cleo_plugins folder to declutter the main directory.

FileSystemOperations plugin includes commands to copy file content to memory, dump memory to file, or get 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