Бот OrgHelper

Эта инструкция для бота версии v1.1.0. В следующих версиях могут быть добавлены новые функции или изменены прежние. Эта инструкция будет обновляться по мере выхода новых версий.

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

Пригласите бота на свой Дискорд-сервер по ссылке: https://discord.com/api/oauth2/authorize?client_id=714175230809210952&permissions=8&scope=bot

Напишите !help, чтобы увидеть все доступные команды.

Управляйте ботом с помощью текстовых команд:

На английском

Задайте часовой пояс сервера:

!set­time­zone Europe/Moscow

Добавьте менеджеров ролей:

!addrole­m­an­ag­er @moscow-manager, @Владимир, @Олололя @moscow-member

Создайте напоминание:

!remind each Sun 15:30 Через 30 минут еженедельный созвон!

Создайте опрос:

!poll "Лучший сотрудник недели:" "Петя" "Вася" "Маша"

На русском

Задайте язык:

!set­lo­cale ru-RU

Задайте часовой пояс сервера:

!задатьчасовойпояс Europe/Moscow

Добавьте менеджеров ролей:

!добавитьменеджераролей @moscow-manager, @Владимир, @Олололя @moscow-member

Создайте напоминание:

!напомнить каждые Вс 15:30 Через 30 минут еженедельный созвон!

Создайте опрос:

!опрос "Лучший сотрудник недели:" "Петя" "Вася" "Маша"

Подробная инструкция

OrgHelper - это бот для Дискорда, который помогает управлять сообществами (на языке Дискорда - "серверами" или "гильдиями").

Чтобы пользоваться возможностями бота, вам нужно состоять как минимум в одном сообществе Дискорда, а лучше - быть в нём администратором, потому что часть команд бота доступна только администраторам сообществ. Зарегистрироваться в Дискорде можно здесь: https://discord.com/

Обратите внимание: через некоторое время мы планируем добавить мультиплатформенную поддержку для бота. То есть, пользоваться OrgHelper'ом можно будет в инструментах типа Slack, Telegram и т.д. Хотите приблизить этот момент? Попросите ваших знакомых программистов присоединиться к разработке этой функциональности или присоединитесь сами, если у вас есть умение и желание. Исходный код бота на GitHub: https://github.com/alteh-union/org-helper

Как начать пользоваться ботом?

Чтобы OrgHelper начал работать в вашем сообществе, его нужно туда пригласить следующим способом:

  1. Пройдите по ссылке: https://discord.com/api/oauth2/authorize?client_id=714175230809210952&permissions=8&scope=bot
  2. Авторизуйтесь в Дискорде, если ещё не сделали этого
  3. Выберите, в какое из ваших сообществ нужно пригласить OrgHelper'а

Готово! Теперь в вашем сообществе вы можете найти бота в списке участников. Как, например, здесь:

Как общаться с ботом?

Общение с ботом проходит путём написания ему команд в текстовых чатах Дискорда.

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

Обратите внимание: у бота должно быть достаточно разрешений на чтение ваших команд и ответов вам. По умолчанию бот приглашается с правами администратора, но если вы вручную выставите в каком-либо канале запрет на чтение/отправку сообщений для бота (точнее, для его роли, которая совпадает с его именем), то бот не сможет нормально работать в этом канале.

Чтобы не путать обычные сообщения с командами для бота, последние нужно начинать с определённого префикса. По умолчанию, префикс - это восклицательный знак: !

То есть, если написать боту "ping", то он ничего не ответит, потому что не воспримет это как команду. А вот если написать ему "!ping" (!пинг), то он ответит на это сообщение "pong!"

Список всех команд с описаниями можно посмотреть, введя специальную команду !help (!помощь).

А если нужно узнать подробности о конкретной команде (в частности, её аргументы), то нужно ввести !help и имя этой команды после пробела. Например, "!help add­role" (второй раз префикс писать не нужно).

Обратите внимание: префикс ! и английский язык - это настройки по умолчанию. Бот может общаться и на русском языке, а также настраиваться на другой префикс (это нужно, например, для того, чтобы не конфликтовать с другими ботами в сообществе). Если бот не отвечает на ваши команды, возможно, вы что-то поменяли в этих настройках. В таком случае, введите команду "!help" (то есть, "помощь" с префиксом по умолчанию и на языке по умолчанию). Бот поймёт её, независимо от того, какой язык и какой префикс вы настроили.

Аргументы команд

Большинство команд, кроме самых простых, имеют аргументы (параметры), которые конкретизируют ваш запрос к боту.

Например, следующая команда добавляет 2 роли (модератор и редактор) одному пользователю по имени ServerAdmin:

!add­role @ServerAdmin @moderator, @editor

(!добавитьроль @ServerAdmin @moderator, @editor)

Здесь аргументами выступают:

  1. @ServerAdmin - упоминание о пользователе с никнеймом Server­Ad­min (упоминание получается при помощи присоединения префикса @ перед никнеймом). Вместо одного человека здесь могло быть несколько, через запятую
  2. @moderator, @editor - список ролей через запятую, которые нужно назначить упомянутому ранее пользователю

Как понять, что аргументы именно эти? Введите "!help add­role" (или на русском "!помощь добавитьроль"), чтобы увидеть список аргументов.

Вот пример помощи по команде !addrole­m­an­ag­er (!добавитьменеджераролей - добавляет менеджеров ролей):

Обратите внимание: как правило, у аргументов есть два имени (алиаса), и в командах вы можете использовать любой из них, если вообще называете аргументы по имени.

Есть два способа вводить аргументы: по имени или последовательно без имён.

