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

Как подключить кластер ARK к SatayaLib: плагин, панель, мосты в Discord и Telegram, API.

Что это

SatayaLib — это чат между серверами и панель для кластера ARK (ARK: Survival Ascended и ARK: Survival Evolved). Игроки на всех картах общаются друг с другом, трайбы сохраняют свой приватный чат между картами, а у вас есть панель с историей, игроками, картой и мостами в Discord и Telegram.

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

Быстрый старт

Войдите в панель. Пароля нет: вводите почту, приходит одноразовый код, вводите его.
Создайте проект и кластер. Проект — это ваша команда: люди, которые управляют серверами. Кластер — группа карт с одним общим чатом. В проекте может быть несколько кластеров.
Выпустите ключ на странице «Ключи». Ключ показывается один раз, скопируйте его. Одного ключа хватает на все ваши машины и карты.
Скачайте плагин на странице «Плагин», под ASA или ASE. Распакуйте в папку плагинов ArkApi на карте и впишите в config.json ключ и адрес панели. Готовый config.json для копирования есть на странице «Ключи».
Запустите карту. Она появится на странице «Серверы» со статусом «ждёт подтверждения». Подтвердите её и выберите кластер.
Повторите для каждой карты. Чат идёт между картами, которые подтверждены, включены, на связи и в одном кластере.

Подтверждение — ваша защита: карта, подключившаяся с вашим ключом, ничего не делает, пока вы её не подтвердите. Если ключ утёк, отзовите его на странице «Ключи» и выпустите новый.

Плагин

Что нужно

ASA: карта работает с AsaApi (Ark Server API). ASE: карта работает с ArkApi. SatayaLib — плагин для этого загрузчика.
Сервер на Windows. ASE с плагином работает только на Windows.

Установка

Распакуйте архив в ArkApi/Plugins/SatayaLib рядом с другими плагинами.
Откройте ArkApi/Plugins/SatayaLib/config.json и заполните два поля:

{
  "key": "ключ проекта со страницы «Ключи»",
  "url": "wss://satayalib.com/plugin/connect"
}

Запустите карту. Больше на сервере ничего не нужно.

Полезно знать

Соединение идёт от вашего сервера к нам, по одному WebSocket. Никаких открытых портов, RCON и базы данных.
Плагин никогда не блокирует игру: если панель недоступна, карта работает дальше и переподключается сама.
На странице «Серверы» видна версия плагина на каждой карте и предупреждение, если карта работает на сборке старше той, что опубликована на странице «Плагин». Обновление — заменить библиотеку и перезапустить карту; конфиг и подтверждение остаются.
Сертификаты: плагин доверяет хранилищу сертификатов Windows. Если на сервере свой CA, укажите путь к нему в поле ca_file в config.json.

Серверы и кластеры

Каждая карта — строка на странице «Серверы». У строки три независимых признака:

Поле	Что значит
Статус	«ждёт подтверждения» или «подтверждён». Меняется один раз, когда карта появилась впервые.
Включён	Ваш выключатель. Выключите карту, чтобы убрать её из чата, не удаляя.
Онлайн	Подключён ли плагин прямо сейчас. Ставим мы, а не вы. После рестарта подтверждать заново не нужно.

Подтверждение, перенос карты в другой кластер и выключатель применяются за секунду, без перезапуска карты.
Карта опознаётся по ключу, порту, названию карты и игре. Если вы сменили карту на сервере, она появится новой строкой и снова будет ждать подтверждения.
Удаление строки отключает плагин до следующего перезапуска; история чата остаётся.
У каждой карты может быть своё название и цвет в строке чата: значок ярлыка рядом с названием карты.

Кластеры

Кластер — это один чат. Его настройки живут на странице «Кластеры»: слово команды для игроков (по умолчанию st), шаблон строки чата (как выглядит префикс с картой и ником), язык ответов игрокам, фильтр слов и автоматическая связка трайбов.

Чат

Страница «Чат» показывает чат кластера вживую и позволяет писать в игру от имени панели. Ваша строка доходит до всех карт кластера.
История хранится по кластеру столько дней, сколько даёт тариф.
Фильтр запрещённых слов работает на нашей стороне: слово маскируется на других картах, в панели и в API. На карте автора строку рисует сама игра, поэтому автор её видит как написал. Свои слова и исключения задаются на странице «Кластеры».
Эмоции, набранные в игре, снаружи приходят обычными смайликами, а обратно в игру уезжают картинками.

