Исходник Гайд AsiSDK by yorenov | ASI-плагины для GTA SA и SA-MP на C++20, пишутся как скрипты MoonLoader

yorenov

Участник
Автор темы
59
64
К, сожалению, мою прошлую тему модерация не прошла, перепутал разделы. Значит... Поехали!

AsiSDK by yorenov
ASI-плагины для GTA San Andreas 1.0 US и SA-MP на C++20

Скачать | GitHub | Документация | Telegram | Видео​

Всем привет. Давно хотел сделать штуку, на которой ASI-плагин пишется так же быстро и просто, как обычный луа-скрипт под MoonLoader. Сделал. Называется AsiSDK.

Если коротко: это статическая библиотека (один файл AsiSDK.lib плюс заголовки), в которой функции называются ровно так же, как в MoonLoader. sampAddChatMessage, sampRegisterChatCommand, createCar, getCharCoordinates, lua_thread.create, wait и так далее. Только пишете вы на C++20, с нормальными типами, с проверкой ошибок и с корутинами вместо lua_thread. На выходе получаете обычный .asi, который кидается в папку с игрой.

Плагину на AsiSDK не нужны ни MoonLoader, ни lua51.dll, ни SAMPFUNCS, ни CLEO, ни BASS, ни D3DX. Хуки (MinHook), Dear ImGui, загрузка картинок (stb) и звук (miniaudio) уже зашиты внутрь либы. Игрок ставит только ваш .asi и ASI Loader, всё.

Видео


Как это выглядит

Вот полный плагин с командой /hello. Никаких DllMain, никаких потоков руками:

C++:
#include <asi/sdk.hpp>

#include <string>
#include <string_view>

ASI_PLUGIN("HelloPlugin", "1.0") {
    asi::script_author("yorenov");

    asi::lua_thread::create([]() -> asi::Task {
        co_await asi::sampReady();

        auto command = asi::sampRegisterChatCommand("hello", [](std::string_view args) {
            std::string name = args.empty() ? std::string("игрок") : std::string(args);
            auto sent = asi::sampAddChatMessage("Привет, " + name + "!", 0xFF33CCFF);
            if (!sent) asi::log::warn(sent.error().message);
        });

        if (!command) asi::log::error(command.error().message);
    });
}

Кто писал на MoonLoader, тот тут всё узнает с первого взгляда. main() это ASI_PLUGIN, wait() это co_await asi::wait(), lua_thread.create это asi::lua_thread::create. Кириллицу можно писать прямо в коде, SDK сам переведёт UTF-8 в CP1251 для игры и обратно. Никаких u8:decode.

Тело ASI_PLUGIN выполняется в игровом потоке на первом кадре, а не внутри DllMain, так что можно спокойно звать функции игры. Есть ещё ASI_PLUGIN_TASK, там тело сразу корутина и можно сразу писать co_await.

Что умеет

Расписываю по разделам, чтобы было понятно, насколько оно полное.

1. Функции MoonLoader и опкоды
  • 1941 функция MoonLoader доступна напрямую, с теми же именами.
  • Все 1448 опкодов из справочника MoonLoader обёрнуты в C++ функции. Аргументы проверяются до вызова (хендлы, модели, диапазоны), а если игра кинет исключение внутри опкода, SDK его поймает и вернёт ошибку, игра не упадёт.
  • Если нужного нет в обёртках, можно вызвать любой опкод напрямую: asi::scm::callOpcode(0x00A0, ...) или по имени через callNamed.
  • Работа с пулами (getAllChars, getAllVehicles, getAllObjects), поиск в сфере, processLineOfSight, перевод 3D координат в экранные и обратно, кватернионы, метки на карте, глобальные переменные SCM, getD3DDevicePtr и прочее.

