SDK Documentation

CLEO 5 SDK allows developers to create new opcodes for GTA San Andreas.

Version Information

Current Version: 5.3.0

The SDK uses a versioning system with main, major, and minor components:

#define CLEO_VERSION_MAIN   5
#define CLEO_VERSION_MAJOR  3
#define CLEO_VERSION_MINOR  0

The combined version is calculated as: 0x05030000

Enumerations

Version Enums

eCLEO_Version - Represents different CLEO versions for compatibility checking.

eGameVersion - Identifies the game version.

Callbacks

eCallbackId - Callback types for event handling.

Other Enums

eLogLevel - Log severity levels.

OpcodeResult - Opcode execution results.

eLogicalOperation - Logical operations for conditional expressions.

Constants

String Length

• MAX_STR_LEN: Maximum string parameter length (255 characters)

Virtual Path Prefixes

Data Structures

SCRIPT_VAR Union

A union for storing different parameter types:

union SCRIPT_VAR {
    DWORD dwParam;    // 32-bit unsigned integer
    short wParam;     // 16-bit signed integer
    WORD usParam;     // 16-bit unsigned integer
    BYTE ucParam;     // 8-bit unsigned integer
    char cParam;      // 8-bit signed char
    bool bParam;      // Boolean
    int nParam;       // 32-bit signed integer
    float fParam;     // 32-bit float
    void* pParam;     // Generic pointer
    char* pcParam;    // String pointer
};

StringList Structure

Container for string arrays:

struct StringList {
    DWORD count;      // Number of strings
    char** strings;   // Array of string pointers
};

CRunningScript Class

The main class representing a running script instance.

Class Members

| Member             | Type              | Offset | Description                    |
| -------------------| ------------------| ------ | ------------------------------ |
| Next               | CRunningScript*   | 0x00   | Next script in queue           |
| Previous           | CRunningScript*   | 0x04   | Previous script in queue       |
| Name               | char[8]           | 0x08   | Script name (from 03A4 opcode) |
| BaseIP             | void*             | 0x10   | Script base pointer            |
| CurrentIP          | BYTE*             | 0x14   | Current instruction pointer    |
| Stack              | BYTE*[8]          | 0x18   | Return stack                   |
| SP                 | WORD              | 0x38   | Stack pointer                  |
| LocalVar           | SCRIPT_VAR[32]    | 0x3C   | Local variables                |
| Timers             | DWORD[2]          | 0xBC   | Script timers                  |
| bIsActive          | bool              | 0xC4   | Active status                  |
| bCondResult        | bool              | 0xC5   | Condition result               |
| bUseMissionCleanup | bool              | 0xC6   | Mission cleanup flag           |
| bIsExternal        | bool              | 0xC7   | External script flag           |
| bTextBlockOverride | bool              | 0xC8   | Text block override            |
| bExternalType      | BYTE              | 0xC9   | External type                  |
| WakeTime           | DWORD             | 0xCC   | Wake time after wait           |
| LogicalOp          | eLogicalOperation | 0xD0   | Logical operation              |
| NotFlag            | bool              | 0xD2   | NOT flag                       |
| bWastedBustedCheck | bool              | 0xD3   | Wasted/busted check            |
| bWastedOrBusted    | bool              | 0xD4   | Player wasted/busted           |
| SceneSkipIP        | void*             | 0xD8   | Scene skip label               |
| bIsMission         | bool              | 0xDC   | Mission script flag            |
| ScmFunction        | WORD              | 0xDD   | SCM function ID                |
| bIsCustom          | bool              | 0xDF   | CLEO script flag               |
                

Key Methods

Status Methods

Variable Access

Script Control

Data Reading

Type Checking Functions

Type Conversion Functions

SDK Functions

Version and System Information

Opcode Functions

Script Management

Script Information

Script Creation and Control

Parameter Handling

Reading Parameters

Writing Parameters

Peeking Parameters (Non-advancing)

Utility Functions

File System Functions

