CLEO Redux

• Начало

  • Что такое CLEO Redux?
  • Поддерживаемые языки
  • Поддерживаемые релизы
  • Связь с CLEO Library
    • Запуск CLEO Redux как отдельного ПО
    • Запуск CLEO Redux в качестве дополнения к библиотеке CLEO

• Установка

  • Первичная настройка
  • Совместимость с re3 и reVC
  • Совместимость с The Trilogy: The Definitive Edition
  • Удаление

• Конфигурация

  • Общая конфигурация
  • Разрешения
    • Все
    • Слабые
    • Строгие
    • Исключения

• Лог

• Пользовательские сценарии

  • Добавление нового скрипта
  • Удаление скрипта
  • Пользовательские команды
  • Написание CS-скриптов
  • Написание JS-скриптов
  • Интеграция с Visual Studio Code

• Поддержка JavaScript

  • Предварительное условие
  • Жизненный цикл скрипта
  • Собственные команды
    • Класс ScriptObject против объекта
    • Мат. классы
    • Свободный интерфейс
    • Примеры
  • Импорт
  • Пользовательские привязки
  • Устаревшие

• Пользовательский текст

• Особенности разработки

  • Лог SCM
  • Горячая перезагрузка
  • SDK

• Лицензия

Начало

Что такое CLEO Redux?

CLEO Redux — это среда выполнения сценариев для игр эпохи GTA 3D. Это полноценный член семейства CLEO, который предоставляет знакомый опыт всем, кто использовал библиотеку CLEO для классической GTA San Andreas или ее повторные реализации для других игр. Основная цель CLEO — предоставить возможность легко настраивать игру с помощью многочисленных пользовательских скриптов.

Если вы новичок в CLEO, посетите официальный сайт, чтобы найти больше информации об этом.

Поддерживаемые языки

CLEO Redux поддерживает скомпилированные бинарные скрипты (*.cs) в родном формате SCM и простые текстовые скрипты (*.js), написанные на JavaScript.

CLEO Redux ориентируется на JavaScript как на основной язык для пользовательских скриптов. JavaScript — популярный язык программирования с богатой экосистемой и большим количеством доступной информации. Он свободен от ограничений и ловушек языка SCM, таких как отсутствие поддержки функций, массивов или малое количество переменных.

Поддерживаемые релизы

Классические:

• GTA III 1.0
• GTA Vice City 1.0
• GTA San Andreas 1.0 (только с CLEO 4.4)

Ремастеры (The Trilogy):

• GTA III 1.0.0.14718
• GTA Vice City 1.0.0.14718
• San Andreas 1.0.0.14296, 1.0.0.14388, 1.0.0.14718 (Название обновления 1.03)

Подробнее см. Часто задаваемые вопросы по окончательному изданию.

Остальные:

• re3 (см. Сведения о совместимости)
• reVC (см. Сведения о совместимости)

CLEO Redux поддерживает только ПК-версию каждой игры.

Для получения полной информации о поддерживаемых функциях обратитесь к этой странице. Также существуют известные ограничения перечислены здесь.

Связь с CLEO Library

CLEO — это общее название пользовательских библиотек, разработанных и созданных для GTA III, Vice City или San Andreas. Каждую версию можно найти и скачать здесь. CLEO Redux — это другая реализация CLEO, созданная с нуля, с несколькими отличительными особенностями, такими как единая кодовая база для всех игр или поддержка кода JavaScript.

На данный момент CLEO Redux не может рассматриваться как полноценная замена CLEO Library из-за отсутствия поддержки многих широко используемых CLEO-команд. Чтобы решить эту проблему и получить максимальную отдачу от двух библиотек, CLEO Redux поддерживает две разные стратегии использования.

CLEO Redux может работать как отдельное ПО или как дополнение к CLEO Library. В первом случае ваша директория с игрой будет содержать только файл cleo_redux.asi (или cleo_redux64.asi). Во втором случае в вашем каталоге с игрой будут и cleo.asi (или III.CLEO.asi, и VC.CLEO.asi), и cleo_redux.asi (или cleo_redux64.asi).

Запуск CLEO Redux как отдельного ПО

Как отдельное ПО CLEO Redux запускает скомпилированные скрипты и JavaScript и предоставляет доступ ко всем командам собственного скрипта. Он также предоставляет ограниченный набор настраиваемых команд, обратно совместимых с библиотекой CLEO. Существующие CLEO-скрипты могут не работать, если они используют пользовательские команды (например, из стороннего плагина), не поддерживаемые CLEO Redux.

Этот режим не работает в классической GTA San Andreas.