2. Корутины вместо lua_thread
  • lua_thread::create, create_suspended, create_in_pause (аналог work_in_pause).
  • co_await asi::wait(500) или wait(500ms), waitForever(), waitUntil(условие), yield().
  • Готовые ожидания: gameReady(), sampReady(), sampConnected(), playerSpawned(). Больше не надо писать while not isSampAvailable() do wait(0) end.
  • Задача может ждать другую задачу, исключение из дочерней пробрасывается наверх.
  • co_await asi::background::run(...) выполнит тяжёлую работу в фоновом потоке и вернёт результат обратно в игровой поток. Игра не фризит.
  • У задачи есть run(), terminate(), statusName() ("suspended", "running", "yielded", "dead" как в MoonLoader), failure() с текстом ошибки, если задача упала.
  • post_to_game_thread() чтобы из любого своего потока выполнить код в игровом.

3. Нормальная обработка ошибок
Всё, что может не выполниться, возвращает asi::Result<T>. Вместо луашного local result, x, y, z = getCharCoordinates(ped) вы получаете структуру с полями positionX, positionY, positionZ и понятный код ошибки, если что-то пошло не так. Есть value_or(), есть asi::must(), который кидает исключение (внутри задачи оно просто завершит задачу и запишется в лог). Если вы забыли проверить результат, SDK напишет об этом в лог. Каждый плагин пишет свой лог в ИмяПлагина.log рядом с .asi, и там видно, почему что-то не сработало.

4. Типы, хендлы и сессии
Ped, Vehicle, Object, Pickup, Marker и т.д. это отдельные типы. Модель нельзя случайно передать вместо хендла, ID игрока SA-MP вместо хендла педа. Компилятор не даст. Плюс каждый хендл помнит сессию: после загрузки сохранения или новой игры старый хендл вернёт ошибку stale_handle, а не испортит какую-то другую машину, которой достался тот же номер. Для автоматического удаления сущностей есть asi::Owned (RAII): создали машину в блоке, вышли из блока, машина удалилась.

5. События
onGameTick, onD3DPresent, onD3DDeviceLost/Reset, onWindowMessage (с consume, чтобы не пускать клавишу в игру), onStartNewGame, onLoadGame, onSaveGame, onQuitGame, onExitScript, onScriptLoad, onScriptTerminate, onSystemInitialized и другие. У всех есть приоритет. Можно писать и в стиле MoonLoader через addEventHandler.
Фишка: в onSaveGame можно вернуть свои данные в JSON, и они сохранятся вместе с сейвом игры, а в onLoadGame придут обратно. При удалении слота сохранения файл тоже удаляется.

6. SA-MP
  • Поддерживаются 0.3.7 R1, R2, R3, R4, R4-2, R5. Версия определяется автоматически.
  • Можно указать своё имя DLL клиента (samp::setClientModule), если у проекта клиент называется иначе.
  • Чат, команды, диалоги, игроки, транспорт, объекты, пикапы, текстдравы, 3D-тексты, табло, синхронизация, отправка RPC-действий, указатели на структуры клиента. Всё с привычными именами sampGet..., sampSet..., sampSend....
  • samp::status() показывает по этапам, что происходит: DLL загружена, версия опознана, объекты созданы, подключены, заспавнены.

7. Перехват пакетов и RPC
net::onReceiveRpc, onReceivePacket, onSendRpc, onSendPacket. Можно читать, блокировать и подменять. Обработчики всех плагинов вызываются по приоритету. Есть свой BitStream с чтением/записью, readText с переводом в UTF-8, encodeString/decodeString для сжатых строк SA-MP. Отправка на сервер (raknetSendRpc, raknetSendBitStream) и эмуляция входящих (raknetEmulRpcReceiveBitStream). Если отправлять пакет изнутри хука, он идёт мимо хуков, так что рекурсии не будет.

Пример: фильтр рекламы в чате, всё что содержит слово "реклама" просто не доходит до игры:

C++:
#include <asi/sdk.hpp>

#include <string>

ASI_PLUGIN("AdFilter", "1.0") {
    asi::net::onReceiveRpc(93, [](asi::net::NetMessage& message) {
        auto view = message.payload();
        auto color = view.readUInt32();
        auto length = view.readUInt32();
        if (!color || !length || *length > 4096) return asi::HookDecision::pass;

        auto text = view.readText(*length);
        if (text && text->find("реклама") != std::string::npos)
            return asi::HookDecision::block;

        return asi::HookDecision::pass;
    }, 100);
}

