> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ss14.art/llms.txt
> Use this file to discover all available pages before exploring further.

# Настройка интеграции с Discord

У нас есть множество различных интеграций с Discord, которые вы можете использовать в своём сообществе. Это руководство по настройке всего этого.

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

* Webhook'и игрового сервера
* Встроенный бот игрового сервера
* Отдельный бот

## Предварительные требования

В этом руководстве часто будут упоминаться «ID» каналов Discord, серверов и т.д. Чтобы получить их, включите «Режим разработчика» в настройках Discord, после чего вы сможете щёлкать правой кнопкой мыши по объектам, чтобы получить их ID.

## Webhook'и игрового сервера

Самая простая форма интеграции предоставляется [Discord Webhook'ами](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks). Она позволяет игровому серверу напрямую отправлять сообщения в определённые каналы Discord с минимальной настройкой.

В настоящее время это используется для следующих функций:

* Автоматические уведомления о статусе раунда (завершение, начало).
  * Включает пинг роли, когда раунд завершён.
* Пересылка внутриигровых сообщений adminhelp.

Настройка крайне проста. Создайте webhook для соответствующих каналов Discord (см. ссылку выше), затем укажите их в конфигурационном файле сервера:

```toml theme={null}
[discord]
# Webhook для отправки сообщений adminhelp.
ahelp_webhook = "<Webhook для ahelps>"

# Webhook для отправки сообщений о статусе раунда.
round_update_webhook = "<Webhook для оповещений о раунде>"

# Опционально: ID роли для пинга при завершении раунда.
round_end_role = "<ID роли для пинга>"
```

## Встроенный бот игрового сервера

Это подразумевает, что игровой сервер размещает собственного внутреннего Discord-бота, что позволяет использовать более продвинутые функции, чем могут предоставить простые webhook'и, но опять же с относительно небольшими усилиями по настройке.

В настоящее время это используется для следующих функций:

* Двунаправленный мост OOC/Admin чата
* И многое другое!

### Обзор

Игровой сервер способен запускать собственного Discord-бота напрямую через [Discord.Net](https://docs.discordnet.dev/). Это означает, что вам не нужно запускать отдельную программу на вашем сервере для получения этой функциональности, вам нужно только создать бота на сайте разработчиков Discord и соответствующим образом настроить ваш сервер.

### Основная настройка

#### Создание бота

<Warning>
  Каждый игровой сервер должен иметь собственное независимое Discord-приложение/бота. Не используйте повторно токены Discord-ботов, это может вызвать кучу забавных багов!
</Warning>

1. Перейдите на [сайт разработчиков Discord](https://discord.com/developers/applications), чтобы зарегистрировать новое приложение.
2. Дайте вашему боту подходящее имя, аватар и всё такое.
3. Скорее всего, вы захотите сделать бота приватным, чтобы только вы могли добавлять его в Discord-сообщества. Для этого:
   1. Перейдите в «Installation» и установите «Install Link» в «None».
   2. Перейдите в «Bot» и отключите «Public Bot»
4. В разделе «Bot» включите «Server Members Intent» и «Message Content Intent».
5. Перейдите в «OAuth» и сгенерируйте URL для установки, отметив следующие флажки и нажав кнопку копирования: <img src="https://mintcdn.com/meowmew/TvZPuS8U3lxB2Npc/images/discord/embedded-discord-bot-perms.png?fit=max&auto=format&n=TvZPuS8U3lxB2Npc&q=85&s=b399b5413f3eb64709d98f31a707236c" alt="Discord's OAuth2 URL generator, with &#x22;bot&#x22; scopes and &#x22;Send Messages&#x22; bot permissions checked" width="1426" height="888" data-path="images/discord/embedded-discord-bot-perms.png" />
6. Вставьте сгенерированный URL в браузер, чтобы установить бота.
7. Перейдите в «Bot», нажмите «Reset Token» и скопируйте полученный токен.

#### Конфигурация сервера

Добавьте следующее в конфигурационный файл сервера для настройки Discord-бота:

```toml theme={null}
[discord]
# Токен бота, который вы скопировали ранее.
token = "заполните меня"
# ID вашего Discord-сервера. Щёлкните правой кнопкой мыши по серверу, чтобы скопировать ID.
guild_id = заполните_меня
# Префикс, который должен добавляться ко всем командам, интерпретируемым ботом.
# Он должен быть уникальным для каждого игрового сервера (и любых других ботов на вашем Discord).
# Обратите внимание, что команды в настоящее время не используются, но, вероятно, будут добавлены в будущем.
prefix = "!"
```

Если вы всё сделали правильно, ваш сервер должен подключиться к Discord при следующем перезапуске. Вы можете подтвердить это, проверив логи сервера и увидев, появился ли у вашего бота статус «онлайн».

### Релей чата (OOC/Admin чат)

Discord-бот может автоматически пересылать сообщения между Discord и внутриигровыми каналами. Это поддерживается как для OOC, так и для admin чата.

Для настройки создайте каналы на стороне Discord и убедитесь, что у бота есть права на чтение и отправку сообщений в них. Затем добавьте следующую конфигурацию на ваш сервер:

```toml theme={null}
[ooc]
# ID канала в Discord. Скопируйте его, щёлкнув правой кнопкой мыши по каналу.
discord_channel_id = заполните_меня

[admin]
# ID канала в Discord. Скопируйте его, щёлкнув правой кнопкой мыши по каналу.
chat_discord_channel_id = заполните_меня
```

Вы можете, конечно, пропустить один из каналов, если хотите ретранслировать только один из двух.

## Отдельный бот

Это подразумевает запуск отдельного Discord-бота, который работает независимо от игровых серверов. Это функциональность, которая работает на официальном боте Overseer на Discord'е, включающая:

* Проверка статуса игрового сервера и автоматическое обновление канала.
* Команды для перезапуска/остановки игровых серверов.
* Автоматические ответы на сообщения.

<img src="https://mintcdn.com/meowmew/TvZPuS8U3lxB2Npc/images/discord/overseer.png?fit=max&auto=format&n=TvZPuS8U3lxB2Npc&q=85&s=534ee585236048d25a7512b6c0658d81" alt="Screenshot of Overseer's Discord profile" width="330" height="197" data-path="images/discord/overseer.png" />

Бот использует [Red Discord Bot](https://github.com/Cog-Creators/Red-DiscordBot) в качестве модульной основы, с нашими собственными cog'ами, расположенными [здесь](https://github.com/space-wizards-federation/wizard-cogs). Это означает, что вы можете добавить гораздо больше функциональности от других разработчиков cog'ов, если захотите.

<Note>
  Мы предоставляем поддержку только для официальных wizard-cogs. Поддержка самого Red или других cog'ов не предоставляется нами, обращайтесь за поддержкой на официальный Discord RedBot или к соответствующему разработчику cog.
</Note>

<Warning>
  Большинству наших cog'ов требуется минимальная версия Python 3.11, пожалуйста, убедитесь, что у вас установлена эта версия, прежде чем обращаться за поддержкой.
</Warning>

### Настройка

1. Следуйте [документации Red](https://docs.discord.red/en/stable/install_guides/index.html) по установке и запуску базового Red-бота. Обратите внимание, что, как и сервер SS14, вам нужен компьютер, который будет оставаться включённым для работы вашего бота.
2. Если вы ещё этого не сделали, прочитайте страницу [Getting started для Red](https://docs.discord.red/en/stable/getting_started.html#getting-started).
3. После того как вы настроили бота и пригласили его на свой сервер, вы можете установить репозиторий wizard-cogs для вашего бота. \[p] в данном случае — это префикс вашего бота, который вы выбрали во время настройки redbot.

```
Включите встроенный cog downloader
[p]load downloader

Добавьте репозиторий wizard-cogs
[p]repo add wizard-cogs https://github.com/space-wizards-federation/wizard-cogs

Установите выбранный cog, посмотрите ссылку на GitHub, чтобы узнать ваши варианты
[p]cog install wizard-cogs <cog_name>

Загрузите cog
[p]load <cog_name>
```

````admonish note title="Подсказки" theme={null}
Ищете другие интересные cog'и? Посмотрите [Redbot Cog index](https://index.discord.red/). Как указано выше, мы не предоставляем поддержку для этих cog'ов.

Ваш сервер не на английском? Некоторые cog'и имеют переводы. Вы можете изменить это с помощью ```[p]set locale <language_code>```. Наши cog'и в настоящее время не поддерживают другие языки, кроме английского.
````

#### Статус игрового сервера

<img src="https://mintcdn.com/meowmew/TvZPuS8U3lxB2Npc/images/discord/SS14-game-status-example.png?fit=max&auto=format&n=TvZPuS8U3lxB2Npc&q=85&s=6033d755566d6375fcc4b943765d2848" alt="SS14 Status" width="701" height="385" data-path="images/discord/SS14-game-status-example.png" />

##### Настройка

1. Установите `[p]cog install wizard-cogs gameserverstatus`
2. Добавьте ваш сервер `[p]statuscfg addserver ss14 <имя-сервера> <адрес-вашего-сервера>`
3. Готово! Посмотрите результат с помощью `[p]status <имя-сервера>` (Конечно, ваш сервер должен быть онлайн)

##### Настройка автоматического отслеживания

<img src="https://mintcdn.com/meowmew/TvZPuS8U3lxB2Npc/images/discord/SS14-game-status-watches.png?fit=max&auto=format&n=TvZPuS8U3lxB2Npc&q=85&s=98fe5bf8ee91a8f438555d94a6466e17" alt="SS14 Status Watches" width="549" height="613" data-path="images/discord/SS14-game-status-watches.png" />

Если вы хотите иметь канал, где сообщение о статусе обновляется автоматически, то watch — это та функция, которая вам нужна.

1. После добавления сервера используйте следующую команду `[p]statuscfg addwatch <сервер> <#канал>`
2. Пока у бота есть права на публикацию в этом канале, вы увидите, что статус сервера автоматически обновляется в сообщении примерно каждые 2 секунды.

#### Действия управления через SS14.Watchdog

<img src="https://mintcdn.com/meowmew/TvZPuS8U3lxB2Npc/images/discord/poweractions-example.png?fit=max&auto=format&n=TvZPuS8U3lxB2Npc&q=85&s=0eacf8c173db16bedb3fc26babf29e04" alt="Poweractions" width="501" height="523" data-path="images/discord/poweractions-example.png" />

Позволяет взаимодействовать с SS14.Watchdog для выполнения определённых действий.

1. Установите `[p]cog install wizard-cogs poweractions`
2. Настройте ваш сервер, выполнив `[p]poweractionscfg add` и нажав зелёную кнопку добавления. Только администраторы могут выполнять эту команду. В противном случае бот не ответит.
   Вы увидите форму, которую нужно заполнить (**Примечание**: ни мы, ни разработчики RedBot не получат эту информацию. Эта информация будет храниться только ботом и не будет отображаться публично.)

<img src="https://mintcdn.com/meowmew/TvZPuS8U3lxB2Npc/images/discord/redbot-poweactions-form.png?fit=max&auto=format&n=TvZPuS8U3lxB2Npc&q=85&s=e4d4863843e5edba5c9d9ee66627e45b" alt="Input field" width="515" height="605" data-path="images/discord/redbot-poweactions-form.png" />

* Name: Имя сервера, которое вы будете указывать боту при перезапуске сервера.
* URL: URL экземпляра watchdog, убедитесь, что URL доступен боту. Пример: если вы открываете API watchdog по адресу '[https://example.com/watchdog](https://example.com/watchdog)', то это то, что вам нужно ввести. Вы также можете использовать 'localhost', если бот работает на той же машине, что и watchdog. Порт watchdog по умолчанию — `5000`
* Server ID: Имя вашего сервера в appsettings.yml вашего watchdog, где хранится конфигурация вашего сервера. *Не* конфиг «Name».
* API token: ApiToken из конфигурации вашего watchdog.

3. После нажатия кнопки отправки, если бот сообщил об успехе, вы закончили! Повторите для других ваших серверов.

##### Доступные команды

Перезапустить сервер сейчас:

`[p]restartserver <имя>`

Перезапустить все серверы, настроенные у бота:

`[p]restartnetwork`

*Запросит подтверждение перед выполнением*

Остановить сервер после завершения текущего раунда:

`[p]stopserver <имя>`

Сообщить watchdog'у о необходимости подготовиться к обновлению сервера:

`[p]updateserver <имя>`

#### GitHub интеграция

Ещё не портировано на redbot. Вы можете использовать [github webhook](https://gist.github.com/jagrosh/5b1761213e33fc5b54ec7f6379034a22) в качестве временного решения.

#### Автоответчик (WYCI, Nanotrasen Block Game, Based)

<img src="https://mintcdn.com/meowmew/TvZPuS8U3lxB2Npc/images/discord/autoresponder-example.png?fit=max&auto=format&n=TvZPuS8U3lxB2Npc&q=85&s=d40faceabbf5a57884db756eb60e3582" alt="why" width="373" height="417" data-path="images/discord/autoresponder-example.png" />

`[p]cog install wizard-cogs autoresponder`

Почему... (Отвечает пользователям, говорящим «Something when» — фразой «When you code it», «Tetris» — «Nanotrasen Block Game» и «Based» — «Based on what». Это внутренняя шутка в сообществах Space Station 14)