CLEO SDK

В базовый модуль CLEO.asi версии 4.1 встроена возможность динамического добавления обработчиков свободных опкодов (0AF0...7FFF). Регистрация нового обработчика может осуществляться из CLEO-плагина, что позволяет писать новые опкоды сторонним разработчикам, расширяя тем самым функционал CLEO и GTA скриптинга в целом.

В CLEO SDK входит:

  • Файл справки (этот файл);
  • Файлы CLEO.h, CLEO.lib используемые для компановки с базовым модулем CLEO.asi;
  • Исходные коды демонстрационных плагинов IniFiles.cleo, FileSystemOperations.cleo и IntOperations.cleo.


CLEO_RegisterOpcode

BOOL WINAPI CLEO_RegisterOpcode(WORD opcode, _pOpcodeHandler callback);

Описание

Функция регистрирует обработчик опкода. Если регистрация завершилась успешно, будет возвращено значение TRUE. Если опкоду с данным номером уже назначен другой обработчик, будет возвращено значение FALSE и выведено сообщение о возможных проблемах в игре.

Параметры

opcode | номер опкода в диапазоне от 0x0AF0 до 0x7FFF;
callback | указатель на функцию-обработчик опкода. См. Формат обработчика опкода.

Пример использования

if (!CLEO_RegisterOpcode(0xC00, &opcode_0C00)) {
return FALSE;
}
Вернуться на предыдущую страницу


CLEO_GetVersion

DWORD WINAPI CLEO_GetVersion();

Описание

Функция возвращает номер версии CLEO, эта величина должна сравниваться с константой CLEO_VERSION.

Пример использования

if (CLEO_GetVersion() < CLEO_VERSION) {
MessageBox(HWND_DESKTOP, "An incorrect version of CLEO was loaded.", NULL, MB_ICONERROR);
return FALSE;
}


CLEO_GetGameVersion

int WINAPI CLEO_GetGameVersion();

Описание

Функция возвращает идентификатор версии игры:

  • GV_US10 - американская версия 1.0;
  • GV_US11 - американская версия 1.01, эта версия не поддерживается CLEO;
  • GV_EU10 - европейская версия 1.0;
  • GV_EU11 - европейская версия 1.01;
  • GV_UNK - любая другая.

Пример использования

if (CLEO_GetGameVersion() != GV_US10) {
MessageBox(HWND_DESKTOP, "This version of game is not supported.", NULL, MB_ICONERROR);
return FALSE;
}


CLEO_GetIntOpcodeParam

DWORD WINAPI CLEO_GetIntOpcodeParam(CScriptThread* thread);

Описание

Функция считывает из скрипта 1 операнд типа Integer и возвращает его значение.

Параметры

thread указатель на структуру потока.

Пример использования

DWORD param = CLEO_GetIntOpcodeParam(thread);


CLEO_SetIntOpcodeParam

void WINAPI CLEO_SetIntOpcodeParam(CScriptThread* thread, DWORD value);

Описание

Функция записывает в операнд-переменную типа Integer значение, переданное вторым параметром.

Параметры

thread | указатель на структуру потока;
value | записываемое значение.

Пример использования

CLEO_SetIntOpcodeParam(thread, -1);


CLEO_GetFloatOpcodeParam

float WINAPI CLEO_GetFloatOpcodeParam(CScriptThread* thread);

Описание

Функция считывает из скрипта 1 операнд типа Float и возвращает его значение.

Параметры

thread указатель на структуру потока.

Пример использования

float param = CLEO_GetFloatOpcodeParam(thread);


CLEO_SetFloatOpcodeParam

void WINAPI CLEO_SetFloatOpcodeParam(CScriptThread* thread, float value);

Описание

Функция записывает в операнд-переменную типа Float значение, переданное вторым параметром.

Параметры

thread | указатель на структуру потока;
value | записываемое значение.

Пример использования

CLEO_SetFloatOpcodeParam(thread, -1.0f);


CLEO_ReadStringOpcodeParam

LPSTR WINAPI CLEO_ReadStringOpcodeParam(CScriptThread* thread, LPSTR buf, int size);

Описание

Функция считывает из скрипта 1 операнд типа String в буфер и возвращает указатель на этот буфер.

Параметры

thread | указатель на структуру потока;
buf | указатель на строку, в которую будет записан результат. При передаче величины NULL строка из скрипта будет считана во внутренний буфер и возвращен указатель на этот буфер;
size | размер строки в байтах;

Пример использования

char * str = CLEO_ReadStringOpcodeParam(thread, NULL, 0);


CLEO_WriteStringOpcodeParam

void WINAPI CLEO_WriteStringOpcodeParam(CScriptThread* thread, LPCSTR str);