8. Рендер
renderCreateFont, renderFontDrawText (с цветовыми тегами {RRGGBB} и кириллицей), прямоугольники, линии, полигоны, текстуры из файла или из памяти (PNG, JPG, BMP, TGA), произвольная геометрия через renderBegin/renderVertex/renderEnd. Шрифты и текстуры сами восстанавливаются после сброса устройства, то есть Alt+Tab ничего не ломает. Плюс спрайты из TXD игры.

9. Dear ImGui
ImGui встроен, подключать ничего не надо. Шрифт с кириллицей поднимается сам, imgui.ini не создаётся. asi::gui::onInitialize для стиля и шрифтов (как imgui.OnInitialize в mimgui), asi::gui::onFrame для отрисовки, setInputCapture чтобы показать курсор и при желании заблокировать управление. Пока ни один плагин не использует интерфейс, SDK вообще не трогает отрисовку игры. Есть и DXUT-диалоги, совместимые с MoonLoader, только рисуются через ImGui.

В документации есть табличка, как переносить скрипт с mimgui, и полный пример такого переноса (10_lovlya_simok).

10. Звук без BASS
MP3, WAV, FLAC, OGG. Из файла, из памяти или по ссылке. 2D и 3D потоки, 3D можно привязать к координатам, педу, машине или объекту. Громкость, зацикливание, пауза, длительность.

11. SAMPFUNCS и CLEO без SAMPFUNCS и CLEO
Консольные команды SAMPFUNCS, глобальные переменные SAMPFUNCS, общие переменные CLEO работают даже если ни того ни другого нет: всё хранится внутри SDK и общее для всех плагинов. Если CLEO стоит, используются его опкоды. Можно создавать свои SCM-потоки на байт-коде. startNewCustomScript и launchCustomMission работают при наличии CLEO 4+.

12. Память и нативные вызовы
memory.getint32 / setfloat и все остальные, как в MoonLoader, плюс шаблонные get<T>/set<T>, copy, fill, compare, tohex, hex2bin, unprotect. Каждый доступ защищён SEH: кривой адрес вернёт ошибку, а не крашнет игру. callFunction, callMethod (thiscall), callNative с выбором соглашения вызова, функции с float на стеке FPU.

13. Всё остальное
  • JSON (encode/decode, load/save с атомарной записью) и INI (аналог inicfg, файл в UTF-8 или CP1251).
  • Файлы и папки с юникодными путями, поиск файлов.
  • Свои строки GXT.
  • Буфер обмена.
  • Загрузка DLL, получение адресов функций.
  • Скачивание файлов по HTTP(S) в фоне с прогрессом.
  • Ввод: isKeyDown, wasKeyPressed, колесо мыши, курсор, блокировка управления, эмуляция нажатий.

14. Несколько плагинов в одной игре
Это важный момент. Если у игрока стоит пять ваших .asi на AsiSDK, хуки игры, D3D, окна и сети ставятся один раз, а события раздаются всем по приоритету. Имена чат-команд общие, поэтому два плагина не смогут тихо перебить одну и ту же команду, второй получит ошибку already_exists. Плагины могут экспортировать функции друг другу (publishExport / importFunction), как import и EXPORTS в MoonLoader. Модули, собранные SDK 1.0 и 1.1, работают вместе. С оригинальным LuaExecutor тоже совместимо.

15. Очистка за собой
При выгрузке плагина или выходе из игры SDK сам завершит задачи, отпишет события и сетевые хуки, снимет команды, освободит шрифты, текстуры, звуки, записи GXT, удалит созданные сущности и отпустит курсор. Руками это делать не нужно.