Other Utility Functions

Usage Examples

Registering a Custom Opcode

OpcodeResult __stdcall MyOpcodeHandler(CRunningScript* script) {
    // Read parameters
    int param1 = CLEO_GetIntOpcodeParam(script);
    float param2 = CLEO_GetFloatOpcodeParam(script);

    // Process...

    // Set result
    CLEO_SetIntOpcodeParam(script, result);

    return OR_CONTINUE;
}

// Register the opcode
CLEO_RegisterOpcode(0x0DD0, MyOpcodeHandler);

Creating a Custom Script

CRunningScript* newScript = CLEO_CreateCustomScript(
    parentScript,
    "cleo:\\MyScript.cs",
    0  // start label
);

if (newScript) {
    // Script created successfully
}

Working with Callbacks

void WINAPI OnGameBegin(DWORD saveSlot) {
    if (saveSlot == -1) {
        // New game started
    } else {
        // Game loaded from save slot
    }
}

// Register callback
CLEO_RegisterCallback(eCallbackId::GameBegin, OnGameBegin);

CLEO_Utils Helper Library

The CLEO_Utils.h header provides utility functions and macros to simplify CLEO plugin development with error handling, parameter validation, and common operations.

Setup Requirements

To use CLEO_Utils.h in your CLEO plugin project, configure your build settings:

Additional Include Directories:

$(PLUGIN_SDK_DIR)\plugin_sa\
$(PLUGIN_SDK_DIR)\shared\game\
$(PLUGIN_SDK_DIR)\plugin_sa\game_sa\

Preprocessor Definitions:

GTASA
TARGET_NAME=R"($(TargetName))"

Logging and Error Handling

Basic Logging Macros

Condition Result Macro

OPCODE_CONDITION_RESULT(value)  // Set opcode's logical result

Opcode Parameter Macros

These macros simplify parameter handling in opcode implementations with automatic type validation and error handling. They expand to multiple lines, so cannot be used where single statements are expected (e.g., if conditions without braces).

Parameter Inspection

Reading Input Parameters

All read macros perform type validation and suspend the script on error.

Basic Types:

OPCODE_READ_PARAM_BOOL()           // Read boolean value
OPCODE_READ_PARAM_INT8()           // Read signed 8-bit integer
OPCODE_READ_PARAM_UINT8()          // Read unsigned 8-bit integer
OPCODE_READ_PARAM_INT16()          // Read signed 16-bit integer
OPCODE_READ_PARAM_UINT16()         // Read unsigned 16-bit integer
OPCODE_READ_PARAM_INT()            // Read signed 32-bit integer
OPCODE_READ_PARAM_UINT()           // Read unsigned 32-bit integer
OPCODE_READ_PARAM_FLOAT()          // Read float value
OPCODE_READ_PARAM_ANY32()          // Read any 32-bit value (int or float)

String Parameters:

OPCODE_READ_PARAM_STRING(varName)
// Creates: const char* varName pointing to null-terminated string

OPCODE_READ_PARAM_STRING_LEN(varName, maxLength)
// Creates: const char* varName with length clamped to maxLength

OPCODE_READ_PARAM_STRING_FORMATTED(varName)
// Reads format string and var-args
// Creates: char varName[] with formatted text
// Creates: char* varNameOk (nullptr if invalid)

OPCODE_READ_PARAMS_FORMATTED(format, varName)
// Uses provided format for var-args
// Creates: char varName[] with formatted text
// Creates: char* varNameOk (nullptr if invalid)

OPCODE_READ_PARAM_FILEPATH(varName)
// Creates: const char* varName with resolved and validated file path

Validated Handle Parameters:

OPCODE_READ_PARAM_PTR()             // Read and validate memory pointer
OPCODE_READ_PARAM_OBJECT_HANDLE()   // Read and validate object handle
OPCODE_READ_PARAM_PED_HANDLE()      // Read and validate ped/actor handle
OPCODE_READ_PARAM_VEHICLE_HANDLE()  // Read and validate vehicle handle
OPCODE_READ_PARAM_PLAYER_ID()       // Read and validate player ID

