EasyUniversal / DocsДокументация · SDK 0.3Подписка Universal ↗
Easy Universal / Справочник SDK

Контракт адаптеров

AngelScript · native runtime · локальная сборка

Easy Adapter SDK 0.1

Это контракт для авторов адаптеров, не автоматическая поддержка всех игр.
Движок предоставляет загрузку, проверку пакета, существующие разрешённые
источники, общую модель сущностей и геометрию. Автор адаптера определяет
структуры, версию приложения, единицы и преобразования координат, проверяет
результаты чтения и публикует только достоверные текущие данные.
Название игры в manifest — заявление автора, не сертификат совместимости.

Разделение пакета

Копируйте examples/adapter-demo в новую папку каталога и задайте уникальный id.
Пакет содержит main.as (callbacks), source.as (получение/нормализация данных)
и view.as (общий потребитель данных). Они компилируются в один AngelScript
модуль и разделяют функции/типы. #include, импорты сторонних SDK и DLL не нужны
и не реализованы. Файл entry и каждый modules-файл должны быть UTF-8 .as.

{
  "id":"my-adapter", "name":"My authorized application",
  "author":"Your name", "version":"0.1.0", "api":"0.1",
  "entry":"main.as", "modules":["source.as","view.as"],
  "permissions":["render","demo"], "resources":[],
  "adapter":{
    "id":"my-source", "game":"my-application", "version":"0.1",
    "source":"demo", "capabilities":["entities","projection"]
  }
}

Максимум 8 дополнительных файлов, 128 КиБ каждый, 256 КиБ суммарно с entry.
Повтор файла/entry, выход из папки и обнаруженные ссылки запрещены. Каталог
показывает хэши всех модулей; их изменение меняет fingerprint. Контрольный
отпечаток не является подписью. Встроенный Source пока редактирует только entry;
остальные файлы редактируются внешним редактором. При изменении зависимостей
Save блокируется до Reopen; сначала скопируйте несохранённые правки.
Перезагрузка перечитывает все модули, но не разрешает менять descriptor,
ID или permissions в текущей сессии. Для этого нужен Stop → новая сессия.

Источники и возможности

  • demo: синтетические данные самого хоста, требует permission demo.
  • process_read: существующее read-only API одного явно выбранного PID,

требует permission process_read и отдельного пользовательского согласия.

  • wt_telemetry: только локальные приборы собственной техники War Thunder,

требует permission; в GUI включается при запуске, CLI требует --allow-wt-telemetry.

entities, projection, instruments описывают контракт пакета. Они не дают
доступа к памяти/сети, не запускают функции автоматически и не обходят защиту.
Произвольных HTTP-источников, автоматизации ввода, записи памяти, kernel и
захвата чужого overlay нет. Проверка имени процесса/версии/структур — обязанность
адаптера, не движка. Для отказа Windows нужно показывать ошибку, а не обходить её.

Статусы

bool adapter::declared();
string adapter::game();
string adapter::source();
bool adapter::has_capability(const string &in capability);
bool adapter::source_available();
string adapter::status();
string adapter::last_error();
bool adapter::set_status(const string &in state, const string &in message = '');

Статусы: waiting, ready, unavailable, unsupported, invalid.
set_status вызывается только в on_frame. Сообщение UTF-8 ≤256 байт.
source_available проверяет только доступность источника: выданный живой процесс,
валидную свежую WT телеметрию либо объявленный demo. Это не проверка структур,
версии игры или достоверности прочитанной сущности. ready устанавливает автор
после собственной проверки; без доступного источника он отклоняется.
Необъявленный adapter: declared() возвращает false, другие adapter-вызовы
завершаются диагностикой. geometry доступна независимо как чистая математика.

Сущности: текущий кадр

bool adapter::add_entity(uint64 id, const string &in label,
                        float x, float y, float z, float health, uint team);
uint adapter::entity_count();
bool adapter::entity_position(uint index, float &out x, float &out y, float &out z);
uint64 adapter::entity_id(uint index);
string adapter::entity_label(uint index);
float adapter::entity_health(uint index);
uint adapter::entity_team(uint index);

Перед каждым on_frame состояние очищается. Адаптер выставляет ready и добавляет
сущности, затем его потребитель читает их в том же callback. Старая сущность
автоматически не переносится в следующий кадр. Утрата источника очищает данные.

Конвенция адаптеров: метры, правосторонние координаты X вправо / Y вперёд /
Z вверх. Автор преобразует исходные координаты. HP нормализуется в 0–100,
это не обязательно исходное число HP; -1 означает неизвестное здоровье,
вместо выдуманного значения. Team 0 — неизвестная, 1–255 — метки
команд конкретного приложения. ID ненулевой, уникальный в кадре; его стабильность
между кадрами обеспечивает автор. Label UTF-8 ≤128 байт. Максимум 128 сущностей.
Координаты конечные, модуль ≤10⁷. Некорректная сущность, дублированный ID или
переполнение очищают весь снимок и дают invalid, а не частично старые данные.

Публикация требует capability entities, ready и on_frame. Для отсутствующего
индекса position возвращает false с нулями; ID/team=0, label пустая, health=-1.
Нет встроенных костей, видимости, прогнозирования, ввода или автоматического
извлечения игроков: расширение модели — отдельный следующий этап.

Геометрия

float geometry::distance3(float x, float y, float z, float x2, float y2, float z2);
bool geometry::project(const string &in matrix64,
                       float x, float y, float z, float &out sx, float &out sy);

project принимает ровно 64 бинарных байта: 16 little-endian float32, row-major,
clip = M × [x,y,z,1]. Это не JSON и не строка чисел. Матричные координаты должны
соответствовать нормализованным координатам сущности. Автор транспонирует и
преобразует матрицу при другой конвенции источника. Используется текущий
логический viewport хоста, не разрешение другого приложения наугад.
Отрицательный/малый clip.w и выход за NDC X/Y [-1,1] дают false и нулевые sx/sy.
Глубина Z не проверяется: near/far и видимость обязан проверить адаптер.
Некорректные матрицы/координаты отклоняются. distance3 возвращает -1 при
некорректных координатах. Это проекция, не трассировка стен и не гарантия fullscreen.

Проверка адаптера

  1. Сначала fixture: без игры, синтетические или заранее разрешённые данные.
  2. Проверьте missing/zero/dead, перезапуск источника, неверную версию и координаты.
  3. Проверьте отключённые согласия и отсутствие устаревших данных.
  4. Только потом — разрешённый живой источник и длительная сессия.

Нейтральный пример и тесты подтверждают контракт SDK. Они не подтверждают
Destiny 2, Fortnite, Rust или любую иную игру. Наличие разрешённого источника
для каждой новой игры проверяется отдельно. Easy External не изменяется.

Easy Universal — отдельный проект. Easy External не изменён.