16. Загрузочный экран
По умолчанию плагин показывает заставку на экранах загрузки. Свою картинку ставите одной строкой в CMakeLists.txt, отключаете тоже одной строкой:
Код:
asi_add_plugin(MyPlugin main.cpp LOADING_SCREEN "art/loading.png")
asi_add_plugin(MyPlugin main.cpp LOADING_SCREEN OFF)

Кому это нужно

  • Тем, кто пишет на MoonLoader и хочет сделать из скрипта нормальный ASI. Скорость, защита кода (это уже скомпилированный бинарь, а не .lua/.luac), не надо тащить за собой MoonLoader и кучу библиотек.
  • Тем, кто давно хотел попробовать C++, но боялся. Порог входа тут почти как у Lua: те же функции, плюс компилятор сам подскажет, где вы ошиблись.
  • Тем, кто уже пишет ASI на голом C++ и устал каждый раз заново поднимать хуки, D3D9, ImGui и разбираться с потоками. Тут это всё уже сделано.
  • Разработчикам под конкретные проекты с кастомными клиентами (своё имя samp.dll).

Чем отличается от plugin-sdk и SAMP-API

Чтобы не было вопросов:
  • plugin-sdk это полный реверс движка. Если вам нужны глубокие моды с классами игры, это туда.
  • SAMP-API это реверс классов клиента SA-MP.
  • AsiSDK это по сути MoonLoader, только на C++. Тот же API, который все знают, без внешних зависимостей, с готовыми хуками, ImGui, звуком и сетью из коробки.
Они не конкурируют, а скорее для разных задач.

Минусы (честно)

  • Исходники библиотеки закрыты. Публикуются заголовки, AsiSDK.lib и CMake-модуль.
  • Только GTA SA 1.0 US. На других версиях функции игры вернут ошибку unsupported, но игра не упадёт.
  • Собирать только в MSVC x86, Release, /MT. Debug-сборку плагина сделать нельзя.
  • Нет реверснутых классов игры (для этого plugin-sdk) и нет поддержки 0.3.DL.
  • .asi получается тяжелее, примерно от 0,6 МБ, потому что всё внутри.
  • Нет горячей перезагрузки как в MoonLoader, после изменений нужно пересобрать и перезапустить игру.
  • Консоль SAMPFUNCS SDK не рисует: команды можно вызывать программно или из своей консоли на ImGui.