По именам

Примеры:

!addrole­m­an­ag­er -s @ServerAdmin -r @moderator

!remind -t 2h -c #Москва -m Не забудьте сдать отчётность!

Преимущества:

Чётко разделённые аргументы, нельзя заехать следующим на предыдущий

Не нужно знать последовательность аргументов

Более понятный ввод

Некоторые аргументы можно пропускать - они установятся на значения по умолчанию

Недостатки:

Длинная запись

Нужно знать имена аргументов

Последовательно

Примеры:

!addrole­m­an­ag­er @ServerAdmin @moderator

!remind 2h Не забудьте сдать отчётность!

Преимущества:

Более короткая запись

Не нужно знать аргументы по именам

Недостатки:

Нужно знать последовательность аргументов

Можно заехать следующим аргументом на предыдущий (зависит от типов аргументов)

Некоторые аргументы нельзя ввести в последовательном режиме - они устанавливаются на значения по умолчанию

Вы можете пользоваться любым одним способом в любом вызове команды, но вы не можете мешать оба способа в рамках одного и того же вызова команды.

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

Например, бот поддерживает создание напоминания для любого текстового канала из любого канала, но что будет, если мы попытаемся ввести аргумент, обозначающий канал, последовательно? Получится что-то вроде этого:

!remind at Sun 12:45 #общий Через 15 минут общий сбор!

