CLEO 5

CLEO Modules

Modular code with import/export support in Sanny Builder 4 — share and update code independently.

{$CLEO .mod}

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

Import example:

{$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

Improved Functions & Runtime

• New return helpers: CLEO_RETURN_WITH and CLEO_RETURN_FAIL.
• SCM functions can use RETURN, return strings, and keep an isolated GOSUB stack.
• Native commands accept string pointers (example: PRINT_HELP 0x008599EC).
• Virtual path prefixes for file ops: root:, user:, cleo:, .\.
• Improved error handling and runtime checks.

Debugging & Logs

Built-in Debug Utilities with tracing, breakpoints, and script logging (cleo_script.log), plus optional legacy debug opcodes.

debug_on

trace "Hello world!"
wait {time} 1000
breakpoint "Time is: %d" TIMERA

Audio, Plugins & SDK

Improved 3D audio (Doppler, correct volume handling), many updated plugins (FileSystemOperations, MemoryOperations, Math, Text) and expanded SDK helpers.

Error Handling

Some non-critical errors are now reported as warnings instead of suspending the script. To report them as errors again, set StrictValidation = 1 (see Config section for details). StrictValidation is highly recommended for development and debugging to catch issues early.

Also onscreen messages have been disabled by default; to enable them, set DebugUtils.ScreenLog.Level (see Config section for details).

String Formatting

String formatting has been thoroughly revised and improved:

• support uppercase modifiers (%D %C %S), that previously caused crashes or were ignored
• providing 0 for format string now errors instead of crashing the game
• add support for hh length modifier, which represents a signed char (-128..127) (e.g. "%hhd") in addition to already supported h and l
• %p formats the address in lowercase, %P formats the address in uppercase

CLEO 4.4.4 Behavior

{0AD1:} print_formatted_now {format} "hi %D" {time} 5000 {args} 100 // "hi D"
{0AD1:} print_formatted_now {format} "hi %C" {time} 5000 {args} 0x41 // "hi A"
{0AD1:} print_formatted_now {format} "hi %S" {time} 5000 {args} 'world' // Game crash
{0AD1:} print_formatted_now {format} "hi %F" {time} 5000 {args} 42.5 // "hi 42.50000"
{0AD1:} print_formatted_now {format} "hi %p" {time} 5000 {args} 0x123ABC // "hi 00123ABC"
{0AD1:} print_formatted_now {format} "hi %P" {time} 5000 {args} 0x123ABC // "hi 00123ABC"
{0AD1:} print_formatted_now {format} 0 {time} 5000 // Game crash

CLEO 5.3 Behavior

{0AD1:} print_formatted_now {format} "hi %D" {time} 5000 {args} 100 // "hi 100"
{0AD1:} print_formatted_now {format} "hi %S" {time} 5000 {args} 'world' // "hi world"
{0AD1:} print_formatted_now {format} "hi %p" {time} 5000 {args} 0x123ABC // "hi 00123abc"
{0AD1:} print_formatted_now {format} 0 {time} 5000 // Script suspended

Other Improvements

• moved CLEO core and plugin settings into a shared configuration file (CLEO\.cleo_config.ini)
• keyboard input is now ignored when the game window is not focused
• increased text length limit from 255 to 399 for:
  • PRINT_STRING
  • PRINT_STRING_NOW

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. See Logs section for setup details.

Memory Usage Limits

The Memory Operations plugin sets various memory limits for scripts. Default limits 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

The 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 report "Opcode Not Found").
• 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.

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, and 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 the 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.

Create a module with exported functions:

{$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.
• RETURN can replace CLEO_RETURN 0.
• Functions can return strings and maintain their own GOSUB stack (up to 8 calls).

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

Enhanced Runtime

CLEO extends string pointer support to native commands; for example PRINT_HELP 0x008599EC can show text using a GXT key.

Script commands support special path prefixes: root:, cleo:, user:, and .\.

int f = open_file {filePathName} "user:\gta_sa.set" {mode} "rb"
int f = open_file {filePathName} ".\config.ini" {mode} "rb"

CLEO 5 validates parameters upfront and provides detailed error messages; 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 debug opcodes.

debug_on

trace "Hello world!"
wait {time} 1000
trace "Time: %d, ~g~Variable: %d" TIMERA 0@
breakpoint "Time is: %d" TIMERA

Plugins & SDK

• Dozens of new methods and helper functions in the SDK.
• Plugins and config files moved to cleo_plugins folder.
• FileSystemOperations plugin includes commands to copy file content to memory, dump memory to file, or get script filename.
• Math plugin with opcodes for bit manipulation and RNG.
• MemoryOperations plugin with enhanced memory access and validation features.
• Text plugin with opcodes for text manipulation, formatted text display, and FXT handling.

Is CLEO 5 compatible with existing scripts?

It depends — most scripts work, but CLEO 5 adds safety checks that may reveal bugs. If a script fails, try renaming .cs to .cs4 to enable compatibility mode.

My script crashes with CLEO 5 but works with CLEO 4. What should I do?

First try changing the script extension to .cs4. If issues persist, open a ticket: create an issue, or ask on Discord.

What's the difference between .CS and .CS4?

.cs4 enables CLEO4 compatibility mode, which relaxes many CLEO5 checks to better mimic CLEO4 behavior. See Compatibility Mode section for details.

How do I install CLEO?

Check the installation guide.

How can I develop my own opcodes?

Use the CLEO SDK and review the examples shipped with CLEO.