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

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

Что это

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

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

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

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

Плагин

Что нужно

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

Установка

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

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

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

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

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

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

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

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

Кластеры

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

Чат

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

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

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

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

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

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

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

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

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

Карта

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

Discord и Telegram

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

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

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

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

Каналы чата и журнала трайба

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

• Чат работает в обе стороны. Журнал идёт только из игры в мессенджер; ему нужен отдельный канал или отдельная тема Telegram. Без привязки канала журнала доставка приостановлена, в чат он не перенаправляется.
• Существующие каналы чата продолжают работать как чат. Журнал подключите отдельно командами /st bridge log и/tribelog <код>.
• Если слово команды изменено в кластере, используйте своё вместо/st.
• Один канал принадлежит одному мосту. Код трайба никогда не забирает уже привязанный канал, так что перехватить канал кластера кодом трайба нельзя.
• /disconnect в канале отвязывает его (только админы). Мост можно удалить и в панели.
• Админы Discord могут ограничить команды трайба каналами или ролями: Server Settings → Integrations → SatayaLib.
• Свой бот: на платных тарифах мост может работать под именем и аватаром вашего бота. Положите его токен на странице «Боты»; он хранится зашифрованным.

Шаблоны сообщений

На странице «Боты» создайте или отредактируйте мост и откройте шаблон исходящего сообщения. Один синтаксис работает в Discord и Telegram.

• Другой пояс задаётся прямо в подстановке:{date:Europe/Moscow} и{time:Europe/Moscow}. Поддерживаются IANA-имена; неверный пояс блокирует сохранение.
• Дата и время относятся к исходному сообщению. Очередь и повторная доставка их не меняют.
• Нужный фрагмент можно обернуть в **...**: например,**{character}** или**[{map}] {character} [{tribe}]**. Это работает в Discord и Telegram. Можно выделить несколько фрагментов и сам{text}.
• Пустой [{tribe}] исчезает вместе со скобками. Отсутствующая платформа выводится пустой строкой. У старых сообщений новые сведения могут отсутствовать.
• Неизвестные подстановки и непарные ** остаются буквальным текстом. Для буквальных звёздочек используйте \*\*.
• Шаблон трайб-моста наследуется от моста кластера. Он не меняет оформление служебных сообщений, трайб-лога и табло.

[{date:Europe/Moscow} {time:Europe/Moscow}] {platform} **[{map}] {character} [{tribe}]**: {text}

Preview с заполненными данными (демонстрационные):

[2026-10-17 16:30:49] Steam[Ragnarok] Alex [Northern Wolves]: Иду на The Island.

Preview без платформы и трайба:

[2026-10-17 16:30:49] [Ragnarok] Alex: Иду на The Island.

Живое табло

Живое табло — одно сообщение в Discord или Telegram с онлайном и состоянием связи по картам одного кластера. Бот редактирует это сообщение вместо публикации ленты обновлений.

1. На странице «Боты» выберите «Создать мост», затем «Вид моста» → «табло». Выберите кластер и мессенджер, затем карты и их порядок. Пустой выбор означает все активные карты в порядке по умолчанию. Имена игроков по умолчанию скрыты.
2. Панель покажет одноразовый код. Пригласите бота и напишите/board <код> в выбранном канале. Привязывать табло могут только админы сервера или группы.

• Табло обновляется периодически: при изменениях — не чаще раза в минуту, а метка времени обновляется каждые пять минут.
• Зелёный статус означает связь с плагином. Красный — связи нет; это не доказывает падение игрового сервера. Прежний онлайн отмечен как «was N», а не как текущий. Жёлтый означает, что связь есть, но данные устарели.
• Неизвестное число игроков показано как «—», не как ноль. Сразу после подключения карты число остаётся неизвестным до первого снимка игроков.
• Если имена включены, они выводятся по картам, не более десяти и «+N more». В длинном табло сначала сокращаются списки имён, затем строки карт с указанием числа скрытых карт. Показываются только имена персонажей, а при их отсутствии — ники.
• Текст табло английский, время — UTC. Собственного часового пояса у табло нет; шаблон игрового чата не меняет ни табло, ни его часовой пояс.
• Steam/EOS ID, IP-адреса, координаты и трайбы в табло не публикуются.

Доступность зависит от настроек тарифа. Уточните условия вDiscord.

Сторож карт

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

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

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

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

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

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

Открытое API

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

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

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

Перевод на другой тариф пока делается вручную: напишите нам вDiscord. Early Access включает расширенные возможности, включая своего бота: 1 проект, до 25 карт и 30 дней истории чата на три месяца. Доступность живого табло уточняйте отдельно.

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

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

• Проверьте 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. Откройте тикет в канале поддержки: он создаёт приватный канал для вас и команды. Никогда не публикуйте ключи, токены и коды в общих каналах.