(!напомнить в Вс 12:45 #общий Через 15 минут общий сбор!)

Человек может понять, что #общий обозначает здесь канал, для которого предназначено сообщение, но для робота нереально определить, это целевой канал или уже начало сообщения, которое нужно передать на текущий канал?

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

Основные функциональности

Точное управление ролями

Дискорд поддерживает систему ролей в рамках единой вертикальной иерархии. Такой как эта:

В чём тут проблема?

Представьте, что вы управляете не маленькой группой людей, а разветвлённым сообществом, представленным в нескольких странах или регионах. Логично, что в таких регионах будут как обычные члены сообщества, так и региональные лидеры. И логично, что вы захотите передать управление региональными ролями региональным лидерам.

Обычно люди в таких случаях выдают разрешения (per­mis­sions) типа управление ролями ("Man­age roles") в самом Дискорде. В таком случае люди с такими разрешениями смогут давать и отнимать роли, которые находятся ниже их в иерархии. Но что получится в горизонтальной разветвлённой структуре? Что-то вроде этого:

админы

менеджеры-москва

менеджеры-спб

менеджеры-казань

участники-москва

участники-спб

участники-казань

Здесь люди с ролью "менеджеры-москва" получают право управлять, во-первых, всеми обычными участниками в регионах, а во-вторых, ещё и менеджерами в Санкт-Петербурге и Казани, чего мы явно делать не хотели.

Вот тут на помощь и приходит OrgHelper с его системой управления ролями.

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

Например,

!addrole­m­an­ag­er @менеджеры-москва @участники-москва

(!добавитьменеджераролей @менеджеры-москва @участники-москва)

В этом случае участники с ролью @менеджеры-москва смогут обращаться к боту с запросом на добавление или снятие роли при помощи команд !add­role и !remove­role. Например:

!add­role @Маша @участники-москва

(!добавитьроль @Маша @участники-москва)

!remove­role @Вася, @ПорфирийПетрович @участники-москва

(!убратьроль @Вася, @ПорфирийПетрович @участники-москва)

Убрать разрешение на управление ролями можно при помощи команды !removerole­m­an­ag­er:

!removerole­m­an­ag­er @менеджеры-москва @участники-москва

!убратьменеджераролей @менеджеры-москва @участники-москва

Кстати, назначать менеджерами ролей можно не только носителей ролей, но и конкретных людей. Например:

!addrole­m­an­ag­er @ServerAdmin @участники-москва

Посмотреть список текущих разрешений по управлению ролями можно при помощи команды:

!per­mis­sions role

(!разрешения роль)

Обратите внимание: пользоваться командами !addrole­m­an­ag­er и !removerole­m­an­ag­er могут только администраторы сообщества. Также, администраторы имеют все права, которые другие участники могут получить только через эти команды. То есть, администраторы могут сразу использовать команды !add­role и !remove­role.

Напоминания

Эта функциональность полезна для тех, кто проводит разовые или периодические мероприятия в рамках Дискорда и должен напоминать о чём-то участникам сообщества.

Администраторы сообщества (а также участники, которых наделили таким правом с помощью команды !per­mitrem­mind) могут создавать напоминания с помощью команды !remind. Например:

!remind 2h Не забудьте сдать отчётность!

!remind -t each Mon 15:30 -c #Москва -m Не забудьте сдать отчётность!

(или по-русски):

!напомнить -в каждые Пн 15:30 -к #Москва -т Не забудьте сдать отчётность!

В первом случае, создастся разовое напоминание, которое сработает через два часа после написания команды, и отправит в тот же канал, где была написана команда, сообщение "Не забудьте сдать отчётность!".

Во втором и третьем случае (в зависимости от выбранного языка), создастся периодическое напоминание, которое каждый понедельник в 15:30 будет постить сообщение "Не забудьте сдать отчётность!" в тестовый канал #Москва.

Обратите внимание: если в команде не указан часовой пояс, то он будет взят либо из настроек бота для конкретного пользователя (заданную через команду !set­my­time­zone), либо из настроек бота для гильдии (заданную через команду !set­time­zone), либо будет поставлен в UTC (нулевое смещение относительно всемирного координированного), в порядке уменьшения приоритета. Не забудьте указать часовой пояс для вас лично или для вашего сервера!

Действующие напоминания можно посмотреть с помощью команды !reminders. Можно также посмотреть напоминания только для конкретного канала. Например:

!remiders #Москва

(!напоминания #Москва)

(последний вариант особенно полезен, если у вас нет глобального разрешения на напоминания, а есть только на конкретный канал)

Удалить ненужное напоминание можно по его цифровому идентификатору. Сначала выводите список напоминаний, а затем используете команду !deletere­minder с этим идентификатором. Например:

Пользователи без администраторских привилегий не могут создавать напоминания по умолчанию. Но им можно дать такое право при помощи команда !per­mitrem­ind. Например:

!per­mitrem­ind @Вася

!per­mitrem­ind @Маша #отчёты

(!разрешитьнапоминания @Маша #отчёты)

В первом случае пользователь @Вася получит право создавать напоминания в любом текстовом канале, а во втором - пользователь @Маша получит возможность создавать напоминания только в канале #отчёты.

Отозвать разрешение можно при помощи команды !denyre­mind. Например:

!denyre­mind @Вася

!denyre­mind @Маша #отчёты

(!запретитьнапоминания @Маша #отчёты)

Посмотреть список текущих разрешений на напоминания можно при помощи команды:

!per­mis­sions remind

(!разрешения напоминание)

Обратите внимание: пользоваться командами !per­mitrem­ind и !denyre­mind могут только администраторы сообщества. Также, администраторы имеют все права, которые другие участники могут получить только через эти команды. То есть, администраторы могут сразу использовать команды remind, reminders и deletereminder.

Обратите внимание: бот не разрешает заводить более 50 активных напоминаний на гильдию.

Опросы

Работает похоже на боты типа Sim­ple Poll. Создаёт опрос в виде группы эмодзи, где каждая эмодзи отвечает за вариант ответа. Пользователи наживают на одну или несколько эмодзи, таким образом "голосуя" за вариант ответа.

Опросы создаются с помощью команды !poll (!опрос), с как минимум одним аргументом (вопросом). Если присутствуют дополнительные аргументы, то они считаются вариантами ответа, и в таком случае создаётся опрос не типа "поддерживаю/не поддерживаю в целом", а "голосую за такой-то вариант".

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

Примеры:

Превращается в:

Превращается в:

Очистка чатов

Позволяет одной командой очистить сообщения в текущем или указанном тестовом канале за всё время или за последнее указанное время.

Примеры:

!clean -c #Москва -t 2h -s silent

(!очистить -к #Москва -в 2ч -т тихо)

Очищает сообщения за последние 2 часа в канале Москва "тихо" (не выводит финальное сообщение о количестве очищенных сообщений).

!clean today

Очищает все сообщения в текущем канале за сегодня.

!clean all

Очищает все сообщения в текущем канале за всё время.

Обратите внимание: команда требует внутреннего разрешения Дискорда на модерирование сообщений в канале, где будет проводиться чистка.

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

1y 4M 3d 4h 5m 6s

или на русском:

1г 4М 3д 4ч 5м 6с

в обоих случаях означает: 1 год, 4 месяца, 3 дня, 4 часа, 5 минут, 6 секунд (всё это конвертируется в миллисекунды и суммируется, чтобы получить точку во времени, до которой нужно удалить сообщения от текущего момента).

Модерация

Бот имеет следующие команды для мгновенной модерации: warn (предупредить), kick (пнуть), ban (бан). Examples:

!warn @Mike For being rude

(!предупредить @Миша За грубость)

!kick @Stacey For bad language

(!пнуть @Вольтер За нецензурные выражения)

!ban @StupidBot, @MerchBot For con­stant spam

(!бан @Спаммер, @Флудер За сообщения не по теме)

Команды "пнуть" и "бан", соответственно, удаляют указанных пользователей с сервера без бана и с баном.

Обратите внимание: Бот должен иметь достаточно прав, чтобы пинать и банить указанных пользователей, иначе команды модерации не сработают.

Команда "предупредить" добавляет предупреждение в базу данных Бота. Позже предупреждения можно посмотреть с помощью команды "предупреждения". Существующие предупреждения могут быть удалены с помощью команды "удалитьпредупреждение" по их номерным идентификаторам (айдишники можно узнать с помощью команды "предупреждения").

Основной смысл команды "предупредить" в том, что вы можете задать автоматический бан пользователей, которые получили достаточно предупреждений. Для этого используется команда "задатьбаннапредупреждения". Например:

!set­banon­warn­ings 3

(!задатьбаннапредупреждения 3)

!warn @Godzilla For smash­ing the buildings

(!предупредить @Godzilla За разрушение зданий)

!warn @Godzilla For crash­ing the people

(!предупредить @Godzilla За топтание по людям)

!warn @Godzilla For not hav­ing a valid visa

(!предупредить @Godzilla За просроченную визу)

- Пользователь Godzil­la получает бан по причине "Получено слишком много предупреждений".

Чтобы выключить бан за предупреждения, используйте ту же команду без аргументов или с аругментом = "0":

!задатьбаннапредупреждения

Другая полезная фича модерации - это сохранение логов (сообщений) об актах модерации в специальном указанном текстовом канале. Чтобы включить логи модерации, используйте команду "задатьлогимодерации":

!set­mod­er­logs on

(!задатьлогимодерации вкл)

Чтобы задать текстовый канал, куда будут складываться логи модерации, используйте команду "задатьканаллоговмодерации":

!set­mod­er­logschan­nel #mod­er­a­tion-logs

(!задатьканаллоговмодерации #логи-модерации)

Обратите внимание: Бот должен иметь достаточно прав для добавления сообщений в указанный канал.

Если канал не был указан, но при этом логи модерации включены, то Бот попытается создать текстовый канал с названием "mod­er-logs" и начнёт логировать сообщения туда.

Настройка под пользователя

Все пользователи серверов, где есть бот OrgHelper, могут задавать себе настройки, связанные с ботом. Например, задавать часовой пояс, чтобы бот правильно понимал, на какое время поставить напоминание. Или язык, чтобы было проще общаться с ботом.

Команды, связанные с индивидуальными настройками пользователей на серверах, следующие:

!myset­tings (!моинастройки - выводит список настроек)

!set­my­lo­cale (!задатьмойязык - задаёт язык или удаляет настройку, если аргумент пустой)

!set­my­time­zone (!задатьмойчасовойпояс - задаёт часовой пояс или удаляет настройку, если аргумент пустой)

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

Настройки самого сервера могут задавать только администраторы сообщества.

Команды, связанные с настройками сервера, следующие:

!set­tings (!настройки - выводит список настроек сервера)

!addbad­words (!добавитьплохиеслова - добавляет слова в список нецензурных)

!bad­words (!плохиеслова - выводи список слов помеченных как нецензурные)

!remove­bad­words (!удалитьплохиеслова - удаляет слова из списка нецензурных)

!set­cen­sor­ing (!задатьцензуру - включает или отключает цензуру)

!set­lo­cale (!задатьязык - задаёт общий язык для сервера с точки зрения бота)

!set­time­zone (!задатьчасовойпояс - задаёт часовой пояс сервера с точки зрения бота)

!set­pre­fix (!задатьпрефикс - задаёт префикс для команд, чтобы вместо ! использовать, например, $ или - или ыыы или что угодно)

!set­banon­warn­ings (!задатьбаннапредупреждения - определяет, как много предупреждений должен получить пользователь, прежде чем Бот его забанит)

!set­mod­er­logschan­nel (!задатьканаллоговмодерации - задаёт имя текстового канала, куда будут публиковаться логи модерации)

!set­mod­er­logs (!задатьлогимодерации - включает или выключает логи модерации)

Обратите внимание: в своей работе бот использует настройки в порядке уменьшения приоритета (если не находит настройку с более высоким приоритетом - спускается на приоритет ниже): сначала индивидуальные настройки пользователя, затем настройки сервера, затем настройки по умолчанию (например, язык бота по умолчанию - английский).

Создание картинок

Бот может генерировать картинки на основе загруженных шаблонов и предоставленной базовой картинки. Например:

Результат в высоком качестве может быть взят с Дискорда с помощью клика по готовой картинки и затем - по ссылке "Open original":

Создание картинки может быть запущено с помощью команды "makeim­age" (создатькартинку):

!makeim­age <имя шаблона> <ссылка на базовую картинку> <текст для картинки> <размер шрифта>

Последний параметр может быть пропущен, потому что шаблоны, как правило, настроены только на определённый размер шрифта, и этот размер можно указать в самом шаблоне.

Пример использования:

$создатькартинку it_2lines https://storage.ruptly.tv/thumbnails/20200625-006/UNN1XBL4Uc1qf7wX/large_UNN1XBL4Uc1qf7wX.jpg "Таксисты Uber в США\nотстояли право на социальные гарантии"

Обратите внимание: убедитесь, что вы имеете разрешение на использование выбранной вами картинки. Разработчики Бота не несут ответственность за нелегальное использование, распространение или модификацию изображений с помощью Бота. Кроме того, если вам разрешено использовать изображение только с указанием его источника, то указывайте этот источник отдельно.

Вы можете разделить ваш текст/заголовок в нужных вам местах с помощью комбинации символов "\n" (как в примере выше). Здесь \n означает символ "новой строки", широко используемой в компьютерных науках.

Шаблоны для создания изображений

Шаблоны картинок являются общими в рамках гильдии (сервера) и могут загружаться либо администраторами, либо людьми, которые имеют разрешение "imagetem­plate" ("шаблонкартинок").

Это разрешение может быть предоставлено с помощью команды "per­mitim­agetem­plate" ("разрешитьшаблоныкартинок"):

!per­mitim­agetem­plate @Петя, @редакторы

(!разрешитьшаблоныкартинок @Петя, @редакторы)

и отозвано с помощью команды "deny­im­agetem­plate" ("запретитьшаблоныкартинок"):

!deny­im­agetem­plate @Петя

(!запретитьшаблоныкартинок @Петя)

Как обычно, существующие разрешения можно посмотреть с помощью команды "per­mis­sions" ("разрешения").

Администраторы и лица с нужным разрешением могут использовать следующие команды, чтобы добавлять, удалять шаблоны и выводить список их имён:

!addim­agetem­plate имя_шаблона

(!создатьшаблонкартинок имя_шаблона)

!lis­tim­agetem­plates

(!списокшаблоновкартинок)

!deleteim­agetem­plate имя_шаблона

(!удалитьшаблонкартинок имя_шаблона)

Команда "создатьшаблонкартинок" добавляет указанный шаблон в базу данных Бота и назначает ему указанное имя. Можно указать шаблон в виде текстовой строки прямо внутри команды, но это не рекомендуется, во-первых, потому что это неудобно, а во-вторых, потому у Дискорда есть ограничение на количество символов в сообщении - 2000.

Поэтому, вместо того, чтобы печатать шаблон прямо в команде, сделайте .txt файл на вашем компьютере, где содержимым будет шаблон, и добавьте его к текстовому сообщению с командой "создатьшаблонкартинок". Как здесь:

Формат шаблонов объясняется в секции ниже.

Команда "списокшаблоновкартинок" выводит список существующих шаблонов, что может потребоваться по 2-м причинам: найти, какие шаблоны можно использовать с командой "создатькартинку", а также чтобы удалить неиспользуемый шаблон.

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

Обратите внимание: tсуществует ограничение в 30 шаблонов на гильдию (сервер). Так что, если вы достигли этого предела, вам нужно удалить несколько старых шаблонов, прежде чем вы сможете добавить новые.

Используйте команду "удалитьшаблонкартинок", чтобы удалить шаблон по его имени. Например:

Содержимое шаблонов картинок

Чтобы самостоятельно создавать шаблоны картинок, вам желательно иметь представление о 2-х вещах: о формате JSON и о программах редактирование изображений типа Pho­to­shop или GIMP.

Хотя формат шаблонов довольно прост, у вас могут возникнуть трудности с ним, так что, вероятно, имеет смысл проконсультироваться с человеком, знакомым с технологиями JSON/Javascipt и/или с редактированием изображений.

Если у вас нет такого опыта, но вы хотели бы научиться создавать шаблоны, тогда один из лучших способов для вас - это учиться на примере. То есть, взять один из существующих примеров шаблона (см. ниже) и поиграться с разными структурами и параметрами, чтобы увидеть, как это влияет на результат.

Каждый шаблон картинок в Боте - это JSON объект с инструкциями о том, как изменить предоставленное пользователем изображение, чтобы в результате получить новое изображение.

Инструкции для Бота в конечном счёте преобразуются в инструкции для библиотек JIMP (примитивный аналог программы GIMP на JavaScript) и text-to-image (во время работы с текстовыми слоями). Большинство имён параметров в шаблоне просто совпадает с именами параметров и функций из этих двух библиотек.

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

Вот пример шаблона из группы Alteh Union в социальных сетях, который предполагает заголовок из двух строк:

{
"input": {
"type": "fixed",
"width": 1280,
"height": 720
},
"fonts": [
{
"url": "https://github.com/dharmatype/Bebas-Neue/raw/master/fonts/BebasNeue(2014)ByFontFabric/BebasNeue-Bold.ttf",
"name": "Bebas Neue Bold"
}
],
"items": [
{
"type": "image",
"url": "http://alteh.org/wp-content/uploads/2020/08/tmpl_it_2lines_under_text.png",
"align": "bot­tom",
"autoscale": true,
"blend": {
"mode": "mul­ti­ply"
}
},
{
"type": "text",
"mar­gin": {
"left": 0,
"right": 0,
"top": 64,
"bot­tom": 0
},
"style": {
"font­Size": 72,
"line­Height": 80,
"tex­tAl­ign": "cen­ter",
"fontWeight": "bold",
"font­Fam­i­ly": "Bebas Neue Bold",
"bgCol­or": "trans­par­ent",
"text­Col­or": "black"
},
"blur": 5
},
{
"type": "text",
"mar­gin": {
"left": 0,
"right": 0,
"top": 64,
"bot­tom": 0
},
"style": {
"font­Size": 72,
"line­Height": 80,
"tex­tAl­ign": "cen­ter",
"fontWeight": "bold",
"font­Fam­i­ly": "Bebas Neue Bold",
"bgCol­or": "trans­par­ent",
"text­Col­or": "black"
},
"blur": 5
},
{
"type": "text",
"mar­gin": {
"left": 0,
"right": 0,
"top": 64,
"bot­tom": 0
},
"style": {
"font­Size": 72,
"line­Height": 80,
"tex­tAl­ign": "cen­ter",
"fontWeight": "bold",
"font­Fam­i­ly": "Bebas Neue Bold",
"bgCol­or": "trans­par­ent",
"text­Col­or": "white"
}
},
{
"type": "image",
"url": "http://alteh.org/wp-content/uploads/2020/08/tmpl_it_2lines_stripes.png",
"align": "bot­tom",
"autoscale": true,
"blend": {
"mode": "over­lay"
}
},
{
"type": "image",
"url": "http://alteh.org/wp-content/uploads/2020/08/tmpl_it_1line_vin.png",
"align": "bot­tom",
"autoscale": true,
"blend": {
"mode": "over­lay"
}
}
]
}

Обратите внимание: в отличие от других функциональностей в Боте, текст шаблона может быть только на английском языке (за исключением ссылок на шрифты и изображения)

Здесь главный объект состоит из трёх основных блоков (являющихся его "свойствами") - "input", "fonts" и "items".

Объект "input" ("ввод") определяет, что нужно предварительно сделать с базовым (входным) изображением, которое указывается пользователем при использовании команды "сделатькартинку". Пока поддерживается только один тип манипуляции - приведение к фиксированном размеру ("fixed") по ширине и высоте. Если соотношение сторон в импортируемом изображении отличается от того, что указано в этом блоке, то после пропорционального изменения размеров, "лишние" части базового изображения будут отрезаны.

Блок "fonts" ("шрифты") это массив (список) шрифтов, которые будут использоваться в шаблоне. Файлы шрифтов должны быть доступны по протоколу http/https с внешнего вебсайта. Примером такого сайта является GitHub, где размещены некоторые хорошие шрифты, бесплатные для использования (см. пример выше). Помимо URL-ссылки на шрифт, должно быть указано имя семейства шрифтов ("font fam­i­ly"), чтобы позже вы могли ссылаться на шрифт по этому имени. Вы можете использовать любое имя, но лучше пользоваться тем, которое дали шрифту его создатели. В любом случае, перед импортом шрифта, система добавит к его имени айди вашей гильдии и название платформы, из которой он используется (т.е. "Dis­cord"), чтобы это имя не конфликтовало со шрифтами других гильдий. Вам не нужно знать этот префикс, потому он используется Ботом только внутренне.

Сейчас нет возможности использовать несколько разных текстовых сообщений в одном шаблоне, поэтому единственный смысл импортировать несколько шрифтов в одном шаблоне - это печатание одного и того же текста разными шрифтами (например, сам заголовок и его контрастную тень - см. пример выше).

Обратите внимание: разработчики Бота не несут ответственности за использование пользователем шрифтов, на использование которых у него нет лицензии. Это ваша ответственность - использовать только те шрифты, на которые у вас есть разрешение. В целом, мы рекомендуем использовать только шрифты, распространяемые по свободным лицензиям (таким, как OFL).

Блок "items" ("объекты") - это массив (список) дополнительных слоёв, которые должны быть наложены на базовый слой. То самое место, где происходит вся магия.

Объекты в этом массиве применяются от верхнего к нижнему (в UI программ типа GIMP или Pho­to­shop это происходит наоборот).

Слои могут быть вложены. То есть, слой изображения может иметь свой блок "items" в котором в свою очередь могут быть указаны дополнительные слои изображений или текстов. Это может быть полезно, если у вас в шаблоне есть область, значительно меньшая, чем весь базовый слой, и вы хотите проделывать манипуляции только с этой небольшой областью. Либо если вам удобнее размещать дополнительные слои относительно некоторой ограниченной области/другого слоя, а не всего базового изображения.

Объект может быть либо текстом, либо изображением. Тип объекта ("type") должен быть обязательно указан.

Атрибуты слоёв изображений ("image")

Если объект является изображением ("image"), то он может иметь следующие свойства:

url - ссылка на изображение на публично доступном ресурсе. Например, "https://mywebsite.org/uploads/stipe_under_title.png". Бот должен иметь достаточно разрешений, чтобы прочитать этот файл. То есть, недопустимо размещать файл там, куда есть доступ только по паролю. Кроме того, убедитесь, что картинка имеет статический путь, потому что если он изменится после создания шаблона, то Бот не сможет скачать картинку во время работы команды "создатькартинку".

autoscale (true/false) ("авто-масштабирование") - определяет, будет ли слой расширен/сужен до максимального размера, с которым он поместится в базовый слой.

align (top/left/bottom/right) ("привязка") - привяжет слой к одной из сторон базового слоя. Если указано "bot­tom" (низ), то левая сторона слоя будет привязана к левому краю базового слоя. Если указано "right" ("право"), то верхняя сторона слоя будет привязана к верхнему краю изображения. Если ничего не указано, то просто расширяет/сужает слой так, чтобы он занял собой базовое изображение.

blend ("смешивание") - должен быть объектом (заключённым в фигурные скобки - {}) с единственным свойством - mode ("режим"). Режим должен быть одним из существующих режимов смешивания в библиотеке JIMP (на данный момент это srcOv­er, dstOver, mul­ti­ply, screen, over­lay, dark­en, light­en, hard­Light, dif­fer­ence, exclu­sion). Если не указан, то слой просто накладывается на предыдущий с помощью линейного смешивания согласно значениям альфа-канала.

rotate ("вращение") - вращает слой по часовой стрелке на указанное количество градусов.

shear ("сдвиг") - вертикально сдвигает слой по косой линии на указанное число пикселей. Если число положительное, то двигает правый край вверх. Если число негативное, то двигает правое число вниз. Левый край при этом не двигается.

blur ("размытие") - размывает слой с радиусом в указанное число пикселей. Одно из применений этого параметра - это создание контрастных теней.

Атрибуты текстовых слоёв ("text")

Если объект является текстом (text), то он может иметь следующие свойства:

mar­gin ("край") - объект со следующими свойствами: left (лево), right (право), top (верх), bot­tom (низ). Каждое из этих свойств определяет, насколько далеко слой должен отстоять от соответствующего края базового слоя. Расстояние указывается в процентах от размера базового слоя.

style ("стиль") - объект со свойствами, которые поддерживаются библиотекой "text-to-image". Наиболее используемые и полезные свойства:

(style) font­Fam­i­ly ("имя шрифта") - имя шрифта из блока шрифтов ("fonts").

(style) font­Size ("размер шрифта") - размер шрифта в пикселях.

(style) line­Height ("высота строки") - высота строки в пикселях. Не имеет значения для текстов в одну строку, но важна для мульти-строчных текстов, потому что определяет, насколько далеко верхняя линия следующей строки будет отстоять от верхней линии текущей строки.

(style) tex­tAl­ign (left, right, cen­ter) ("привязка текста") - привязка строк текста к левому краю, правому краю или центру внутри текстового слоя.

(style) fontWeight (nor­mal, bold) ("вес шрифта") - определяет, должна ли использоваться нормальная версия шрифта или жирная.

(style) bgCol­or ("цвет фона") - цвет фона под текстом. Используйте "trans­par­ent" ("прозрачный") чтобы сделать слой под текстом прозрачным. Так же можно использовать известные названия цветов, типа "white", "black" и т.д., а также цветовые коды, типа "#000".

(style) text­Col­or - цвет текста. Можно использовать известные названия цветов, типа "white", "black" и т.д., а также цветовые коды, типа "#111".

rotate ("вращение") - вращает слой по часовой стрелке на указанное количество градусов.

shear ("сдвиг") - вертикально сдвигает слой по косой линии на указанное число пикселей. Если число положительное, то двигает правый край вверх. Если число негативное, то двигает правое число вниз. Левый край при этом не двигается. Если вы используете текст поверх какой-нибудь полосы шириной во всё изображение, и хотите сдвинуть оба слоя, то лучше указать mar­gin у текста слева и справа по 0. В таком случае горизонтальные линии у обоих слоёв до сдвига останутся параллельными и после сдвига.

blur ("размытие") - размывает слой с радиусом в указанное число пикселей. Одно из применений этого параметра - это создание контрастных теней.

Ограничения у шаблонов

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

Максимальное число шаблонов на одну гильдию - 30.

Максимальное число шрифтов на гильдию - 20.

Максимальная сложность шаблона - 200. Сложность считается как общая сумма всех свойств всех JSON объектов и массивов на всех уровнях вложенности.

Максимальная длина текста шаблона - 10000 символов.

Максимальный размер файла шрифта для скачивания 4194304 байт.

Максимальная ширина картинки-результата - 1920.

Максимальная высота картинки-результата - 1920.

Качество JPG для картинки-результата - 95.

Как создать шаблон

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

Однако одним из наиболее эффективных способов является создание шаблона при помощи программ Photoshop/GIMP, затем экспортирование оттуда слоёв как отдельных изображений, затем загрузка их на ваш (или какой-либо другой публично доступный) сайт, и, наконец, написание текста шаблона со ссылками на загруженные вами изображения.

Вот как был создан, например, однострочный шаблон Alteh Union:

1) Сначала, создайте проект в вашей программе манипуляции изображениями (Pho­to­shop, GIMP или другой). В этом случае мы используем GIMP, потому что он бесплатен, имеет открытый исходный код и во многом не уступает Photoshop:

1.1) Определите, какой размер по высоте и ширине должен быть у картинки в результате и убедитесь, что размеры холста в GIMP ему соответствуют (в нашем случае это 1280 на 720).

1.2) Загрузите какое-нибудь фоновое изображение (вам не нужно будет экспортировать его вместе с другими слоями, однако это поможет вам прикинуть, как будет выглядеть результат работы вашего шаблона). Измените его размер так, чтобы оно заполняло холст.

1.3) Добавьте дополнительные слои, которые вам нужны. Это может быть фоновая полоса за тестом, ваше лого, водяной знак, виньетка и т.д. Чтобы узнать, как создавать такие слои в вашем приложении, обращайтесь к руководствам по соответствующей программе.

1.4) Обратите внимание, как слои расположены относительно друг друга и холста. Вам будет нужна эта информация, когда вы будете писать текст шаблона. В наиболее простом случае все слои (кроме базового с примером изображения) будут совпадать по размеру со всем хостом (например, в нашем случае их размер будет 1280x720), так что вам не придётся определять, как из позиционировать.

1.5) Решите, какой режим смешивания нужен для каждого слоя. Например, здесь виньетка имеет нормальный ("nor­mal") режим смешивания, основная полоса за текстом имеет режим "умножение" ("mul­ti­ply"), и тонкие белые полоски по краям основной полосы - режим ("over­lay").

