CLEO 3 / Опкоды
Пользование следующими опкодами возможно только при установленной библиотеке CLEO 3. При компиляции Sanny Builder проверяет, установлена ли CLEO 3 и при необходимости предупреждает о том, что следует провести ее установку. Если вы написали скрипт с использованием данных опкодов, не забудьте включить в комплект файлы библиотеки или иным способом обеспечить для конечного пользователя работоспособность такого скрипта.Opcode 0A8C Opcode 0A99 Opcode 0AA6 Opcode 0AB3
Opcode 0A8D Opcode 0A9A Opcode 0AA7 Opcode 0AB4
Opcode 0A8E Opcode 0A9B Opcode 0AA8 Opcode 0AB5
Opcode 0A8F Opcode 0A9C Opcode 0AA9 Opcode 0AB6
Opcode 0A90 Opcode 0A9D Opcode 0AAA Opcode 0AB7
Opcode 0A91 Opcode 0A9E Opcode 0AAB Opcode 0AB8
Opcode 0A92 Opcode 0A9F Opcode 0AAC Opcode 0AB9
Opcode 0A93 Opcode 0AA0 Opcode 0AAD Opcode 0ABA
Opcode 0A94 Opcode 0AA1 Opcode 0AAE Opcode 0ABB
Opcode 0A95 Opcode 0AA2 Opcode 0AAF Opcode 0ABD
Opcode 0A96 Opcode 0AA3 Opcode 0AB0 Opcode 0ABE
Opcode 0A97 Opcode 0AA4 Opcode 0AB1 Opcode 0ABF
Opcode 0A98 Opcode 0AA5 Opcode 0AB2 Opcode 0AC0
Опкоды CLEO 2
0A8C: write_memory 0xC0BC15 size 1 value 1 virtual_protect 0
Опкод 0A8C записывает значение по указанному адресу памяти игры.
Параметры:
1 – адрес памяти (любое целое число)
2 – размер записи: 1, 2, 4 байта
3 – значение (любое число)
4 – Virtual Protect: 1 – если нужно сделать адрес памяти записываемым, 0 – если запись идет в перезаписываемый адрес памяти.
0A8D: $result = read_memory 1@ size 4 virtual_protect 0
0A8D читает определенный адрес памяти и записывает результат в переменную.
Параметры:
1 – переменная, в которую будет записан результат чтения (любая переменная или массив)
2 – адрес памяти (любое целое число)
3 – размер области чтения: 1, 2, 4 байта
4 – Virtual Protect: 1 – если нужно сделать адрес памяти читаемым, 0 – если запись идет в читаемый адрес памяти.
0A8E: 4@ = 5@ + 6@ // int
0A8E складывает два целых значения и записывает результат в переменную.
Параметры:
1 – переменная, в которую будет записана сумма (любая переменная или массив)
2 – первое слагаемое (любое целое число)
3 – второе слагаемое (любое целое число)
0A8F: $var = 0@(1@,2i) - 1 // int
0A8F вычитает одно целое значение из другое и записывает результат в переменную.
Параметры:
1 – переменная, в которую будет записана разность (любая переменная или массив)
2 – уменьшаемое (любое целое число)
3 – вычитаемое (любое целое число)
0A90: $var(0@,10i) = 100 * 1@ // int
0A90 перемножает два целых числа и записывает результат в переменную.
Параметры:
1 – переменная, в которую будет записано произведение (любая переменная или массив)
2 – умножаемое число (любое целое число)
3 – множитель (любое целое число)
0A91: $div = 1 / 5 // int
0A91 делит одно целое число на другое и записывает результат в переменную. Остаток от деления отбрасывается.
Параметры:
1 – переменная, в которую будет записано частное (любая переменная или массив)
2 – делимое (любое целое число)
3 – делитель (любое целое число)
0A96: $ActorStruct = actor $PLAYER_ACTOR struct
0A96 записывает в переменную адрес структуры актера в памяти. Структура – это совокупность разных значений, таких как здоровье, координаты и т.д. Зная адрес структуры актера можно читать эти значения, используя опкод 0A8D.
Параметры:
1 – переменная, в которую будет записан адрес структуры
2 – хендл (handle) актера
0A97: $CarStruct = car $MyCar struct
0A97 записывает в переменную адрес структуры машины в памяти.
Параметры:
1 – переменная, в которую будет записан адрес структуры
2 – хендл (handle) машины
0A98: $ObjectStruct = object 0@ struct
0A98 записывает в переменную адрес структуры объекта в памяти.
Параметры:
1 – переменная, в которую будет записан адрес структуры
2 – хендл (handle) объекта
0A99: chdir 0
0A99 меняет глобальный указатель игры на директорию, делая ее директорией по умолчанию.
Параметр:
0 – сделать директорией по умолчанию корневую папку игры
1 – сделать директорией по умолчанию папку с сейвами
0A9A: $hFILE = openfile "settings.ini" mode 0x72 // IF and SET
0A9A открывает файл для чтения и записи. Данный опкод может использоваться и как условие: если файл не был открыт, проверка вернет False, иначе True.
Параметры:
1 – переменная, в которую будет записан указатель на файл
2 – путь к файлу. Если путь локальный, файл ищется относительно текущей директории (см. опкод 0A99).
3 – режим открытия файла:
0x6272 – открыть байтовый файл для чтения
0x72 – открыть текстовый файл для чтения
0x6277 – открыть бинарный файл для записи
0x77 – открыть текстовый файл для записи
0A9B: closefile $hFILE
0A9B закрывает файл и освобождает память.
Параметр: указатель на файл
0A9C: 0@ = file $hFILE size
0A9C записывает в переменную размер файла в байтах.
Параметры:
1 – переменная, в которую будет записан размер файла
2 – указатель на файл
0A9D: readfile $hFILE size 2 to $150
0A9D считывает определенное число байтов из открытого файла и записывает их в область памяти, где находится переменная.
Параметры:
1 – указатель на файл
2 – количество байтов чтения
3 – переменная в которую будет записан результат чтения. Если размер чтения превышает 4 байта, остаток будет записан в следующую переменную (в данном случае в $151).
0A9E: writefile $hFILE size 128 from 0@
0A9E записывает в открытый файл определенное число байтов, начиная адреса по которому находится переменная – последний параметр.
Параметры:
1 – указатель на файл
2 – количество байтов, который будут записаны в файл
3 – переменная, начиная с которой будет вестись запись. Если размер записи превышает 4, будет записано значение следующей переменной и т.д. В данном примере в файл будет записан дамп всех локальных переменных потока (32 переменных по 4 байта = 128 байтов).
0A9F: 0@ = current_thread_pointer
0A9F записывает в переменную адрес структуры текущего потока. Зная этот адрес можно работать напрямую с определенными значениями потока, такими как имя потока, локальные переменные, базовый IP и т.д.
0AA0: gosub_if_false @CREATE_NEW_ACTOR
0AA0 делает gosub, если условие было ложным. В целом данный опкод напоминает 004D: jump_if_false и может использоваться вместо него.
Параметр: метка для перехода
0AA1: return_if_false
0AA1 делает return, если условие было ложным. В целом данный опкод напоминает 004D: jump_if_false и может использоваться вместо него.
0AA2: $hLIB = load_library "CLEO\version.dll" // IF and SET
0AA2 загружает библиотеку DLL по указанному адресу и записывает указатель на нее в переменную. Данный опкод может использоваться и как условие. Если библиотека не была загружена, проверка вернет False, иначе True.
Параметры:
1 – переменная, в которую будет записан указатель на библиотеку (любая локальная или глобальная переменная)
2 – путь к библиотеке. Если указан относительный путь (без указания диска), поиск файла будет вестись относительно текущей активной директории (см. опкод 0A99). Если расширение файла не указано, будет использовано расширение по умолчанию (.DLL).
0AA3: free_library $hLIB
0AA3 выгружает библиотеку из памяти.
Параметр: указатель на библиотеку
0AA4: $hPROC = get_proc_address "GetVersion" library $hLIB // IF and SET
0AA4 ищет в библиотеке процедуру с указанным именем и если находит записывает ее адрес в переменную. Этот адрес может потом быть использован в опкодах типа call. Данный опкод может использоваться и как условие. Если процедура не была найдена, проверка вернет False, иначе True.
Параметры:
1 – переменная, в которую будет записан адрес процедуры.
2 – имя процедуры (строка или стринговая переменная). Обратите внимание, get_proc_address чуствительна к регистру имени. Если процедура импортирована из DLL с именем GetVersion, это значит, что например get_proc_address "getversion” такую процедуру не найдет. Вы должны указывать точное имя. Также помните, что при компиляции Sanny Builder по умолчанию переводит все строки в верхний регистр. Это значит, что данный пример будет скомпилирован как «GETVERSION», и соответственно процедура GetVersion не будет найдена. Чтобы избежать этого, переключите регистр букв в опциях на «Как есть».
3 – указатель на загруженную библиотеку (0AA2)
0AA5: call $hPROC num_params 1 pop 1 $param
0AA5 и подобные ему опкоды имеют переменное количество параметров. Данный опкод имеет минимум 3 параметра, а также дополнительные, число и значение которых зависит от вызываемой процедуры. Общее число таких дополнительных параметров должно соответствовать параметру num_params. Все передаваемые параметры должны быть числовыми (константы или переменные), но не строковыми.
Параметры:
1 – глобальный адрес процедуры. Это может быть адрес в gta_sa.exe или загруженной dll.
2 – число передаваемых в процедуру параметров.
3 – число параметров, которые должны быть убраны со стека после того как отработает вызываемая процедура. Это значение может быть в интервале от 0 до num_params. Точное число зависит от самой вызываемой процедуры. Как правило, отдельные функции в ехе сами не «чистят» за собой стек, поэтому число pop должно быть чаще всего равно num_params.
0AA6: call_method $Destroy struct $CarStruct params 0 pop 0
0AA6 вызывает процедуру для класса. Каждый класс имеет кроме набора значений еще и набор процедур (ближайшее сравнение – классы в SB), которые называются методами. В данном примере мы вызываем метод уничтожения структуры $CarStruct (условно, если $Destroy содержит глобальный адрес такой процедуры в ЕХЕ). С определенными оговорками, можно сказать что это тоже самое, что Car.Destroy($MyCar).
Параметры:
1 – глобальный адрес процедуры. Это может быть адрес в gta_sa.exe или загруженной dll.
2 – указатель на структуру, частью которой является вызываемая процедура. Может быть получен опкодами 0A96 - 0A98.
3 – число передаваемых параметров
4 – число параметров, которые должны быть убраны со стека после того как отработает вызываемый метод. Как правило, методы сами чистят за собой стек и параметр pop должен быть равен 0.
0AA7: call_function 0x569660 num_params 2 pop 2 $COORD_X $COORD_Y $GROUND
0AA7 работает по схожему принципу, что и 0AA5, только дополнительно записывает в переменную результат вызванной функции. Последним параметром всегда должна быть переменная – в нее будет записан результат. num_params таким образом будет на 1 меньше, чем кол-во дополнительных параметров (в данном примере мы вызвали функцию по адресу 0x569660 и передали ей два параметра X и Y, результат функции будет записан в $GROUND).
Параметры:
1 – глобальный адрес процедуры. Это может быть адрес в gta_sa.exe или загруженной dll.
2 – число передаваемых в функцию параметров.
3 – число параметров, которые должны быть убраны со стека после того как отработает вызываемая функция. Это значение может быть в интервале от 0 до num_params. Точное число зависит от самой вызываемой процедуры. Как правило, отдельные функции в ехе сами не «чистят» за собой стек, поэтому число pop должно быть чаще всего равно num_params.
0AA8: call_function_method 0x4048E0 struct 0xB74494 num_params 1 pop 0 $MyCar 0@
0AA8 вызывает функцию из структуры struct и записывает результат в переменную, которая всегда должна идти в конце. Принцип работы схож с опкодами 0AA6 и 0AA7. В данном примере мы вызываем функцию по адресу 0x4048E0 и передаем ей как параметр хендл машины. struct 0xB74494 это структура всех машин в игре. 0x4048E0 – функция, которая переводит хендл в указатель на структуру (аналог опкода 0A97). Полученный указатель будет записан в переменную 0@.
Параметры:
1 – глобальный адрес функции. Это может быть адрес в gta_sa.exe или загруженной dll.
2 – указатель на структуру, частью которой является вызываемая функция. Может быть получен опкодами 0A96 - 0A98.
3 – число передаваемых параметров
4 – число параметров, которые должны быть убраны со стека после того как отработает вызываемый метод. Как правило, методы сами чистят за собой стек и параметр pop должен быть равен 0.
0AA9: is_game_version_original
Данный опкод используется как условие. Если вы работаете в оригинальной версии GTA SA 1.0 проверка вернет True, иначе False. Опкод полезен при написании модов, которые будут работать на разных версиях игры.
0AAB: file_exists "CLEO\version.dll"
0AAB проверяет, существует ли физически указанный файл. Данная проверка является частью опкодов 0A9A и 0AA2 и для них дублировать ее необязательно.
Параметр: путь к файлу. Если указан относительный путь (без указания диска), поиск файла будет вестись относительно текущей активной директории (см. опкод 0A99).
0AAC: $hMP3 = load_mp3 "CLEO\playlist\01.mp3"
0AAC загружает в память mp3-файл и записывает указатель на него в переменную.
Параметры:
1 – переменная, в которую будет записан указатель на загруженный mp3.
2 – путь к mp3-файлу. Если указан относительный путь (без указания диска), поиск файла будет вестись относительно текущей активной директории (см. опкод 0A99).
0AAD: set_mp3 $hMP3 perform_action 1
Данный опкод выполняет одно из заранее определенных действий над загруженным mp3.
Параметры:
1 – указатель на загруженный mp3
2 – число, определяющее одно из выполняемых действий:
0: остановить проигрывание
1: запустить проигрывание файла
2: поставить проигрывание на паузу
3: продолжить проигрывание
0AAE: release_mp3 $hMP3
0AAE выгружает mp3-файл из памяти.
Параметр: указатель на загруженный mp3-файл.
0AAF: 0@ = get_mp3_length $hMP3
Данный опкод записывает в переменную длину mp3-файла в секундах.
Параметры:
1 – переменная, в которую будет записана длина трека
2 – указатель на загруженный mp3-файл
0AB0: key_pressed 0x73
0AB0 используется как условие. Данный опкод проверяет, была ли нажата клавиша на клавиатуре. Если клавиша с указанным номером была нажата, проверка вернет True, иначе False.
Параметр: номер клавиши на клавиатуре. Список virtual_key_codes см. здесь
Опкоды CLEO 3
0A92: create_custom_thread "ShowTextBox.s"
0A92 создает поток из указанного файла. Обратите внимание, что если файл имеет расширение .cs, поток из этого файла будет создан автоматически при старте игры. При создании потока опкодом 0A92 можно передать в него до 34 параметров, как в опкоде 004F.
Параметр: путь к файлу. Имя файла должно быть указано полностью с расширением (если таковое имеется). Поиск файла ведется относительно папки ‘игра\CLEO’.
0A93: end_custom_thread
0A93 останавливает текущий CLEO-поток. Данный опкод должен использоваться только внутри файлов с CLEO-потоками (не CLEO-миссиями и не в main.scm). В целом данный опкод является аналогом опкода 004E.
Для остановки CLEO-миссии используйте опкод 004E.
0A94: start_custom_mission "missions\CustomMission1"
0A94 стартует CLEO-миссию из указанного файла аналогично опкоду 0417. Обратите внимание, что расширение указывать не надо. В действительности опкод будет искать файл с расширением .cm (Custom Mission). В данном примере миссия будет запущена из файла CLEO\missions\CustomMission1.cm
Параметр: путь к файлу. Имя файла должно быть без расширения. Поиск файла ведется относительно папки ‘игра\CLEO’.
0A95: enable_thread_saving
0A95 устанавливает флаг сохранения для текущего CLEO-потока. По умолчанию CLEO-потоки не сохраняются в CLEO-сейве, а при запуске игры начинают работу с самого начала. Для того чтобы сохранить в сейве статус потока, его переменные и т.п., добавьте этот опкод в самое начало скрипта.
0AAA: 0@ = thread 'OTB' pointer
Данный опкод проверяет, активен ли поток с указанным именем. Если он активен, в переменную записывается адрес данного потока. Если поток с указанным именем не был найден в памяти игры, в переменную будет записано число 0.
Параметры:
1 - имя переменной, в которую будет записан результат поиска
2 - имя потока для поиска
0AB1: call_scm_func @GetSQR 1 10 $result
Данный опкод вызывает код из SCM, передает в него параметры и получает результат. Передаваемые параметры последовательно копируются в локальные переменные, затем поток переходит на указанную метку, выполняет код по данной метке и возвращается после опкода 0AB2.
Параметры:
1 – имя метки (начало SCM-функции)
2 – количество передаваемых параметров
После этого идут передаваемые параметры, в данном случае число 10. После этого должны стоять переменные, в которые будет записан результат (см. 0AB2).
0AB2: ret 1 0@
Данный опкод возвращает поток на опкод 0AB1 и записывает значения в его результирующие переменные. Общее число возвращаемых значений обязательно должно соответствовать числу переменных в опкоде 0AB1. В данном примере опкод 0AB2 вернет одно значение, которое содержится в переменной 0@ и это значение будет записано в переменную $result (см. 0AB1). Если 0AB2 не возвращает значений, в нем должен стоять ноль как единственный параметр, а 0AB1 не должен иметь переменных для приема.
Параметры:
1 – количество возвращаемых значений
После этого идут возвращаемые значения, в данном случае значение переменной 0@.
Вот простой пример оформления SCM-функции получения квадрата числа.
0@ = 5
0AB1: call_scm_func @GetSQR 1 10 $result
end_thread
…..
: GetSQR
006A: 0@ *= 0@
0AB2: ret 1 0@
Объясню механизм работы. Сперва игра приходит на опкод 0AB1. После этого читаются передаваемые параметры – в данном случае он один и равен 10. Переменная 0@ текущего потока приравнивается к 10 (если бы число параметров было больше, следующее значение было бы записано в 1@, потом 2@ и т.д.). После этого поток переходит на метку GetSQR. Здесь происходит вычисление квадрата числа (параметра в 0@). Опять-таки, если бы функция была сложнее, то могли бы еще учитываться переменные 1@ (второй переданный параметр) и т.д. После вычислений игра переходит на опкод 0AB2. Значение 0@ в этот момент равно 10*10 = 100. Игра читает, сколько значений нужно вернуть (в данном примере 1, см. 0AB2). После этого происходит следующее: возвращаемое значение (0@) записывается в те переменные, которые стоят в опкоде 0AB1, вызвавшем данную функцию. В этом примере это переменная $result. После записи значения, поток возвращается обратно к опкоду 0AB1 и переходит на команду end_thread. Значение переменной $result в этот момент равно 100.
Напоследок скажу, что 0AB2 может возвращать не только значения переменных, но и числовые константы. Например, 0AB2: ret 1 1 всегда будет записывать в результат 1.
Также обратите внимание, что сами значения локальных переменных после вызова функции не меняются! В данном примере, перед опкодом 0AB1 переменная 0@ была равна 5. Несмотря на то, что она использовалась в вычислениях внутри функции, после вызова она будет по-прежнему равна 5. Это распространяется на все 32 локальные переменные, поэтому вы можете свободно работать с ними внутри функции, не боясь потери данных.
0AB3: var 0 = 10
0AB3 устанавливает значение глобальной CLEO-переменной. Эти переменные могут использоваться для обмена данными между CLEO-потоками, а также между CLEO и main.scm. Общее число таких переменных равно 1000. Их значения сохраняются в CLEO-сейве.
Такие переменные могут использоваться и в самом main.scm как альтернатива простым глобальным переменным.
Параметры:
1 – ID глобальной переменной. Должно быть в интервале 0..999.
2 – значение глобальной переменной (любое число, целое или дробное).
0AB4: 0@= var 0
0AB4 записывает в переменную значение глобальной CLEO-переменной. В данном примере 0@ будет равно 10 (см. опкод 0AB3).
Параметры:
1 – переменная, в которую будет записано значение глобальной CLEO-переменной.
2 – ID глобальной переменной. Должно быть в интервале 0..999.
0AB5: store_actor $PLAYER_ACTOR closest_vehicle_to 0@ closest_ped_to 1@
Данный опкод записывает в переменные хэндлы ближайших к актеру машины и прохожего. Если близко к актеру нет ни одной машины или прохожего, в соответствующую переменную будет записано -1.
Параметры:
1 – хендл актера
2 – переменная, в которую будет записан хендл ближайшей машины
3 – переменная, в которую будет записан хендл ближайшего прохожего
0AB6: store_target_marker_coords_to 0@ 1@ 2@ // IF and SET
Этот опкод записывает в переменные координаты места, отмеченного на карте красным маркером цели (правый клик по карте). Если этой отметки на карте нет, значения переменных не изменятся.
Параметры:
1,2,3 – переменные, в которые будут записаны координаты XYZ
0AB7: get_vehicle $CAR number_of_gears_to 10@
Опкод 0AB7 записывает в переменную общее число передач в коробке передач данной машины. Это число соответствует параметру TransmissionData.nNumberOfGears в файле handling.cfg.
Параметры:
1 – хендл машины
2 – переменная, в которую будет записано число передач
0AB8: get_vehicle $CAR current_gear_to 11@
Данный опкод записывает в переменную номер текущей передачи в коробке передач машины.
Параметры:
1 – хендл машины
2 – переменная, в которую будет записана текущая передача
0AB9: get_mp3 $hMP3 state_to 7@
Данный опкод записывает в переменную состояние mp3-файла.
Параметры:
1 – хендл загруженного mp3 (опкод 0AAC)
2 – переменная, в которую будет записана состояние mp3:
1 – файл проигрывается
2 – файл на паузе
-1 – файл остановлен
0ABA: end_custom_thread_named 'BENZIN'
0ABA завершает CLEO-поток с указанным именем. Имя потоку дается опкодом 03A4. Если имя потоку не было задано опкодом 03A4, поток получает имя по первым 7 буквам названия файла. Например, поток из файла test.cs будет иметь имя 'test.cs', из файла myscript.cs - 'myscrip'. Опкод 0ABA немедленно прекращает работу потока с указанным именем. Этот опкод аналогичен опкоду 0459, но предназначен для CLEO-скриптов.
Параметры:
1 - имя потока
0ABD: vehicle 0@ siren_on
0ABD 0ABD проверяет, включена ли сирена на машине 0@. Если сирена включена, проверка вернет True.
Параметры:
1 - хендл машины
0ABE: vehicle 0@ engine_on
0ABE проверяет, запущен ли двигатель на машине 0@. Если двигатель запущен, проверка вернет True.
Параметры:
1 - хендл машины
0ABF: set_vehicle 0@ engine_state_to 0
0ABF устанавливает режим двигателя: выключен, включен.
Параметры:
1 - хендл машины
2 - режим двигателя:
0 - выключить двигатель
1 - включить двигатель
Пользование следующими опкодами возможно только при установленной библиотеке CLEO 3. При компиляции Sanny Builder проверяет, установлена ли CLEO 3 и при необходимости предупреждает о том, что следует провести ее установку. Если вы написали скрипт с использованием данных опкодов, не забудьте включить в комплект файлы библиотеки или иным способом обеспечить для конечного пользователя работоспособность такого скрипта.Opcode 0A8C Opcode 0A99 Opcode 0AA6 Opcode 0AB3
Opcode 0A8D Opcode 0A9A Opcode 0AA7 Opcode 0AB4
Opcode 0A8E Opcode 0A9B Opcode 0AA8 Opcode 0AB5
Opcode 0A8F Opcode 0A9C Opcode 0AA9 Opcode 0AB6
Opcode 0A90 Opcode 0A9D Opcode 0AAA Opcode 0AB7
Opcode 0A91 Opcode 0A9E Opcode 0AAB Opcode 0AB8
Opcode 0A92 Opcode 0A9F Opcode 0AAC Opcode 0AB9
Opcode 0A93 Opcode 0AA0 Opcode 0AAD Opcode 0ABA
Opcode 0A94 Opcode 0AA1 Opcode 0AAE Opcode 0ABB
Opcode 0A95 Opcode 0AA2 Opcode 0AAF Opcode 0ABD
Opcode 0A96 Opcode 0AA3 Opcode 0AB0 Opcode 0ABE
Opcode 0A97 Opcode 0AA4 Opcode 0AB1 Opcode 0ABF
Opcode 0A98 Opcode 0AA5 Opcode 0AB2 Opcode 0AC0
Опкоды CLEO 2
0A8C: write_memory 0xC0BC15 size 1 value 1 virtual_protect 0
Опкод 0A8C записывает значение по указанному адресу памяти игры.
Параметры:
1 – адрес памяти (любое целое число)
2 – размер записи: 1, 2, 4 байта
3 – значение (любое число)
4 – Virtual Protect: 1 – если нужно сделать адрес памяти записываемым, 0 – если запись идет в перезаписываемый адрес памяти.
0A8D: $result = read_memory 1@ size 4 virtual_protect 0
0A8D читает определенный адрес памяти и записывает результат в переменную.
Параметры:
1 – переменная, в которую будет записан результат чтения (любая переменная или массив)
2 – адрес памяти (любое целое число)
3 – размер области чтения: 1, 2, 4 байта
4 – Virtual Protect: 1 – если нужно сделать адрес памяти читаемым, 0 – если запись идет в читаемый адрес памяти.
0A8E: 4@ = 5@ + 6@ // int
0A8E складывает два целых значения и записывает результат в переменную.
Параметры:
1 – переменная, в которую будет записана сумма (любая переменная или массив)
2 – первое слагаемое (любое целое число)
3 – второе слагаемое (любое целое число)
0A8F: $var = 0@(1@,2i) - 1 // int
0A8F вычитает одно целое значение из другое и записывает результат в переменную.
Параметры:
1 – переменная, в которую будет записана разность (любая переменная или массив)
2 – уменьшаемое (любое целое число)
3 – вычитаемое (любое целое число)
0A90: $var(0@,10i) = 100 * 1@ // int
0A90 перемножает два целых числа и записывает результат в переменную.
Параметры:
1 – переменная, в которую будет записано произведение (любая переменная или массив)
2 – умножаемое число (любое целое число)
3 – множитель (любое целое число)
0A91: $div = 1 / 5 // int
0A91 делит одно целое число на другое и записывает результат в переменную. Остаток от деления отбрасывается.
Параметры:
1 – переменная, в которую будет записано частное (любая переменная или массив)
2 – делимое (любое целое число)
3 – делитель (любое целое число)
0A96: $ActorStruct = actor $PLAYER_ACTOR struct
0A96 записывает в переменную адрес структуры актера в памяти. Структура – это совокупность разных значений, таких как здоровье, координаты и т.д. Зная адрес структуры актера можно читать эти значения, используя опкод 0A8D.
Параметры:
1 – переменная, в которую будет записан адрес структуры
2 – хендл (handle) актера
0A97: $CarStruct = car $MyCar struct
0A97 записывает в переменную адрес структуры машины в памяти.
Параметры:
1 – переменная, в которую будет записан адрес структуры
2 – хендл (handle) машины
0A98: $ObjectStruct = object 0@ struct
0A98 записывает в переменную адрес структуры объекта в памяти.
Параметры:
1 – переменная, в которую будет записан адрес структуры
2 – хендл (handle) объекта
0A99: chdir 0
0A99 меняет глобальный указатель игры на директорию, делая ее директорией по умолчанию.
Параметр:
0 – сделать директорией по умолчанию корневую папку игры
1 – сделать директорией по умолчанию папку с сейвами
0A9A: $hFILE = openfile "settings.ini" mode 0x72 // IF and SET
0A9A открывает файл для чтения и записи. Данный опкод может использоваться и как условие: если файл не был открыт, проверка вернет False, иначе True.
Параметры:
1 – переменная, в которую будет записан указатель на файл
2 – путь к файлу. Если путь локальный, файл ищется относительно текущей директории (см. опкод 0A99).
3 – режим открытия файла:
0x6272 – открыть байтовый файл для чтения
0x72 – открыть текстовый файл для чтения
0x6277 – открыть бинарный файл для записи
0x77 – открыть текстовый файл для записи
0A9B: closefile $hFILE
0A9B закрывает файл и освобождает память.
Параметр: указатель на файл
0A9C: 0@ = file $hFILE size
0A9C записывает в переменную размер файла в байтах.
Параметры:
1 – переменная, в которую будет записан размер файла
2 – указатель на файл
0A9D: readfile $hFILE size 2 to $150
0A9D считывает определенное число байтов из открытого файла и записывает их в область памяти, где находится переменная.
Параметры:
1 – указатель на файл
2 – количество байтов чтения
3 – переменная в которую будет записан результат чтения. Если размер чтения превышает 4 байта, остаток будет записан в следующую переменную (в данном случае в $151).
0A9E: writefile $hFILE size 128 from 0@
0A9E записывает в открытый файл определенное число байтов, начиная адреса по которому находится переменная – последний параметр.
Параметры:
1 – указатель на файл
2 – количество байтов, который будут записаны в файл
3 – переменная, начиная с которой будет вестись запись. Если размер записи превышает 4, будет записано значение следующей переменной и т.д. В данном примере в файл будет записан дамп всех локальных переменных потока (32 переменных по 4 байта = 128 байтов).
0A9F: 0@ = current_thread_pointer
0A9F записывает в переменную адрес структуры текущего потока. Зная этот адрес можно работать напрямую с определенными значениями потока, такими как имя потока, локальные переменные, базовый IP и т.д.
0AA0: gosub_if_false @CREATE_NEW_ACTOR
0AA0 делает gosub, если условие было ложным. В целом данный опкод напоминает 004D: jump_if_false и может использоваться вместо него.
Параметр: метка для перехода
0AA1: return_if_false
0AA1 делает return, если условие было ложным. В целом данный опкод напоминает 004D: jump_if_false и может использоваться вместо него.
0AA2: $hLIB = load_library "CLEO\version.dll" // IF and SET
0AA2 загружает библиотеку DLL по указанному адресу и записывает указатель на нее в переменную. Данный опкод может использоваться и как условие. Если библиотека не была загружена, проверка вернет False, иначе True.
Параметры:
1 – переменная, в которую будет записан указатель на библиотеку (любая локальная или глобальная переменная)
2 – путь к библиотеке. Если указан относительный путь (без указания диска), поиск файла будет вестись относительно текущей активной директории (см. опкод 0A99). Если расширение файла не указано, будет использовано расширение по умолчанию (.DLL).
0AA3: free_library $hLIB
0AA3 выгружает библиотеку из памяти.
Параметр: указатель на библиотеку
0AA4: $hPROC = get_proc_address "GetVersion" library $hLIB // IF and SET
0AA4 ищет в библиотеке процедуру с указанным именем и если находит записывает ее адрес в переменную. Этот адрес может потом быть использован в опкодах типа call. Данный опкод может использоваться и как условие. Если процедура не была найдена, проверка вернет False, иначе True.
Параметры:
1 – переменная, в которую будет записан адрес процедуры.
2 – имя процедуры (строка или стринговая переменная). Обратите внимание, get_proc_address чуствительна к регистру имени. Если процедура импортирована из DLL с именем GetVersion, это значит, что например get_proc_address "getversion” такую процедуру не найдет. Вы должны указывать точное имя. Также помните, что при компиляции Sanny Builder по умолчанию переводит все строки в верхний регистр. Это значит, что данный пример будет скомпилирован как «GETVERSION», и соответственно процедура GetVersion не будет найдена. Чтобы избежать этого, переключите регистр букв в опциях на «Как есть».
3 – указатель на загруженную библиотеку (0AA2)
0AA5: call $hPROC num_params 1 pop 1 $param
0AA5 и подобные ему опкоды имеют переменное количество параметров. Данный опкод имеет минимум 3 параметра, а также дополнительные, число и значение которых зависит от вызываемой процедуры. Общее число таких дополнительных параметров должно соответствовать параметру num_params. Все передаваемые параметры должны быть числовыми (константы или переменные), но не строковыми.
Параметры:
1 – глобальный адрес процедуры. Это может быть адрес в gta_sa.exe или загруженной dll.
2 – число передаваемых в процедуру параметров.
3 – число параметров, которые должны быть убраны со стека после того как отработает вызываемая процедура. Это значение может быть в интервале от 0 до num_params. Точное число зависит от самой вызываемой процедуры. Как правило, отдельные функции в ехе сами не «чистят» за собой стек, поэтому число pop должно быть чаще всего равно num_params.
0AA6: call_method $Destroy struct $CarStruct params 0 pop 0
0AA6 вызывает процедуру для класса. Каждый класс имеет кроме набора значений еще и набор процедур (ближайшее сравнение – классы в SB), которые называются методами. В данном примере мы вызываем метод уничтожения структуры $CarStruct (условно, если $Destroy содержит глобальный адрес такой процедуры в ЕХЕ). С определенными оговорками, можно сказать что это тоже самое, что Car.Destroy($MyCar).
Параметры:
1 – глобальный адрес процедуры. Это может быть адрес в gta_sa.exe или загруженной dll.
2 – указатель на структуру, частью которой является вызываемая процедура. Может быть получен опкодами 0A96 - 0A98.
3 – число передаваемых параметров
4 – число параметров, которые должны быть убраны со стека после того как отработает вызываемый метод. Как правило, методы сами чистят за собой стек и параметр pop должен быть равен 0.
0AA7: call_function 0x569660 num_params 2 pop 2 $COORD_X $COORD_Y $GROUND
0AA7 работает по схожему принципу, что и 0AA5, только дополнительно записывает в переменную результат вызванной функции. Последним параметром всегда должна быть переменная – в нее будет записан результат. num_params таким образом будет на 1 меньше, чем кол-во дополнительных параметров (в данном примере мы вызвали функцию по адресу 0x569660 и передали ей два параметра X и Y, результат функции будет записан в $GROUND).
Параметры:
1 – глобальный адрес процедуры. Это может быть адрес в gta_sa.exe или загруженной dll.
2 – число передаваемых в функцию параметров.
3 – число параметров, которые должны быть убраны со стека после того как отработает вызываемая функция. Это значение может быть в интервале от 0 до num_params. Точное число зависит от самой вызываемой процедуры. Как правило, отдельные функции в ехе сами не «чистят» за собой стек, поэтому число pop должно быть чаще всего равно num_params.
0AA8: call_function_method 0x4048E0 struct 0xB74494 num_params 1 pop 0 $MyCar 0@
0AA8 вызывает функцию из структуры struct и записывает результат в переменную, которая всегда должна идти в конце. Принцип работы схож с опкодами 0AA6 и 0AA7. В данном примере мы вызываем функцию по адресу 0x4048E0 и передаем ей как параметр хендл машины. struct 0xB74494 это структура всех машин в игре. 0x4048E0 – функция, которая переводит хендл в указатель на структуру (аналог опкода 0A97). Полученный указатель будет записан в переменную 0@.
Параметры:
1 – глобальный адрес функции. Это может быть адрес в gta_sa.exe или загруженной dll.
2 – указатель на структуру, частью которой является вызываемая функция. Может быть получен опкодами 0A96 - 0A98.
3 – число передаваемых параметров
4 – число параметров, которые должны быть убраны со стека после того как отработает вызываемый метод. Как правило, методы сами чистят за собой стек и параметр pop должен быть равен 0.
0AA9: is_game_version_original
Данный опкод используется как условие. Если вы работаете в оригинальной версии GTA SA 1.0 проверка вернет True, иначе False. Опкод полезен при написании модов, которые будут работать на разных версиях игры.
0AAB: file_exists "CLEO\version.dll"
0AAB проверяет, существует ли физически указанный файл. Данная проверка является частью опкодов 0A9A и 0AA2 и для них дублировать ее необязательно.
Параметр: путь к файлу. Если указан относительный путь (без указания диска), поиск файла будет вестись относительно текущей активной директории (см. опкод 0A99).
0AAC: $hMP3 = load_mp3 "CLEO\playlist\01.mp3"
0AAC загружает в память mp3-файл и записывает указатель на него в переменную.
Параметры:
1 – переменная, в которую будет записан указатель на загруженный mp3.
2 – путь к mp3-файлу. Если указан относительный путь (без указания диска), поиск файла будет вестись относительно текущей активной директории (см. опкод 0A99).
0AAD: set_mp3 $hMP3 perform_action 1
Данный опкод выполняет одно из заранее определенных действий над загруженным mp3.
Параметры:
1 – указатель на загруженный mp3
2 – число, определяющее одно из выполняемых действий:
0: остановить проигрывание
1: запустить проигрывание файла
2: поставить проигрывание на паузу
3: продолжить проигрывание
0AAE: release_mp3 $hMP3
0AAE выгружает mp3-файл из памяти.
Параметр: указатель на загруженный mp3-файл.
0AAF: 0@ = get_mp3_length $hMP3
Данный опкод записывает в переменную длину mp3-файла в секундах.
Параметры:
1 – переменная, в которую будет записана длина трека
2 – указатель на загруженный mp3-файл
0AB0: key_pressed 0x73
0AB0 используется как условие. Данный опкод проверяет, была ли нажата клавиша на клавиатуре. Если клавиша с указанным номером была нажата, проверка вернет True, иначе False.
Параметр: номер клавиши на клавиатуре. Список virtual_key_codes см. здесь
Опкоды CLEO 3
0A92: create_custom_thread "ShowTextBox.s"
0A92 создает поток из указанного файла. Обратите внимание, что если файл имеет расширение .cs, поток из этого файла будет создан автоматически при старте игры. При создании потока опкодом 0A92 можно передать в него до 34 параметров, как в опкоде 004F.
Параметр: путь к файлу. Имя файла должно быть указано полностью с расширением (если таковое имеется). Поиск файла ведется относительно папки ‘игра\CLEO’.
0A93: end_custom_thread
0A93 останавливает текущий CLEO-поток. Данный опкод должен использоваться только внутри файлов с CLEO-потоками (не CLEO-миссиями и не в main.scm). В целом данный опкод является аналогом опкода 004E.
Для остановки CLEO-миссии используйте опкод 004E.
0A94: start_custom_mission "missions\CustomMission1"
0A94 стартует CLEO-миссию из указанного файла аналогично опкоду 0417. Обратите внимание, что расширение указывать не надо. В действительности опкод будет искать файл с расширением .cm (Custom Mission). В данном примере миссия будет запущена из файла CLEO\missions\CustomMission1.cm
Параметр: путь к файлу. Имя файла должно быть без расширения. Поиск файла ведется относительно папки ‘игра\CLEO’.
0A95: enable_thread_saving
0A95 устанавливает флаг сохранения для текущего CLEO-потока. По умолчанию CLEO-потоки не сохраняются в CLEO-сейве, а при запуске игры начинают работу с самого начала. Для того чтобы сохранить в сейве статус потока, его переменные и т.п., добавьте этот опкод в самое начало скрипта.
0AAA: 0@ = thread 'OTB' pointer
Данный опкод проверяет, активен ли поток с указанным именем. Если он активен, в переменную записывается адрес данного потока. Если поток с указанным именем не был найден в памяти игры, в переменную будет записано число 0.
Параметры:
1 - имя переменной, в которую будет записан результат поиска
2 - имя потока для поиска
0AB1: call_scm_func @GetSQR 1 10 $result
Данный опкод вызывает код из SCM, передает в него параметры и получает результат. Передаваемые параметры последовательно копируются в локальные переменные, затем поток переходит на указанную метку, выполняет код по данной метке и возвращается после опкода 0AB2.
Параметры:
1 – имя метки (начало SCM-функции)
2 – количество передаваемых параметров
После этого идут передаваемые параметры, в данном случае число 10. После этого должны стоять переменные, в которые будет записан результат (см. 0AB2).
0AB2: ret 1 0@
Данный опкод возвращает поток на опкод 0AB1 и записывает значения в его результирующие переменные. Общее число возвращаемых значений обязательно должно соответствовать числу переменных в опкоде 0AB1. В данном примере опкод 0AB2 вернет одно значение, которое содержится в переменной 0@ и это значение будет записано в переменную $result (см. 0AB1). Если 0AB2 не возвращает значений, в нем должен стоять ноль как единственный параметр, а 0AB1 не должен иметь переменных для приема.
Параметры:
1 – количество возвращаемых значений
После этого идут возвращаемые значения, в данном случае значение переменной 0@.
Вот простой пример оформления SCM-функции получения квадрата числа.
0@ = 5
0AB1: call_scm_func @GetSQR 1 10 $result
end_thread
…..
: GetSQR
006A: 0@ *= 0@
0AB2: ret 1 0@
Объясню механизм работы. Сперва игра приходит на опкод 0AB1. После этого читаются передаваемые параметры – в данном случае он один и равен 10. Переменная 0@ текущего потока приравнивается к 10 (если бы число параметров было больше, следующее значение было бы записано в 1@, потом 2@ и т.д.). После этого поток переходит на метку GetSQR. Здесь происходит вычисление квадрата числа (параметра в 0@). Опять-таки, если бы функция была сложнее, то могли бы еще учитываться переменные 1@ (второй переданный параметр) и т.д. После вычислений игра переходит на опкод 0AB2. Значение 0@ в этот момент равно 10*10 = 100. Игра читает, сколько значений нужно вернуть (в данном примере 1, см. 0AB2). После этого происходит следующее: возвращаемое значение (0@) записывается в те переменные, которые стоят в опкоде 0AB1, вызвавшем данную функцию. В этом примере это переменная $result. После записи значения, поток возвращается обратно к опкоду 0AB1 и переходит на команду end_thread. Значение переменной $result в этот момент равно 100.
Напоследок скажу, что 0AB2 может возвращать не только значения переменных, но и числовые константы. Например, 0AB2: ret 1 1 всегда будет записывать в результат 1.
Также обратите внимание, что сами значения локальных переменных после вызова функции не меняются! В данном примере, перед опкодом 0AB1 переменная 0@ была равна 5. Несмотря на то, что она использовалась в вычислениях внутри функции, после вызова она будет по-прежнему равна 5. Это распространяется на все 32 локальные переменные, поэтому вы можете свободно работать с ними внутри функции, не боясь потери данных.
0AB3: var 0 = 10
0AB3 устанавливает значение глобальной CLEO-переменной. Эти переменные могут использоваться для обмена данными между CLEO-потоками, а также между CLEO и main.scm. Общее число таких переменных равно 1000. Их значения сохраняются в CLEO-сейве.
Такие переменные могут использоваться и в самом main.scm как альтернатива простым глобальным переменным.
Параметры:
1 – ID глобальной переменной. Должно быть в интервале 0..999.
2 – значение глобальной переменной (любое число, целое или дробное).
0AB4: 0@= var 0
0AB4 записывает в переменную значение глобальной CLEO-переменной. В данном примере 0@ будет равно 10 (см. опкод 0AB3).
Параметры:
1 – переменная, в которую будет записано значение глобальной CLEO-переменной.
2 – ID глобальной переменной. Должно быть в интервале 0..999.
0AB5: store_actor $PLAYER_ACTOR closest_vehicle_to 0@ closest_ped_to 1@
Данный опкод записывает в переменные хэндлы ближайших к актеру машины и прохожего. Если близко к актеру нет ни одной машины или прохожего, в соответствующую переменную будет записано -1.
Параметры:
1 – хендл актера
2 – переменная, в которую будет записан хендл ближайшей машины
3 – переменная, в которую будет записан хендл ближайшего прохожего
0AB6: store_target_marker_coords_to 0@ 1@ 2@ // IF and SET
Этот опкод записывает в переменные координаты места, отмеченного на карте красным маркером цели (правый клик по карте). Если этой отметки на карте нет, значения переменных не изменятся.
Параметры:
1,2,3 – переменные, в которые будут записаны координаты XYZ
0AB7: get_vehicle $CAR number_of_gears_to 10@
Опкод 0AB7 записывает в переменную общее число передач в коробке передач данной машины. Это число соответствует параметру TransmissionData.nNumberOfGears в файле handling.cfg.
Параметры:
1 – хендл машины
2 – переменная, в которую будет записано число передач
0AB8: get_vehicle $CAR current_gear_to 11@
Данный опкод записывает в переменную номер текущей передачи в коробке передач машины.
Параметры:
1 – хендл машины
2 – переменная, в которую будет записана текущая передача
0AB9: get_mp3 $hMP3 state_to 7@
Данный опкод записывает в переменную состояние mp3-файла.
Параметры:
1 – хендл загруженного mp3 (опкод 0AAC)
2 – переменная, в которую будет записана состояние mp3:
1 – файл проигрывается
2 – файл на паузе
-1 – файл остановлен
0ABA: end_custom_thread_named 'BENZIN'
0ABA завершает CLEO-поток с указанным именем. Имя потоку дается опкодом 03A4. Если имя потоку не было задано опкодом 03A4, поток получает имя по первым 7 буквам названия файла. Например, поток из файла test.cs будет иметь имя 'test.cs', из файла myscript.cs - 'myscrip'. Опкод 0ABA немедленно прекращает работу потока с указанным именем. Этот опкод аналогичен опкоду 0459, но предназначен для CLEO-скриптов.
Параметры:
1 - имя потока
0ABD: vehicle 0@ siren_on
0ABD 0ABD проверяет, включена ли сирена на машине 0@. Если сирена включена, проверка вернет True.
Параметры:
1 - хендл машины
0ABE: vehicle 0@ engine_on
0ABE проверяет, запущен ли двигатель на машине 0@. Если двигатель запущен, проверка вернет True.
Параметры:
1 - хендл машины
0ABF: set_vehicle 0@ engine_state_to 0
0ABF устанавливает режим двигателя: выключен, включен.
Параметры:
1 - хендл машины
2 - режим двигателя:
0 - выключить двигатель
1 - включить двигатель