Запуск CLEO Redux в качестве дополнения к библиотеке CLEO

В качестве дополнения CLEO Redux работает вместе с CLEO Library, делегируя ему всю заботу о пользовательских скриптах. Это означает, что все пользовательские скрипты и плагины, созданные для библиотеки CLEO, будут продолжать работать точно так же. CLEO Redux управляет только JS-скриптами. Все пользовательские команды становятся доступными для среды выполнения JavaScript, что означает, что вы можете использовать команды, которые в настоящее время не реализованы нативно в CLEO Redux, например, для файлов или динамические библиотеки.

Этот режим работает в классической GTA III, GTA Vice City и GTA San Andreas, где существует библиотека CLEO.

Установка

Если вы используете The Definitive Edition (GTA III, VC или SA):

• Следуйте этому руководству.

Для всех остальных игр:

• Скопируйте cleo_redux.asi в папку с игрой.

• Запустите игру

Примечание: CLEO Redux не изменяет игровые файлы. Он использует тот факт, что игра изначально загружает файлы .asi в качестве дополнений к библиотеке Miles Sound System. Никакого дополнительного ПО не требуется.

Первичная настройка

Во время первого запуска игры может быть заметное отставание, так как CLEO Redux загружает файлы, необходимые для поддержки JavaScript. При последующих запусках этого не произойдет.

Также в папке с игрой* должна появиться новая папка с именем CLEO. Это основное место для всех CLEO-скриптов, плагинов и конфигов.

*Если CLEO не может создать новые файлы в каталоге игры из-за отсутствия прав на запись, он использует альтернативный путь в C:\Users\<ваше_имя_пользователя>\AppData\Roaming\CLEO Redux. Там можно найти cleo_redux.log и каталог CLEO.

Совместимость с re3 и reVC

CLEO Redux поддерживает только «Windows D3D9 MSS 32bit» версию re3 или reVC.

При запуске на re3 и reVC убедитесь, что в каталоге игры есть файл re3.pdb (для re3) или reVC.pdb (для reVC). Из-за динамического характера адресов памяти в этих реализациях CLEO Redux использует отладочную информацию, хранящуюся в файле PDB, для правильного определения своего местоположения.

Совместимость с The Trilogy: The Definitive Edition

Проверьте Часто задаваемые вопросы по окончательному изданию

Удаление

• Удалите cleo_redux.asi (или cleo_redux64.asi).
• Удалите папку CLEO (необязательно).
• Удалите cleo_redux.log (необязательно).

Конфигурация

CLEO Redux предоставляет некоторые настраиваемые параметры в файле CLEO\.config\cleo.ini.

Общая конфигурация

• AllowCs - при значении 1 CLEO загружает и выполняет файлы *.cs, расположенные в каталоге CLEO. Включено по умолчанию.
• AllowJs - при значении 1 CLEO загружает и выполняет файлы *.js, расположенные в каталоге CLEO. Включено по умолчанию.
• AllowFxt - при значении 1 CLEO загружает и использует файлы *.fxt, расположенные в каталоге CLEO\CLEO_TEXT. Включено по умолчанию.
• CheckUpdates - при значении 1 CLEO проверяет наличие нового обновления, доступного для скачивания, при запуске игры. Включено по умолчанию.
• LogOpcodes - при значении 1 CLEO регистрирует все выполненные опкоды в пользовательских скриптах. Этот журнал является частью файла cleo_redux.log (см. Лог)
• PermissionLevel - устанавливает уровень разрешений для небезопасных операций (см. ниже). По умолчанию используется «слабый».

Разрешения

CLEO Redux признает некоторые пользовательские команды (коды операций) небезопасными и требует от пользователя решить, запускать их или нет. Необработанный доступ к памяти процесса, загрузка внешних библиотек или выполнение сетевых запросов могут быть вредными и вызывать нежелательные побочные эффекты. Поэтому CLEO вводит уровни разрешений для запуска небезопасного кода.

Доступны четыре уровня:

Все

Допускаются любые небезопасные операции. Используйте это только в том случае, если вы доверяете сценариям, которые запускаете.

Слабые

Это уровень разрешений по умолчанию.

Никакая небезопасная операция не разрешена, если сценарий явно не запрашивает ее. В настоящее время для запроса разрешения имя файла сценария должно включать маркеры разрешений, заключенные в квадратные скобки.

Например, если скрипт хочет получить доступ к памяти через 0A8D READ_MEMORY, имя файла должно содержать [mem], т.е. крутой спаунер[mem].cs. Если файл называется по-другому, CLEO отвергает 0A8D, и скрипт вылетает.

Строгие

