Пока недоступен в магазине Discord. Можно установить на сервер тут

ENGLISH README

EXPIFY

Дискорд бот для серверов, с улучшенной системой левелинга Текста, Голоса и Видео. Поддерживает отключение типов опыта, регулировку скорости заработка опыта, начисление ролей-наград, каналы, пользователи и роли без получения опыта и многое другое с ориентацией на максимально честное соревнование в активности сервера.

• EXPIFY
• Система начисления опыта
  • Базовые правила
  • Текстовый опыт
  • Голосовой опыт
  • Опыт видео
• Начисление наград и режимы
  • Режимы наград
• Уровни доступа
• Миграция
  • Справка
• Ограничение команды /rank для использования только в конкретном канале
• Локализация
• Просмотр своего уровня
• Управление очками опыта на сервере
  • Сброс опыта всех участников сервера
  • Отключить любой вид опыта на сервере
  • Запретить получать опыт для пользователя/роли/канала
  • Установить своё количество базового опыта в минуту
• Управление наградами сервера
  • Добавление награды
  • Обновление награды
  • Удаление награды
  • Просмотр списка наград
  • Забрать награды у участников, которые не соответствуют требованиям для них
• Отображение топа сервера
• Просмотреть настройки сервера
• Указать каналы для уведомлений от бота
• Прочее

Система начисления опыта

Я постарался сделать максимально честную систему начисления пользовательского опыта всех типов основываясь на замечаниях в течении шести лет администрирования нашего Discord сервера.

Базовые правила

• Максимальное количество опыта для которого работают функции: 160280000xp (160 миллионов)
  • Соответственно максимальный уровень: 1000
  • Если вам кажется это маленьким: При минимальном базовом значении 5, вам придётся сидеть в голосовом чате до максимального уровня ~61 год без перерыва. При стандартном 10: ~30 с половиной лет, а при максимальном 100: ~3 года
• Опыт начисляется раз в минуту по всем условиям установленым в системе
• Выдача установленых наград производится раз в 5 минут всем пользователям которые проявили активность за последние несколько минут и по завершении процесса если вы установили канал для уведомлений придёт комбинированное сообщение с людьми которым выдали награды и какие. При этом сообщение встроенное, поэтому пинговать людей и роли оно не будет.
• Опыт каждого уровня имеет базовое значение, которым может управлять администратор с помощью команды /expify gain для того чтобы. Стандартные значения: text = 20, voice = 10, video = 20 (xp/мин).
• На каждую итерацию начисления опыта участникам применяется случайный множитель к базовому значению от x0.8 до x1.2. Эти множители зашиты главным правилом и менять их нельзя.
• Администратор может отключить любые типы опыта для сервера с помощью /expify toggle. Отключенные типы опыта не начисляются участником и не указываются в /top и /rank
• Модераторы и администраторы могут устанавливать объекты которые не будут учитываться в рассчёте опыта с помощью /noxp. Пользователи указаные в списке не будут получать опыт, за активность в каналах указаных в списке не будет начисляться опыт, пользователи с ролями указаными в списке не будут получать опыт.
• Боты не получают опыт

Текстовый опыт

Формула: Base_Text * 0.8~1.2

Все правила выше учитываются.

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

Голосовой опыт

Формула: Base_Voice * 0.8~1.2

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

• Пользователь получает опыт за каждую минуту, проведённую в голосовом канале
• Пользователь не получает опыт если находится в канале один или вдвоём с ботом
• Пользователь не получает опыт если его микрофон выключен
• Пользователь не получает опыт если выключен микрофон у всех участников канала, кроме самого пользователя

Опыт видео

Формула: Base_Video * 0.8~1.2 + (Base_Video * 0.25) * 0.8~1.2

Все правила выше учитываются. Этот тип обычно отсутствует у многих систем левелинга, но я решил его внедрить поощряя дополнительную активность в голосовых чатах при этом сохранив честную конкуренцию голосового опыта, так как не все могут сидеть со стримами и веб-камерами.

• Пользователь получает опыт видео за каждую минуту активного стрима или веб-камеры в голосовом чате
• Количество людей смотрящих трансляцию не влияют на количество получаемого опыта
• За включенную веб-камеру пользователь получает полный базовый опыт умноженный на множитель опыта текущей итерации. Веб-камеры используются редко, что делает их более ценными.
• За включенную трансляцию экрана пользователь получает 25% от базового опыта умноженный на множитель опыта текущей итерации. Такой множитель объяснён тем, что довольно многие пользователи транслируют экран почти 80% времени нахождения в канале. Если важно облегчить получение опыта видео, то администратор может повысить базовое значение с 20xp до любого, не привышающего 100xp.
• Если участник канала включил и трансляцию экрана и веб-камеру, то полученный опыт за оба складывается и начисляется пользователю. Пример: 20 * 0.95 + (20 * 0.25) * 0.95 = 23.75 = 24
• Пользователь не получает опыт если находится в канале один или вдвоём с ботом
• Пользователь не получает опыт если его микрофон выключен
• Пользователь не получает опыт если выключен микрофон у всех участников канала, кроме самого пользователя