Трайбы между картами

Трайб живёт на одной карте. SatayaLib связывает трайбы разных карт в одну группу, и чат трайба вместе с журналом племени ходит между картами.

Командой. Владелец или админ трайба пишет /st link на одной карте и получает код. На другой карте участник того же трайба пишет /st link <код>. Код живёт час.
В панели. На странице «Игроки», вкладка «Трайбы», выберите трайбы разных карт и нажмите «Объединить». Там же можно отвязать.
Автоматически. Включите на кластере «автосвязку по владельцу»: трайбы с одним и тем же владельцем связываются сами. Ручные связки автоматика не трогает.
Журнал племени (убийства, приручения, постройки) собирается со всех карт и показывается на странице «Игроки», вкладка «Трайбы», под списками трайбов. Он же уходит в собственный канал трайба в Discord или Telegram (см. ниже).

Команды в игре

Игроки набирают команды в чате. Слово st и имена подкоманд меняются на кластере. Всё, что начинается со слэша, в общий чат между серверами не попадает.

Команда	Что делает
`/st help`	Список команд, доступных этому игроку.
`/st link`	Выдаёт код связки трайба (владельцу или админу трайба).
`/st link <код>`	Связывает трайб на этой карте с трайбом, выдавшим код.
`/st unlink`	Выводит трайб из сквозной группы.
`/st color nick <цвет>`	Цвет ника. Цвета: red, orange, gold, yellow, lime, green, cyan, blue, purple, pink, white, gray.
`/st color text <цвет>`	Цвет текста, та же палитра.
`/st color reset`	Сбрасывает цвета.
`/st bridge`	Выдаёт код для привязки собственного канала трайба в Discord или Telegram.

Цвета видны на других картах и в панели; мессенджеры цвета не показывают. На своей карте игрока строку рисует игра как обычно. Могут ли игроки выбирать цвета сами, зависит от тарифа и от настроенных вами групп.

Игроки, группы, муты

Страница «Игроки». Кто сейчас онлайн на каждой карте и все, кого кластер видел: персонаж, уровень, трайб, последний вход, платформа. Цвета можно задать и отсюда.
Группы. VIP-группы на проекте: подпись в строке чата со своим цветом, права вроде «может сам выбирать цвет ника», участники по Steam или EOS ID со сроком, отложенным стартом и одноразовыми опциями. Участника можно добавить до того, как он впервые зашёл на сервер.
Муты. Мут выдаётся по платформенному ID с причиной и сроком, действует на всех картах проекта и переживает смену карты. Сообщение останавливается до того, как уйдёт на другие карты, а на карте автора его прячет плагин. История наказаний остаётся на игроке.

Карта

Страница «Карта» показывает, где находятся игроки на выбранной карте: онлайн-игроки вживую, офлайн-тела после сбора.
«Начать сбор» просит плагин один раз обойти карту и сообщить о спящих телах и погибших персонажах. Читается живой мир, а не файлы сейва, и это достаточно легко, чтобы запускать при игроках онлайн.
Картинки карт официальные; без картинки всё равно есть сетка с координатами.

Discord и Telegram

Наши боты: SatayaLib в Discord и @satayalib_bot в Telegram. Мост соединяет один канал с чатом одного кластера, в обе стороны.

Канал кластера

Страница «Боты», «Создать мост»: выберите кластер, мессенджер и что слать (чат, входы и выходы, статус карт, тревоги).
Панель покажет одноразовый код (живёт час) и кнопку «Пригласить бота».
Пригласите бота на сервер или в группу, откройте канал и напишите /connect <код> (в Discord: /connect code:<код>). Привязывать и отвязывать могут только админы сервера или группы.

С этого момента сообщения из канала уходят в игру с меткой [Discord] или [Telegram], а игровой чат идёт в канал. Шаблоны обоих направлений правятся на мосте.

Канал трайба

В игре владелец или админ трайба пишет /st bridge и получает код личным сообщением.
В собственном канале трайба кто-то пишет /tribe <код>. Теперь в канале живут чат трайба и журнал племени, а ответы уходят обратно трайбу в игру.