Никакая небезопасная операция не разрешена, если сценарий явно не запрашивает ее (см. "Слабые"), а файл конфигурации CLEO разрешает этот тип операции в разделе Разрешения.

Раздел разрешений в cleo.ini позволяет включать или отключать группы небезопасных операций с помощью токенов разрешений. Например,

mem=0

отключает все коды операций, связанные с памятью, даже если скрипт имеет токен [mem] в имени файла.

Примечание. Раздел Permissions в cleo.ini вступает в силу только в том случае, если PermissionLevel имеет значение Strict.

Исключения

Небезопасная работа не допускается.

Лог

CLEO регистрирует важные события и ошибки в файле cleo_redux.log расположенном в папке с игрой (или C:\Users\<ваше_имя_пользователя>\AppData\Roaming\CLEO Redux, см. Первичная настройка примечание). Этот файл перезаписывается при каждом запуске игры. Если у вас возникнут какие-либо проблемы при использовании CLEO Redux, начните исследовать основную причину с этого файла.

Чтобы транслировать события в вашем терминале во время тестирования скрипта, запустите:

tail -f cleo_redux.log

tail - это команда unix, поэтому необходима совместимая среда (например, Git Bash).

Пользовательские сценарии

Добавление нового скрипта

Обычно файл скрипта нужно просто скопировать в каталог CLEO. Для установки некоторых скриптов могут потребоваться дополнительные действия. В случае каких-либо проблем проверьте документацию скрипта или обратитесь к его автору.

Удаление скрипта

Удалите файл скрипта из каталога CLEO. Некоторые сценарии могут потребовать дополнительных действий для отмены установки. В случае каких-либо проблем проверьте документацию скрипта или обратитесь к его автору.

Пользовательские команды

Примечание: Следующие команды предназначены только для классических игр. Для The Definitive Edition проверьте эту информацию.

• 0A8C WRITE_MEMORY (UNSAFE - требует mem разрешение)
• 0A8D READ_MEMORY (UNSAFE - требует mem разрешение)
• 0A8E INT_ADD
• 0A8F INT_SUB
• 0A90 INT_MUL
• 0A91 INT_DIV
• 0A93 TERMINATE_THIS_CUSTOM_SCRIPT
• 0AA5 CALL_FUNCTION (UNSAFE - требует mem разрешение)
• 0AA6 CALL_FUNCTION_RETURN (UNSAFE - требует mem разрешение)
• 0AA7 CALL_METHOD (UNSAFE - требует mem разрешение)
• 0AA8 CALL_METHOD_RETURN (UNSAFE - требует mem разрешение)
• 0AB0 IS_KEY_PRESSED

Написание CS-скриптов

Используйте Sanny Builder 3 в режимах редактирования GTA III, GTA VC или GTA SA соответственно. Посетите эту страницу для получения дополнительной информации.

Проверьте Часто Задаваемые Вопросы для получения информации о поддержке CS в обновленных играх.

Написание JS-скриптов

Используйте VS Code (рекомендуется) или любой редактор по вашему выбору. Создайте новый файл с расширением .js и поместите его в папку CLEO. Дополнительную информацию см. в разделе Поддержка JavaScript.

Среда выполнения поддерживает сценарии в стандарте ECMAScript 2020. Это означает, что вы можете использовать самые последние функции JavaScript из коробки, такие как импорт, классы, стрелочные функции и т.д.

CLEO Redux — это не Node.js. Не ожидайте, что здесь будут доступны сокеты, операции с файловой системой или другие функции Node.js.

Интеграция с Visual Studio Code

Посмотреть демонстрацию: https://youtu.be/jqz8_lGnG4g

CLEO Redux генерирует типизации для всех поддерживаемых команд, которые вы можете использовать при написании JavaScript в VS Code. Добавьте следующую строку в свой скрипт *.js чтобы получить полную поддержку автозаполнения:

Для GTA III или re3:

/// <reference path=".config/gta3.d.ts" />

Для Vice City или reVC

/// <reference path=".config/vc.d.ts" />

Для San Andreas

/// <reference path=".config/sa.d.ts" />

Эта строка указывает VS Code, где искать определения команд для функции автозаполнения. Путь может быть относительным относительно файла сценария или быть абсолютным. Дополнительную информацию на официальном портале TypeScript.

Поддержка JavaScript

Предварительное условие

Когда JavaScript включен, CLEO Redux требует определения команд с https://library.sannybuilder.com/. При первом запуске CLEO пытается загрузить их и поместить в вашу локальную директорию CLEO/.config. Если этого не произошло или вы не хотите, чтобы CLEO совершал сетевые вызовы, вручную скачайте необходимый файл (см. таблицу ниже) и поместите его в каталог CLEO/.config.