1.6) Определите, как шрифт вы будут использовать для текста. Учтите, что файл шрифта должен быть доступен Боту позже, так что не используйте шрифты, которые просто есть на вашей локальной машине, но нигде не выложены публично в Сети. Также, используйте только шрифты, на использование и распространение которых у вас есть право.

1.7) Напишите какой-нибудь примерный текст и разместите его в нужном вам месте. Используйте столько строк, сколько вы предполагаете использовать для этого шаблона. Хоть это и не всегда так, но как правило шаблоны рассчитаны только на строго определённое число строк, иначе текст будет вылезать по положенное ему место, вам придётся растягивать плашки под ним и т.п..

1.8) Обратите внимание, где ваш текст находится относительно других слоёв и края холста. Вам нужно будет подсчитать расстояние в процентах, чтобы спозиционировать текстовый слой в шаблоне. Также запомните размер шрифта.

2) Экспортируйте все слои как отдельные файлы в PNG-формате, кроме связанных с текстом (например, сам текст и его тень) и кроме примера базового изображения.

Чтобы экспортировать слой, временно смените режим его смешения на "нормальный", затем либо скопируйте его в новый проект, где размер холста будет совпадать с размером изображения, или, если размер холста в основном проекте уже совпадает с размером слоя, то сделайте все остальные слои невидимыми и просто экспортируйте нужный слой прямо из основного проекта.