Один канал принадлежит одному мосту. Код трайба никогда не забирает уже привязанный канал, так что перехватить канал кластера кодом трайба нельзя.
/disconnect в канале отвязывает его (только админы). Мост можно удалить и в панели.
Админы Discord могут ограничить команду /tribe каналами или ролями: Server Settings → Integrations → SatayaLib.
Свой бот: на платных тарифах мост может работать под именем и аватаром вашего бота. Положите его токен на странице «Боты»; он хранится зашифрованным.

Сторож карт

Если карта замолчала и не вернулась за 15 минут, вам об этом скажут. Короткий рестарт ничего не запускает.

В Discord или Telegram: включите «тревоги» на мосте. Для тихого канала только для админов создайте второй мост того же кластера в приватном канале и включите там только «тревоги»; в Discord можно добавить роль для упоминания.
Письмом: владелец проекта получает одно письмо на карту в сутки, не больше трёх на проект в сутки. Если лёг весь кластер, приходит одно письмо со списком карт.
Когда карта вернулась, канал сообщает об этом.

Здоровье карт

Страница «Здоровье» показывает, как на самом деле работает каждая карта: длительность кадра игры изнутри сервера, онлайн, обрывы и тревоги на одной оси времени. Снаружи кадр сервера не видит никто, поэтому именно здесь решается спор «это сервер или сеть».

По каждой карте: средний и худший кадр, игроки онлайн, порог тревоги и метки всех обрывов и тревог. Периоды: сутки, неделя, 30 дней.
Доступность: доля времени на связи, число обрывов, самый долгий и обычное время подъёма.
Онлайн по часам недели: когда кластер живёт активнее всего, чтобы планировать ивенты и рестарты.
Тревога о лаге: если кадр держится выше 100 мс пять минут, мосты с включёнными тревогами получают сообщение; когда всё успокоилось, приходит отбой. Письма о лаге нет.

Страница входит в тариф Pro.

Открытое API

Страница «Интеграции»: выпустите токен с нужными правами (читать чат, писать в чат, чат трайбов, серверы, события). Токен показывается один раз.
Передавайте его как Authorization: Bearer <токен>. Справочник со всеми ручками: /api/v1/docs.
Поток событий — WebSocket с чатом, входами и выходами, статусом карт, присутствием, связками трайбов и тревогами сторожа. На нём живут боты, оверлеи и статистика.

Тарифы и лимиты

Тариф живёт на аккаунте владельца проекта и распространяется на все его проекты. Он ограничивает число проектов, подтверждённых карт и дней истории чата и включает возможности: цвета, модерацию, карту, сбор офлайн-данных, своё слово команды, открытое API, своего бота. Страница «Тариф» показывает, что у вас есть и что предлагается.

Перевод на другой тариф пока делается вручную: напишите нам в Discord. Хотите попробовать максимум возможностей? Напишите туда же, и мы включим все функции на три месяца.

Если что-то не работает

Карта не появляется на странице «Серверы»

Проверьте url и key в config.json: ключ должен быть живым ключом вашего проекта, адрес — тем, что на странице «Ключи».
Посмотрите лог ArkApi на сервере: плагин пишет, почему не может подключиться, по-английски.
«key revoked» или 401 в логе: ключ отозван; выпустите новый.
426 в логе: плагин слишком старый для панели; скачайте текущую сборку.

Ошибка сертификата в логе

Плагин проверяет сертификат панели через хранилище сертификатов Windows. Обновите корневые сертификаты сервера или положите на сервер набор CA и укажите путь к нему в ca_file в config.json.

Карты на связи, а чат не идёт

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

Бот не отвечает на /connect

Бот должен быть в канале с правом читать и писать. В Telegram привязывать могут только администраторы группы.
Код одноразовый и живёт час; возьмите новый на странице «Боты».
«This code is a tribe code» означает, что вы ввели /connect с кодом из игры; коды трайба идут с /tribe.

Игроки не видят цвета на своей карте

Так и задумано: на карте автора строку рисует игра. Цвета видны на других картах и в панели, мессенджеры их не показывают.

Две машины с одним ключом

Это нормально. Карты различаются портом, названием карты и адресом, и каждая новая ждёт подтверждения.

Поддержка

Вопросы, тикеты и запросы функций — в нашем Discord. Откройте тикет в канале поддержки: он создаёт приватный канал для вас и команды. Никогда не публикуйте ключи, токены и коды в общих каналах.