Жизненный цикл скрипта

Файл с кодом JavaScript должен иметь расширение *.js и содержать известные инструкции, как описано ниже. Скрипт может не иметь инструкций (пустой скрипт). Он запускается, как только начинается новая игра или загружается файл сохранения.

Скрипт завершается автоматически после выполнения последней инструкции. Среда выполнения также завершает зависшие сценарии, чтобы игра не зависала. Застрявший скрипт — это тот, которому потребовалось более 2 секунд для запуска с момента последней команды ожидания. Если это произошло, проверьте свои циклы, в некоторых из них отсутствует команда ожидания.

while (true) {
  // бессмысленный бесконечный цикл, обычно зависающий в игре
  // будет завершено через две секунды
}

Среда выполнения завершит этот скрипт. Чтобы этого избежать, добавьте команду ожидания

while (true) {
  wait(250);
  // все равно бессмысленно, но не зависает в игре
}

Собственные команды

CLEO Redux поддерживает все внутриигровые команды (коды операций) в форме класса, как определено в библиотеке Sanny Builder.

Класс ScriptObject против объекта

Библиотека Sanny Builder определяет статический класс Object для группировки команд, позволяющих создавать и управлять трехмерными объектами в игре. В то же время в JavaScript есть собственный класс Object со своими методами.

Чтобы не смешивать их, CLEO Redux использует класс ScriptObject вместо класса Object из библиотеки с тем же интерфейсом.

var x = ScriptObject.Create(modelId, x, y, z); // код операции 0107, создает новый объект в игре

var x = Object.create(null); // собственный код JavaScript, создает новый объект в памяти JS

Мат. классы

Подобно классу Object (см. выше), и библиотека, и собственная среда выполнения JavaScript используют одно и то же имя для математических утилит: класс Math. Однако в данном случае было принято решение сохранить как собственные методы, так и скриптовые методы под одним и тем же именем класса.

Приоритет отдавался нативному коду в тех случаях, когда он обеспечивал ту же функциональность, что и опкоды скрипта. Например, чтобы вычислить абсолютное значение числа, используйте собственный Math.abs, а не Math.Abs. См. Использование математики для более подробной информации.

Свободный интерфейс

Методы конструируемых сущностей (таких как Player, Car, Char – любые сущности, созданные с помощью метода конструктора) поддерживают цепочку (также известную как Fluent Interface). Это позволяет писать такой код:

var p = new Player(0);

p.giveWeapon(2, 100)
  .setHealth(5)
  .setCurrentWeapon(2)
  .getChar()
  .setCoordinates(1144, -600, 14)
  .setBleeding(true);

Посмотреть демонстрацию: https://www.youtube.com/watch?v=LLgJ0fWbklg.

Методы деструктора прерывают цепочку. Например. учитывая код:

Char.Create(0, 0, 0, 0, 0).setCoordinates(0, 0, 0).delete()

Цепочка не может продолжаться после метода удаления, так как символ удаляется, а его дескриптор больше не действителен.

Примеры

Если вы должны были изменить время суток на 22:00, выполните следующую команду

Clock.SetTimeOfDay(22, 0);

Это будет эквивалентно коду операции 00C0: set_time_of_day 22 0 или SET_TIME_OF_DAY 22 0 в коде SCM.

Поменять деньги игрока

var player = new Player(0);
player.addScore(1000);

new Player(0); эквивалентен получению индекса игрока с использованием глобальной переменной $PLAYER_CHAR в Sanny Builder.

Создадим динамический объект (например, автомобиль)

// запрашиваем модель 
Streaming.RequestModel(101);

// подождём пока игра загрузит модель
while (!Streaming.HasModelLoaded(101)) {
  wait(250);
}

// создаём машину по координатам и сохранить её хэндл
var infernus = Car.Create(101, 1234.0, 567.0, -100.0);

Переменная infernus будет содержать хэндл только что созданного автомобиля. Его можно передать напрямую любой команде, получающей дескриптор Car.

// создать маркер на созданном автомобиле и сохранить хэндл маркера
var blip = Blip.AddForCar(infernus);

Эту же переменную infernus можно использовать для вызова методов Car'а, например, чтобы взорвать машину.

infernus.explode();

Это будет эквивалентно коду операции 020B: взорвать_автомобиль $infernus или EXPLODE_CAR $infernus в сценариях SCM.

Также ознакомьтесь с примерами скриптов.

Импорт

Вы можете импортировать другие файлы сценариев в свой код, чтобы сделать код модульным и использовать общую логику. Среда выполнения поддерживает оператор import, как описано в https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import.