Вот как выглядит подготовка к экспорту на примере слоя с плашкой под текстом:

3) Загрузите все заэкспортированные файлы картинок на публично доступный сайт, откуда вы сможете использовать их в шаблоне. Например, это может быть ваш сайт на Word­Press или даже социальная сеть (в последнем случае будьте осторожны, потому что прямые ссылки на изображения в соц. сетях могут быть динамическими, и в таком случае окажутся недоступными по старым ссылкам со временем).

В случае с Word­Press, войдите в панель администратора, например <ваш сайт>/wp-admin, затем выберите "Медиафайлы" -> Добавить новый -> выберите файл с вашего компьютера -> подождите, пока загрузка завершится -> обратите внимание, какую URL получила картинка на сайте - вам понадобится вставить её в шаблон.

Вот как выглядит загруженный на сайт Word­Press файл картинки от плашки под тестом:

4) Создайте текстовый файл для шаблона. Заполните его согласно формату, указанному в секциях выше. Или просто возьмите пример шаблона, приведённый выше, и доработайте его по своим нуждам.

В блоке "input" ("ввод") используйте те же значения ширины и высоты, которые были у вашего холста.

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

Для слоёв с изображениями - задайте привязку согласно с наблюдениями, проведёнными на шаге 1.4. Если слой совпадает с размером холста, то привязку и авто-масштабирование (align и autore­size) задавать не нужно, либо же просто задайте привязку как "left" (слева).