Output Variable Parameters (for mixed param order):

OPCODE_READ_PARAM_OUTPUT_VAR_INT()    // Get int* for later writing
OPCODE_READ_PARAM_OUTPUT_VAR_FLOAT()  // Get float* for later writing
OPCODE_READ_PARAM_OUTPUT_VAR_ANY32()  // Get SCRIPT_VAR* for later writing
OPCODE_READ_PARAM_OUTPUT_VAR_STRING() // Get StringParamBufferInfo for later writing

Writing Output Parameters

All write macros perform type validation and suspend the script on error.

OPCODE_WRITE_PARAM_BOOL(value)
OPCODE_WRITE_PARAM_INT8(value)
OPCODE_WRITE_PARAM_UINT8(value)
OPCODE_WRITE_PARAM_INT16(value)
OPCODE_WRITE_PARAM_UINT16(value)
OPCODE_WRITE_PARAM_INT(value)
OPCODE_WRITE_PARAM_UINT(value)
OPCODE_WRITE_PARAM_FLOAT(value)
OPCODE_WRITE_PARAM_ANY32(value)
OPCODE_WRITE_PARAM_STRING(value)
OPCODE_WRITE_PARAM_STRING_INFO(info, value)  // Using StringParamBufferInfo
OPCODE_WRITE_PARAM_PTR(value)

String Utilities

String Manipulation Functions

File Path Utilities

Path Manipulation Functions

Validation Functions

Handle Validation

Script Version Check

Memory Utilities

Memory Patching

String List Creation

Usage Examples with CLEO_Utils.h

Custom Opcode with Parameter Validation

OpcodeResult __stdcall opcode_CreateEffect(CRunningScript* thread)
{
    // Read and validate parameters
    auto pedHandle = OPCODE_READ_PARAM_PED_HANDLE();
    auto effectId = OPCODE_READ_PARAM_INT();
    auto duration = OPCODE_READ_PARAM_FLOAT();
    OPCODE_READ_PARAM_STRING(effectName);

    // Process the effect...
    bool success = CreateEffect(pedHandle, effectId, duration, effectName);

    // Set condition result
    OPCODE_CONDITION_RESULT(success);

    // Write output
    OPCODE_WRITE_PARAM_INT(effectHandle);

    return OR_CONTINUE;
}

Safe File Operations

OpcodeResult __stdcall opcode_ReadFile(CRunningScript* thread)
{
    OPCODE_READ_PARAM_FILEPATH(filepath);  // Automatically validated
    auto* outputVar = OPCODE_READ_PARAM_OUTPUT_VAR_STRING();

    if (FilepathIsSafe(thread, filepath))
    {
        std::string content = ReadFileContent(filepath);
        OPCODE_WRITE_PARAM_STRING_INFO(outputVar, content.c_str());
    }
    else
    {
        LOG_WARNING(thread, "Unsafe file path: %s", filepath);
        return thread->Suspend();
    }

    return OR_CONTINUE;
}

Formatted String Reading

OpcodeResult __stdcall opcode_PrintFormatted(CRunningScript* thread)
{
    OPCODE_READ_PARAM_STRING_FORMATTED(message);

    if (messageOk)  // Automatically created by macro
    {
        DisplayMessage(message);
    }
    else
    {
        SHOW_ERROR("Invalid format string in script %s",
                   ScriptInfoStr(thread).c_str());
        return thread->Suspend();
    }

    return OR_CONTINUE;
}

Notes

• CLEO 5 supports GTA SA 1.0 US only
• Use CLEO_ResolvePath for file operations to ensure ModLoader compatibility
• String buffers have a maximum length of 255 characters (MAX_STR_LEN)
• CLEO_Utils.h macros expand to multiple lines - use braces with if statements
• Memory addresses below 0x10000 are considered invalid (Windows reserved)