Начисление наград и режимы

Начисления наград производится раз в несколько минут по последней активности если пользователь соответствует условиям для получения. Если установлен канал для анонсов в /expify channels, то уведомление о вручении наград придёт туда во встроенном сообщении чтобы не пинговать пользователя и роли каждый раз когда их кто-то получает.

Режимы наград

Изменять режим вручения наград можно с помощью команды /reward mode

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

• Дополнительных условий нет.

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

Представим пример: (⌨️: Текстовый опыт, 🎙️: Голосовой опыт, 🎦: Видео опыт)

• Роль 1 требует: (⌨️ 45 LVL) + (🎙️ 45 LVL) + (🎦 45 LVL) - Комбинированая
• Роль 2 требует: (⌨️ 50 LVL) + (🎙️ 60 LVL) - Комбинированая
• Роль 3 требует: (🎙️ 45 LVL) - Одного типа
• Роль 4 требует: (🎙️ 60 LVL)
• Роль 5 требует: (🎦 75 LVL)

Пользователь уже заработал Роль 1, и Роль 3, но текущий уровень у него: (⌨️ 56 LVL) + (🎙️ 59 LVL) + (🎦 74 LVL). Он ещё не соответсвует по требованиям для Роль 2, Роль 5 и Роль 4

Теперь пользователь заработал (🎙️ 60 LVL), всего: (⌨️ 56 LVL) + (🎙️ 60 LVL) + (🎦 75 LVL). Он заслужил Роль 2, Роль 5 и Роль 4. Если у вас установлен режим (Оставить только наивысшие награды) бот будет следовать следующим образом:

• Начислить пользователю Роль 2, Роль 4 и Роль 5
• У пользователя уже есть роль такого же типа с уровнем ниже чем у Роль 4 - Роль 3. После выдачи Роль 4 мы забираем Роль 3.
• У Роль 5 нет начисленых пользователю аналогов, поэтому мы больше ничего не забираем
• Роль 1 остаётся даже с Роль 2, потому что они имеют комбинированый тип и не идут в сравнение.

Уровни доступа

У бота нет кастомного режима разграничения прав. Права на видимость и использование команд безопасно разграничены битмапами разрешений Discord.

• Команды /rank, /ping, /invite, /about доступны всем участникам сервера
• Команда /top доступна только для людей с правом на управление сообщениями
• Команда /lang. Команды /reward, /xp, /noxp - напрямую дают управление наградами, ролями и прочими параметрами, поэтому доступны только людям с правом на Управление ролями
• Команда /expify с её подразделами позволяет делать самые опасные действия, которые зачастую нужно настроить только единожды при внедрении бота. Она доступна только пользователям с правами администратора на сервере.

Миграция

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

Для этого нужно добавить эти роли как награды с помощью /reward add с нужным количеством опыта для каждой роли. Обновить их можно указав в /reward add ту же самую роль, которая уже была добавлена в награды, с новыми требованиями к опыту. Проверить и узнать ID можно с помощью /reward list. Удалить награду можно используя /reward remove указав ID награды которую нужно удалить.

Для того, чтобы в топе сервера значения не были линейными (Десятки людей с полностью одинаковым количеством опыта), начисляется не в точности такое же количество опыта, а немного больше. Однако если в вашей старой системе у пользователя очень высокий уровень (100+), он может в зависимости от его удачи получить значительную прибавку к опыту. Множитель определяется заново для каждого типа опыта и каждого пользователя. Формула: Reward_XP * 1~1.0250.

Справка

Справка из /expify migrate-help:

👉 /expify migrate - Это команда, при помощи которой вы можете восстановить часть прогресса от других ботов или ручного награждения, путём соотношения настроенных наград и ролей которые выданы участникам сервера.

🚀 С чего начать?

• Вам нужно создать награды в /reward add с требованиями для получения награды.

Вы можете добавить до 30 наград одновременно и использовать несколько типов опыта для её получения

⚡ Что сделает бот?

Когда вы будете уверены с требованиями к ролям (Можно проверить через /reward list), вы можете выполнять эту команду.

Бот соберёт ваши созданные награды и начнёт проверять какие роли есть у пользователей вашего сервера