Что нужно

  • Visual Studio 2022 или новее, с компонентом "Разработка классических приложений на C++" (инструменты x86).
  • CMake 3.25+ (идёт вместе со студией).
  • GTA San Andreas 1.0 US.
  • Любой ASI Loader (Silent's или Ultimate ASI Loader).
  • Для SA-MP: клиент 0.3.7 R1/R2/R3/R4/R4-2/R5.

Как скачать и начать

1. Идёте в релиз на GitHub и качаете:
  • AsiSDK-1.1.0.zip это сам SDK (include, lib/AsiSDK.lib, документация, cmake/AsiSDK.cmake, лицензии).
  • AsiSDK-1.1.0-examples.zip это 10 примеров, в каждом уже лежит копия SDK и готовый .asi. Если хотите сначала просто посмотреть, как это работает в игре, берите его.
Там же лежит SHA256SUMS.txt, если хотите проверить архивы.

2. Создаёте папку проекта, распаковываете AsiSDK-1.1.0.zip в подпапку sdk. Должно получиться так:
Код:
MyPlugin\
  sdk\
    include\
    lib\
    cmake\
  CMakeLists.txt
  main.cpp

3. CMakeLists.txt:
Код:
cmake_minimum_required(VERSION 3.25)
if(NOT CMAKE_BUILD_TYPE)
    set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type")
endif()
project(MyPlugin LANGUAGES C CXX)

include("${CMAKE_CURRENT_SOURCE_DIR}/sdk/cmake/AsiSDK.cmake")

asi_add_plugin(MyPlugin main.cpp)
asi_set_output_directory(MyPlugin "${CMAKE_CURRENT_SOURCE_DIR}/bin")
Строка с Release обязательно до project(), иначе студия сама выберет Debug.

4. main.cpp: берёте пример с /hello из начала поста.

5. Открываете x86 Native Tools Command Prompt for VS 2022 (ищется в пуске), переходите в папку проекта и пишете:
Код:
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
Если удобнее генератор Visual Studio:
Код:
cmake -S . -B build -G "Visual Studio 17 2022" -A Win32
cmake --build build --config Release
Ещё проще: скопируйте build.cmd из любого примера, он сам найдёт студию, CMake и Ninja.

6. Берёте bin\MyPlugin.asi и кидаете в папку игры рядом с gta_sa.exe. Заходите, пишете /hello. Если что-то не так, смотрите MyPlugin.log рядом с .asi.

Если вы что-то настроили не так (x64, /MD, Debug, C++17), сборка остановится с понятным сообщением, что именно поменять. Голову ломать не придётся.

Можно и без CMake, ключи компилятора и линкера есть в документации.

Примеры

В репозитории 10 примеров, каждый собирается отдельно через свой build.cmd:
  • 01_minimal_chat_command: команда /hello и сообщение в чат.
  • 02_tasks_and_timers: задачи, ожидание, пауза, фоновые вычисления, перезапуск, ошибки (F2).
  • 03_network_hooks: перехват, блокировка и подмена RPC и пакетов (/netinfo).
  • 04_render_and_gui: текст и примитивы поверх игры, окно ImGui (F3).
  • 05_entities: машины и метки с автоудалением, модели (F10, /veh).
  • 06_audio: звук из памяти, 3D звук, файл (F11).
  • 07_config_unicode_client: INI, JSON, UTF-8 и CP1251, своё имя DLL клиента.
  • 08_events_and_session: события, свои данные в сохранениях, сообщения окна (Insert).
  • 09_two_plugins: два ASI, обмен функциями, общие команды (/alpha, /beta).
  • 10_lovlya_simok: перенос реального mimgui-скрипта на AsiSDK со стилем, своими кнопками и CEF-пакетом 215 (F4, /lovlyasimok).
Чтобы собрать примеры из клона репозитория, распакуйте SDK в sdk\ в корне клона и запустите build.cmd в папке нужного примера. Горячие клавиши примеров не пересекаются с клавишами SA-MP и не срабатывают, когда открыт чат.

Документация

Полное руководство на русском: AsiSDK_API.md. Оно же лежит в релизе как lib/AsiSDK_API.md. Там всё по разделам с примерами кода, таблица соответствия MoonLoader и AsiSDK, список кодов ошибок и в конце все объявления всех заголовков.

Что нового в 1.1.0
  • Загрузочный экран (своя картинка или отключение одной строкой).
  • asi::gui::onInitialize для настройки стиля и шрифтов ImGui.
  • Протокол брокера 1.1, модули на SDK 1.0 продолжают работать вместе с новыми.
  • Новый пример 10_lovlya_simok.
  • build.cmd проверяет каждый шаг и при сбое повторяет сборку.
Полный список изменений в CHANGELOG.md на гитхабе.

Лицензии
Внутри используются MinHook, Dear ImGui, stb и miniaudio. Их лицензии лежат в THIRD_PARTY_NOTICES.txt, кладите этот файл рядом со своими плагинами, когда выкладываете их.

Ссылки

Баги, предложения, чего не хватает пишите сюда в тему или в Issues на гитхабе. Если сделаете что-то на AsiSDK, кидайте, интересно посмотреть.

Автор: yorenov (AkeGGa)
 

chromiusj

Известный
Модератор
6,107
4,502
ASI-плагин пишется так же быстро и просто, как обычный луа-скрипт под MoonLoader
Зачем? Обычный плагин спокойно пишется быстро без всяких плюмбусов по типу этого. Всегда хватает обычного набора по типу PSDK/SAMP-API, и уже в зависимости от необходимости библиотеки для хуков. Остальное - бессмыслица. Даже темплейты с готовыми вариантами подключения и пренастройками будут более чем удобными
asi получается тяжелее, примерно от 0,6 МБ, потому что всё внутри.
IMG-20261107-WA0001.jpg
 

yorenov

Участник
Автор темы
59
64
Зачем? Обычный плагин спокойно пишется быстро без всяких плюмбусов по типу этого. Всегда хватает обычного набора по типу PSDK/SAMP-API, и уже в зависимости от необходимости библиотеки для хуков. Остальное - бессмыслица. Даже темплейты с готовыми вариантами подключения и пренастройками будут более чем удобными

Посмотреть вложение 304104
Есть люди, которые только начинают разбираться в си++. Я же тоже когда-то переходил с луа сразу же на крестики. Мне было сложно уживаться с синтаксом плюсов. Я не мог разобраться, почему потоки они все-таки небезопасны. Я не мог разобраться, почему у меня стопится игра, когда я пишу sleep. Это сейчас после годов разработки, я уже начинаю все понимать и осознавать. Но люди, которые только пришли - они ничего не знают. Писать с помощью нейросети-это как-то не по-человечески. Я не люблю нейросети, я использую их только лишь как инструмент. Здесь я, например, писал все самостоятельно единственное, что - api было написано с помощью нейросети. Потому что писать api вручную-это слишком долго и сложно, и из-за этого использование нейросети в качестве инструмента для написания чего-либо это наоборот хорошо. Для людей это очень сложно понять. Поэтому я дал возможность с помощью одного лишь инструмента пытаться как-то написать плагины или переписать луа скрипты на c++, которые будут работать везде. Мне кажется, наоборот, это неплохая идея для того, чтобы начинать разрабатывать что-либо создана тема была лишь для тех людей, которые не умеют разрабатывать. Ведь многие же люди скачивают visual studio и не умеют в нем, например, подключать сампапи или же какой-нибудь kthook. Как по мне удобнее взять одну библиотеку просто напросто и с помощью этой библиотеки+заголовков написать что либо похожее на луа и изучать синтаксис плюсиков. Да и проект у меня разрабатывался приблизительно года 2, потому что это было очень сложно и долго. Сейчас я решил просто напросто этот проект дропнуть лишь для того, чтобы люди начали смотреть его переходить, например, на плюсы с луа.

Ну и + ко всему этому с помощью костылей, только возможно написать на самп api плагин, который будет работать на всех версиях. А здесь уже тебе дано из коробки, что оно работает на всех версиях. Здесь тебе даны из коробки, например, те же самые хуки ракнет. Здесь тебе дано все из коробки, и это все собрано в одно единое, чтобы можно было написать какой-либо плагин без усилий вообще. И что плохого?
 

01EG

Режим чтения
Проверенный
796
463
Зачем? Обычный плагин спокойно пишется быстро без всяких плюмбусов по типу этого. Всегда хватает обычного набора по типу PSDK/SAMP-API, и уже в зависимости от необходимости библиотеки для хуков. Остальное - бессмыслица. Даже темплейты с готовыми вариантами подключения и пренастройками будут более чем удобными

Посмотреть вложение 304104
да ну выглядит ответ в стиле дарк кнайта
хейт то за что? или у тебя времена 2006 года где диски по 128 гигов?? и каждый мегабайт ценен
ну да псдк\самп-апи куда проще ставиться🧌🧌🧌🧌🧌, чем эту хуйню проделывать, хотя это тоже действия-💩💩
Зачем? Обычный плагин спокойно пишется быстро без всяких плюмбусов по типу этого. Всегда хватает обычного набора по типу PSDK/SAMP-API, и уже в зависимости от необходимости библиотеки для хуков. Остальное - бессмыслица. Даже темплейты с готовыми вариантами подключения и пренастройками будут более чем удобными

Посмотреть вложение 304104
проще всего проэкт сампфанкса открывался прост и пишешь себе плагины.

хотя этот проект тоже поприятней обычных аси плагинов кодится должен и выглядеть ЛАКОНИЧНО
крч сложно ты проделал так много работы, но зачем?

юрий кодэ бы оценил ((( r.i.p