Чтобы избежать запуска включенных файлов .js как отдельных скриптов, либо поместите их в отдельную папку (например, CLEO/includes/), либо используйте расширение .mjs.

import func from "./other"; // импортируем экспорт по умолчанию из other.js или other.mjs, расположенных в том же каталоге

import { PedType } from "./includes/types"; // импортируем именованный экспорт PedType из types.js или types.mjs, расположенных в каталоге CLEO/includes

import data from "./vehicles.json"; // импортируем cars.json как значение JavaScript (массив, объект).

В настоящее время поддерживается только импорт файлов .js (.mjs) и .json.

Пользовательские привязки

Следующие переменные и функции доступны только в коде JavaScript.

• GAME - идентификатор текущей игры. Возможные значения: gta3, vc, re3, reVC, sa, gta3_unreal, vc_unreal, sa_unreal.

if (GAME === "gta3") {
  showTextBox("This is GTA III");
}
if (GAME === "sa") {
  showTextBox("This is San Andreas");
}
if (GAME === "sa_unreal") {
  showTextBox("This is San Andreas: The Definitive Edition");
}

• ONMISSION - глобальный флаг, определяющий, находится ли игрок в данный момент на миссии.

if (!ONMISSION) {
  showTextBox("Not on a mission. Setting ONMISSION to true");
  ONMISSION = true;
}

• TIMERA и TIMERB - два автоматически увеличивающихся таймера, полезных для измерения временных интервалов.

while (true) {
  TIMERA = 0;
  // ждём 1000 мс
  while (TIMERA < 1000) {
    wait(0);
  }
  showTextBox("1 second passed");
}

• log(...values) - печатает разделенные запятыми {values} в cleo_redux.log

var x = 1;
log("value of x is ", x);

• wait(timeInMs) - приостанавливает выполнение скрипта как минимум на {timeInMs} миллисекунд.

while (true) {
  wait(1000);
  log("1 second passed");
}

• showTextBox(text) - отображает {text} в черном прямоугольном поле.

showTextBox("Hello, world!");

• exit(reason?) - немедленно завершает работу скрипта. Функция exit принимает необязательный строковый аргумент, который будет добавлен в cleo_redux.log.

exit("Script ended");

• семейство статических методов в классе Memory для работы с различными типами данных. См. Руководство по памяти для получения дополнительной информации.

Устаревшие

Примечание: использование следующих команд не рекомендуется.

• op(opcode_id, ...input_args) - низкоуровневая функция для выполнения любой внутриигровой команды с опкодом {opcode_id}.

  Для команд, возвращающих одно значение, результатом является это значение.

  Для команд, возвращающих несколько значений, результатом является объект, в котором каждый ключ соответствует возвращаемому значению. Имена ключей соответствуют именам выходов, указанным в определении команды.

  Для условных команд результатом является логическое значение true» или false.

op(0x00c0, 12, 30); // устанавливаем время суток на 12:30

var pos = op(0x0054, 0); // возвращает вектор координат игрока 0 {x, y, z}
showTextBox("Player pos:", " x = ", pos.x, " y = ", pos.y, " z = ", pos.z);

if (op(0x0248, 101)) {
  // Проверяем условие.
  showTextBox("Model with id 101 has been loaded");

Пользовательский текст

CLEO Redux поддерживает пользовательский текстовый контент без необходимости редактировать игровые файлы. См. это руководство для получения дополнительной информации.

Особенности разработки

Лог SCM

CLEO Redux имеет встроенную поддержку отслеживания инструкций SCM. Чтобы включить трассировку для выполняемых команд, откройте cleo.ini и измените LogOpcodes на 1. Обратите внимание, что это может сильно повлиять на производительность игры из-за частых микрозадержек во время записи в файл журнала. Используйте этот параметр только в целях отладки.

Горячая перезагрузка

CLEO отслеживает активные скрипты и перезагружает их в игре по мере их изменения.

Демонстрация: https://www.youtube.com/watch?v=WanLojClqFw

Добавление нового файла скрипта в директорию CLEO или удаление во время игры запускает или останавливает скрипт автоматически.

Демонстрация: https://www.youtube.com/watch?v=LAi2syrsxJg

Горячая перезагрузка для CS-скриптов не работает, когда CLEO Redux работает вместе с CLEO Library (например, в классической San Andreas).

SDK

CLEO Redux предоставляет C++ и Rust SDK для разработки пользовательских команд. Дополнительную информацию см. в руководстве Использование SDK.

Лицензия

CLEO Redux доступен по лицензионному соглашению с конечным пользователем