• Если у человека нашлась одна роль из наград, то бот выдаст ему количество опыта всех типов которые назначены как награда к этой роли
• Если у человека нашлось несколько ролей, то для каждого вида опыта будет учитываться максимальное значение награды. Так если (роль1) даёт 500 опыта этого типа, а (роль2) 1000 опыта, то выдано будет количество опыта от роли2
• Если человек на сервере получил больше опыта определённого типа, чем дают его роли, то его заработанный опыт останется нетронутым Чтобы топ сервера был менее линейным после миграции каждый случайным образом получает до x1.025 опыта от базового значения. Активные пользователи с лёгкостью смогут обойти неактивных

❗ОБРАТИТЕ ВНИМАНИЕ

• Будьте внимательны, бот перезапишет все значения опыта, которые попадают под условия выше. Отменить это действие невозможно!
• /expify migrate Можно использовать не чаще чем 1 раз в неделю!

Ограничение команды /rank для использования только в конкретном канале

Вы можете сделать это с помощью команды /expify channels выбрав в ней соответствующий раздел.

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

• Независимо от аргументов команды, если она использована вне разрешённого чата - ответ будет видеть ТОЛЬКО пользователь, который её использовал
• Если она будет использована в разрешённом чате, то она будет опубликована для всех, даже если пользователь указал аргумент публичного ответа как false

Локализация

Бот поддерживает несколько языков и всегда отвечает на команды языком вашего интерфейса, если он поддерживается. Однако уведомления о полученых наградах и административные события будут на стандартном языке. Чтобы сменить язык сообщений которые бот отправляет независимо от ответа на вашу команду - используйте команду /lang. Если ваш язык интерфейса входит в перечень поддерживаемых, он будет установлен на вашем сервере как основной. Если нет, то вы можете выбрать язык из списка поддерживаемых внутри команды.

Если вы хотите помочь с переводом бота на ваш язык, вы можете создать issue с описанием того, что нужно поправить или отправить нам полноценный Pull Request с изменениями в locales.json.

Просмотр своего уровня

Любой пользователь с правом на использование команд может проверить свой уровень написав /rank. Команда выведет ваш уровень, общее количество очков и прогресс до следующего уровня для всех видов опыта, которые не отключены на сервере администратором. Если установлено ограничение на использование этой команды во всех чатах, вы сможете использовать команду, но не сможете отобразить ответ публично.

Управление очками опыта на сервере

Для того чтобы выполнять большинство операций с очками опыта пользователей вы можете использовать команду /xp. Так, для того чтобы добавить очки опыта используется /xp add, а чтобы отобрать очки опыта /xp remove. Вы можете устанавливать сразу уровень пользователя, вместо очков с помощью /xp set-level или сбросить какой-то конкретный тип опыта или все сразу используя /xp reset.

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

Сброс опыта всех участников сервера

Если вам по какой-то причине понадобилось сбросить прогресс всех пользователей серера, сделать это может человек с правами администратора при помощи команды /expify xp-reset. Обратите внимание что это действие нельзя отменить, так как пользователи сразу стираются из базы данных до момента получения первых очков опыта на сервере.

Для того чтобы забрать награды пользователей, вам потребуется команда /expify cleanup-rewards. Её описание также есть в этом документе

Отключить любой вид опыта на сервере

При помощи команды /expify toggle администраторы могут включать/отключать Текстовый, аудио или видео опыт для сервера в любой комбинации (Даже вовсе всё выключить). Пользователи не потеряют заработанный опыт отключенного вида, но больше не будут видеть его при использовании /rank и не смогут зарабатывать этот вид опыта до момента его включения. Команда /top тоже не позволяет просматривать отключенные типы опыта, поэтому просто "Заморозить" таблицу не выйдет.

Запретить получать опыт для пользователя/роли/канала

Как и во многих других системах тут можно запретить заработать опыт, например, "фермерам" или просто плохим людям, а также запретить получать опыт в АФК и спам-каналах. Для этого можно использовать команды:

• Для добавления каналов, за активности в которых участникам не будет начислен опыт: /noxp channel
• Для добавления отдельных пользователей, которые больше не смогут получать опыт: /noxp user
• Для добавления ролей, с которыми пользователи больше не смогут получать опыт: /noxp role

Если вы хотите удалить конкретный элемент из списка, просто укажите его в команде повторно. Например если в списке есть @роль1 и её нужно оттуда убрать, просто повторно напишите /noxp role @роль1

Этот список ограничен по размеру на каждый сервер. Проверить что вы уже поставили и сколько свободного места у вас есть можно написав команду /noxp list

Если вы удалили с сервера элемент, который есть в этом списке и не сохранили его ID, вам придётся использовать команду /noxp reset для сброса конкретного списка с которым у вас возникла проблема и после добавить нужные элементы заново.

Установить своё количество базового опыта в минуту