Для текстовых слоёв - сначала укажите ссылку на файл со шрифтом в блоке шрифтов ("fonts"), и затем укажите соответствующее имя шрифта в слое - в блоке стиля ("style") -> в свойстве "имя семейства шрифта" ("font­Fam­i­ly").

Для текстовых слоёв - задайте отступ от краёв ("mar­gin") согласно процентам, посчитанным на шаге 1.8. Как правило, вам нужно задать только верхний отступ ("top"), если текст расположен горизонтально по центру, а также левый отступ ("left"), если текст расположен горизонтально не по центру. Отступы справа и снизу ("right" и "bot­tom") нужно задавать, только если вы хотите ограничить размер слоя с текстом.

Укажите тот же размер шрифта ("font­Size"), который вы использовали в вашей программе редактирования изображений. То же самое с цветом текста. Цвет фона, как правило, нужно будет выставить как прозрачный ("trans­par­ent").

Если вам нужна контрастная тень позади текста, то просто скопируйте/ставьте существующий текстовый слой, и в получившемся слое просто добавьте свойство размытия ("blur") а также измените цвет шрифта на чёрный ("black"), например.

5) Протестируйте ваш шаблон с помощью команд Бота, указанных в предыдущих секциях ("добавитьшаблонкартинок" - "addim­agetem­plate", "создатькартинку" - "cre­ateim­age"). Если шаблон работает не так, как нужно - удалите его с помощью команды "удалитьшаблонкартинок" - "deleteim­agetem­plate", исправьте текст шаблона у себя на компьютере, и затем повторите этот пункт.