Описание

Функция записывает в операнд-переменную типа String строку, переданную вторым параметром.

Параметры

thread | указатель на структуру потока;
str | указатель на строку, которая будет записана в скриптовую переменную.

Пример использования

CLEO_WriteStringOpcodeParam(thread, "OK");


CLEO_GetOperandType

int WINAPI CLEO_GetOperandType(CScriptThread* thread);

Описание

Функция получает тип операнда для более защищенного доступа к нему.

Параметры

thread указатель на структуру потока.

Возвращаемое значение

Значение | Описание | Пример
globalVar | Глобальная переменная. | $PLAYER_ACTOR
localVar | Локальная переменная. | 0@
globalArr | Массив глобальных элементов. | $Girl_Weapons(0@,12i)
localArr | Массив локальных элементов. | 1@(0@,12i)
imm8 | Целое в диапазоне от -0x80 до 0x7F. | 12
imm16 | Целое в диапазоне от -0x8000 до 0x7FFF. | 260
imm32 | Целое в диапазоне от -0x80000000 до 0x7FFFFFFF. | 0x969110
imm32f | Дробное число, Sanny Builder'ом компилируется как imm32. | 1.5
vstring | Строка переменной длины. | "string"
sstring | Строка фиксированной длины. | 'string'
globalVarVString | Глобальная переменная, длинная строка. | v$12
localVarVString | Локальная переменная, длинная строка. | 0@v
globalVarSString | Глобальная переменная, короткая строка. | s$12
localVarSString | Локальная переменная, короткая строка. | 0@s

Пример использования

switch (CLEO_GetOperandType(thread))
{
case globalVar:
case localVar:
case globalArr:
case localArr:
case imm8:
case imm16:
case imm32:
a = CLEO_GetIntOpcodeParam(thread)
break;
default:
CLEO_SkipOpcodeParams(thread, 1);
}


CLEO_RetrieveOpcodeParams

void WINAPI CLEO_RetrieveOpcodeParams(CScriptThread* thread, int count);

Описание

Функция считывает из скрипта указанное количество операндов (до 32 штук за раз). Результат будет записан в массив opcodeParams. Эту функцию удобно использовать когда необходимо считать сразу несколько параметров из потока.

Параметры

thread | указатель на структуру потока;
count | количество считываемых из потока значений.

Пример использования

float x, y, z;
CLEO_RetrieveOpcodeParams(thread, 3);
x = opcodeParams[0].fParam; y = opcodeParams[1].fParam; z = opcodeParams[2].fParam;


CLEO_RecordOpcodeParams

void WINAPI CLEO_RecordOpcodeParams(CScriptThread* thread, int count);

Описание

Функция записывает в поток указанное количество значений (до 32 штук за раз). Значения считываются из массива opcodeParams. Эту функцию удобно использовать когда необходимо записать сразу несколько параметров в поток.

Параметры

thread | указатель на структуру потока;
count | количество записываемых в поток значений.

Пример использования

opcodeParams[0].fParam = x; opcodeParams[1].fParam = y; opcodeParams[2].fParam = z;
CLEO_RecordOpcodeParams(thread, 3);


CLEO_SetThreadCondResult

void WINAPI CLEO_SetThreadCondResult(CScriptThread* thread, BOOL result);

Описание

Функция устанавливает результат логической операции для условного потока (True или False).

Параметры

thread | указатель на структуру потока;
result | TRUE или FALSE.

Пример использования

CLEO_SetThreadCondResult(thread, a != 0);


CLEO_SkipOpcodeParams

void WINAPI CLEO_SkipOpcodeParams(CScriptThread* thread, int count);

Описание

Функция пропускает указанное количество операндов в скрипте.

Параметры

thread | указатель на структуру потока;
count | количество пропускаемых операндов.

Пример использования

CLEO_SkipOpcodeParams(thread, 1);


CLEO_ThreadJumpAtLabelPtr

void WINAPI CLEO_ThreadJumpAtLabelPtr(CScriptThread* thread, int labelPtr);

Описание

Функция выполняет переход к метке.

Параметры

thread | указатель на структуру потока;
labelPtr | метка для перехода.

Пример использования

CLEO_ThreadJumpAtLabelPtr(thread, CLEO_GetIntOpcodeParam(thread));


Формат обработчика опкода

Обработчик опкода имеет следуюший формат:

OpcodeResult WINAPI opcodeHandler(CScriptThread* thread);

Параметры

thread указатель на структуру потока.

Возвращаемое значение

Функция должна возвращать одно из значений:

OR_CONTINUE | указывает продолжить исполнение текущего скрипта;
OR_INTERRUPT | передает исполнение следующему скрипту в очереди.