Почти все расчёты получаемого опыта в минуту сводятся к формуле: Base * 0.8~1.2. Мы не можем дать вам возможность управлять множителем, но мы можем позволить вам управлять базовым опытом. Для этого администратор может воспользоваться командой /expify gain, выбрать в ней нужный тип опыта и указать количество базового опыта для этого типа. При расчётах баланса для своего сервера учитывайте что пользователям может выпасть до x1.2 опыта от вашей базы за минуту, а со включенным стримом и веб-камерой одновременно до х1.5 видео опыта. Вы можете регулировать количество базового опыта в пределах от 5 до 100. Для того чтобы посмотреть текущие параметры опыта на вашем сервере - используйте команду /expify get и выберите соответствующий раздел. Там будут показаны не только базовые значения в минуту, но и рассчёты этих значений от минимума до максимума за минуту.

Управление наградами сервера

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

Вы можете использовать команду /reward mode чтобы выбрать свой режим наград для сервера. О режимах наград написано выше.

Добавление награды

Чтобы добавить награду вы должны использовать команду /reward add. Вы можете установить ограниченое количество наград, общее количество вы можете узнать в списке наград. В аргументах к команде вы должны указать роль, которую хотите сделать наградой, а также от одного до трёх условий её получения. Условия указываются в уровнях. Как только участник выполняет все условия награды, через небольшой промежуток времени ему будет начислена эта роль. В ответ на добавление награды бот вернёт вам сообщение об успехе и ID вашей награды в нашей базе данных

Обновление награды

Если вы допустили ошибку или установили другие уровни специально, чтобы совершить миграцию и хотите вернуть награду на сбалансированые значения - вам нужно повторно использовать команду /reward add. Система не позволит вам иметь одну и ту же роль в двух разных наградах, поэтому чтобы обновить существующую награду, просто укажите в аргументах ту самую роль которая уже есть в списке и условия получения которой вы хотите обновить. Укажите роль и новые условия, после этого бот вернёт вам ответ что награда была обновлена

Удаление награды

Для удаления награды используется отдельная команда /reward remove. В аргументах к команде нужно указать ID награды которую вы хотите удалить. Узнать вы его можете при создании награды и в списке созданых наград.

Просмотр списка наград

Вы можете просмотреть список настроенных наград при помощи команды /reward list. В ответе будут перечислены все награды, роли, условия для получения и ID. Также будет указан режим начисления наград который сейчас установлен на вашем сервере.

Забрать награды у участников, которые не соответствуют требованиям для них

Обычно такое может произйти после полного сброса опыта на сервере или масштабной переработки требований к вашим наградам. Мы предусмотрели такую возможность, администраторы серверов смогут отобрать незаслуженные награды по новым требованиям с помощью /expify cleanup-rewards. ОБРАТИТЕ ВНИМАНИЕ!

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

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

Отображение топа сервера

Если у вас есть как минимум права на управление сообщениями (Вы модератор) - вам доступна команда /top. Вы сможете вывести топ сервера по любому из включённых на сервере видов опыта, выбрав его в аргументах. Также при использовании команды вы сможете выбрать страницу топа и нужно ли его отправить видимым для всех public: true. Можете подводить итоги каждую неделю, при плотном состязании. Максимально на странице отображается 10 элементов.

Просмотреть настройки сервера

Все настройки доступны в четырёх разделах команды /expify get.

• В разделе с начислением опыта вы увидите какие виды опыта включены на вашем сервере и какое количество XP в минуту получают участники при текущей базе и множителях
• В разделе с каналами вы сможете увидеть настроенные каналы для уведомлений и ранкинга
• Раздел объектов не получающих опыт это алиас к /noxp list
• Раздел наград это алиас к /rewards list

Указать каналы для уведомлений от бота

Указать каналы для того чтобы бот присылал в них сообщения об определённых событиях можно с помощью команлы /expify channels. В аргументах выберите категорию и выберите канал для этой категории. Для просмотра установленных каналов вы можете, как описано выше, использовать /expify get. Чтобы отключить канал, выберите раздел и оставьте поле где вы указывали канал пустым. После этого в списке появится надпись "Отключен".

• Уведомления о получении наград: В этот канал будет приходить красивое встроенное сообщение когда всякий раз бот вручает награду пользователю. Если награда начисляется сразу нескольким пользователям одновременно и даже в случае если начисленных наград несколько, всё придёт в едином сообщении, не засыпая спамом сервер. На длинну такого сообщения есть лимит, если участников слишком много, сообщение может быть отрезано.
• Административные уведомления: В этот канал будут приходить уведомления в случае ошибок выдачи наград, а также в случае исполнения серьёзных административных действий через бота, с упоминанием пользователя который совершил действие.
• Разрешить проверять ранг только в этом канале: Ограничивает возможность публичных ответов бота на команду /rank. Об этом описано выше...

Прочее

Создайте Issue в этом репозитории в случае проблем. Вы можете связаться со мной на нашем Discord сервере @shulkerplay.