Цензурирование

Позволяет заменять нецензурные слова специальными символами.

Предварительно нужно настроить список нецензурных слов с помощью команды !addbad­words через запятую. Например:

!addbad­words матерноеслово, ещёматерноеслово

(!добавитьплохиеслова матерноеслово, ещёматерноеслово)

Кроме того, нужно включить саму функцию цензурирования (доступно только администраторам сервера) с помощью команды:

!set­cen­sor­ing on

(!задатьцензуру вкл)

После этого, если кто-то напишет сообщение с указанными словами в любой текстовый канал, оно будет заменено ботом на аналогичное, но с нецензурными словами, заменёнными на спец. символы. Например:

Посмотреть текущий список нецензурных слов можно при помощи команды !bad­words (!плохиеслова), а удалить их из списка можно при помощи команды !remove­bad­words (!удалитьплохиеслова) со списком удаляемых слов через запятую.

Выключить цензурирование можно при помощи команды:

!set­cen­sor­ing off

(!задатьцензуру выкл)

Типичные проблемы с ботом

Проблемы с упоминаниями

Для многих команд бот использует так называемые упоминания (men­tions) в качестве аргументов. Упоминания формируются Дискордом автоматически при вводе имени пользователя, роли или канала. Но иногда этот механизм не срабатывает и Дискорд пишет простой текст. Если такой простой текст отправляется к боту, то он, как правило, считает это ошибкой, несмотря на то, что визуально всё может выглядеть правильно.

Упоминание от простого текста можно отличить по следующим признакам:

  1. Упоминания выделяются цветом.
  2. При наведении курсора мыши на упоминание, курсор меняется на "руку".
  3. При нажатии на упоминание срабатывают опции, связанные с упомянутым пользователем, ролью или каналом.

К примеру, на данном скрине @ServerAdmin и @moderator - это упоминания, а @Batman - простой текст:

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

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

Проблемы с указанием времени

OrgHelper использует гибкую систему считывания аргументов, связанных со временем.

Бот последовательно читает символы из команды до тех пор, пока не наткнётся либо на слово, которое не получается трактовать как часть времени, либо на часть времени, которая не совместима с предыдущими частями.

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

Поэтому, если аргумент времени был введён неправильно, это может привести к непредсказуемым последствиям.

Например, в следующей команде:

!напомнить каждые Вос 15:30 Сдать отчётность!

Сокращённые имена дней недели на русском языке для бота - это Пн, Вт, Ср, Чт, Пт, Сб, Вс. "Вос" не является определением дня недели, поэтому бот посчитает, что аргумент времени закончился уже на слове "каждые", а не на "15:30". То есть, весь текст "Вос 15:30 Сдать отчётность!" он посчитает текстом напоминания, а в определение времени запишет только часовой пояс пользователя. Естественно, правильного расписания напоминания из этого не получится. Но мало этого, бот ещё и может не сообщить об ошибке, потому что с его точки зрения запрос пользователя выглядит хоть и странно, но грамматически корректно.

Отсюда вывод: быть внимательным при вводе временных аргументов. В частности, при создании напоминаний - проверять, что получилось при помощи команды !reminders (!напоминания).

Если у вас есть идеи, как сделать использование аргументов времени более интуитивно понятным - напишите нам.

Политика конфиденциальности

Ознакомиться с политикой конфиденциальности бота можно здесь: http://alteh.org/orghelper-privacy-policy/

Для реализации политики конфиденциальности существует специальная команда !myda­ta, которая доступна только в приватной переписке с ботом (в так называемом "DM" или "direct mes­sages"). Команда выводит все данные, непосредственно связанные с вами хранимые ботом.