HELPER Discord Bot
← К списку Wiki
PROFILE CORE // ID CARDS // WEBP RENDER

HELPER PROFILES ID-КАРТЫ ИГРОКОВ /PROFILE / AVATAR CDN / SHOP.DB / REPUTATION.DB / PROCESS POOL

Profiles превращает сухие цифры экономики и репутации в красивую личную ID-карту участника. Игрок вводит /profile, выбирает стиль Glass / Neon / Minimal / Golden, а HELPER подтягивает аватар, баланс, влияние, ранг и отправляет готовую WebP-картинку прямо в Discord.

Показать картинки Путь профиля 4 стиля
850×320profile card
4glass/neon/minimal/golden
10scommand cooldown
WEBPcache render
Command/profile user style
RenderPillow рисует WebP 850×320
Datashop.db + reputation.db
Cacheavatar hash + balance + points
Safetymodule_states disabled-view
// MODULE_PURPOSE

Что делает Profiles

Это визуальная карточка личности участника. Внутри неё: Discord-аватар, display name, статус по репутации, очки влияния, баланс экономики и прогресс до следующего ранга. Карточка генерируется как WebP-файл и отправляется в embed.

01

Команда

Игрок вызывает /profile, выбирает user и style.

02

Данные

Бот читает balance из экономики и points из reputation.

03

Рендер

ProfileRenderer собирает WebP-карту 850×320.

04

Discord

Картинка отправляется как attachment://id_card_*.webp.

// VISUAL_GUIDE

Больше информации картинками

Полный путь глазами игрока и администратора: команда, выбор пользователя, выбор стиля, загрузка аватара, готовая WebP-карточка, cache-hit, пустые данные и disabled-state.

01 / commandИгрок вводит /profile
💬
slash command/profile

Параметры команды

user: @Player или пусто = свой профиль
style: glass / neon / minimal / golden
Получить визуальную ID-карту
02 / deferБот начинает генерацию

⏳ Генерация карточки

Бот делает defer, проверяет модуль, скачивает avatar bytes и собирает stats.

ensure_profiles_active → fetch avatar → render
03 / card outputГотовая ID-карта
👤
attachment webpid_card_*.webp

👤 Профиль участника

Embed показывает attachment-картинку, а footer пишет активный стиль.

AVATAR / STATUS / BALANCE / PROGRESS
attachment://id_card_guild_user_time.webp
04 / profile fieldsЧто внутри карточки
profile card850×320
AvatarDiscord CDN 256px PNG
image
Display Nameemoji очищаются для Pillow
safe
RankИЗГОЙ / АКТИВНЫЙ / ДОВЕРЕННЫЙ / ЛЕГЕНДА
status
Progressвизуальная шкала по points
bar
05 / cache hitБыстрый повтор

⚡ Fast cache

Если avatar_hash, стиль, balance и points не изменились, HELPER отдаёт готовый WebP из cache.

profile_fast_cache
06 / empty dataЕсли цифр нет

Нули в профиле

Если в shop.db или reputation.db нет записи по guild_id/user_id, бот покажет 0 balance и 0 influence.

NO STATS YET
// DISCORD_COMMANDS

Команда Discord

У модуля одна главная команда. Она открыта игрокам, но защищена cooldown 10 секунд на пользователя, чтобы массовые рендеры не грузили сервер.

main command/profile
/profile user:@Player style:glass

Показывает ID-карту выбранного пользователя. Если user не указан — показывает профиль вызвавшего игрока.

style choicesВыбор стиля
🪞 Glassmorphism → glass 🌃 Neon Cyberpunk → neon 🌑 Minimal Dark → minimal 👑 Golden Luxury → golden

Стиль влияет на blur, glow, overlay, тени, цвет акцента и настроение карточки.

cooldownЗащита от спама
@commands.cooldown(1, 10, BucketType.user)

Если игрок спамит команду, он получает сообщение: “Подождите N секунд”.

server onlyТолько сервер
guild required → ❌ Профили доступны только на сервере.

В личных сообщениях модуль не работает, потому что данные берутся по guild_id.

// PROFILE_FLOW

Путь профиля от команды до WebP

1/profile

slash

2State

module on

3Stats

DB read

4Avatar

CDN fetch

5Render

process pool

6Send

attachment

A

User lock

Для одного guild_id/user_id не запускается несколько одинаковых рендеров одновременно.

B

Active renders

Если такой cache_filename уже рендерится, второй запрос ждёт existing future.

C

Safe errors

Timeout Discord CDN, ошибка аватара или render exception возвращаются понятным сообщением.

// PLAYER_FLOW

Что видит игрок

self profileСвой профиль

Моя ID-карта

Игрок вводит /profile без user и получает свою карточку с текущим балансом и репутацией.

target = inter.user
other memberПрофиль другого игрока

Посмотреть участника

В параметре user можно выбрать другого участника сервера и посмотреть его карточку.

/profile user:@Arctic style:neon
error cdnCDN не ответил

❌ Ошибка загрузки аватара

Если Discord CDN не отдал аватар или превысил timeout, игрок получает короткое понятное сообщение.

avatar fetch failed
cooldownПовтор слишком быстро

⏳ Идёт генерация

Команда ограничена cooldown, чтобы игроки не спамили ProcessPool рендером.

10 sec / user
// ADMIN_FLOW

Что делает администратор

01

Включает модуль

На сайте включает profiles/profile в module_states.json.

02

Экономика

Баланс должен попадать в shop.db с guild_id и user_id.

03

Репутация

Очки influence должны попадать в reputation.db.

04

Фоны

Можно положить локальные изображения в backgrounds/ для общего визуального вайба карточек.

Важный момент

У этого модуля нет сложной web-настройки стилей: сайт управляет доступностью, а конкретный стиль выбирается пользователем в Discord-команде.

// DATA_SOURCES

Откуда берутся цифры

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

balanceБаланс
shop.dbосновная база экономики.
tablesusers, shop_users, economy_users, balances.
score columnsbalance, money, cash, coins, points.
WHEREguild_id + user_id текущего сервера.
reputationРепутация / влияние
reputation.dbосновная база кармы.
tablesserver_reputation, reputation, users, user_reputation, reputation_users.
score columnspoints, reputation, rep, karma, score.
rankpoints превращаются в статус и цвет ранга.
rank mapСтатусы
rank config
ИЗГОЙ-∞ до -21 points
grey
АКТИВНЫЙ-20 до 100 points
blue
ДОВЕРЕННЫЙ101 до 500 points
violet
ЛЕГЕНДА501+ points
gold
guild safeЗащита данных

Guild-safe read

Legacy-таблицы без guild_id специально пропускаются. Профиль одного сервера не подтянет чужой баланс.

CAST(guild_id AS TEXT) = current guild
// CACHE_ENGINE

Кэш и скорость

Профили рендерятся тяжело, поэтому модуль использует ProcessPoolExecutor, disk cache, user lock и active render future.

1Hash

avatar bytes

2Name

cache file

3Disk

read cache

4Future

same render

5Pool

new render

6Clean

old files

cache keyЧто входит в имя файла
guild_idодин user на разных серверах получает разные файлы.
user_idвладелец карточки.
styleglass/neon/minimal/golden.
avatar_hashсмена аватара пересобирает card.
balance + pointsсмена цифр создаёт новый WebP.
cache folderdata/cache/profiles
cache filename
profile_123456789_987654321_glass_a1b2c3d4e5f6_12450_240.webp profile_123456789_987654321_neon_a1b2c3d4e5f6_12450_240.webp output: id_card_123456789_987654321_1717450123.webp
workersProcessPool

Отрисовка вне bot-loop

Количество workers считается от CPU: минимум 1, максимум 4. Это не блокирует основной Discord loop.

run_in_executor(process_pool, run_render_sync)
cleanupОчистка старого кэша

cleanup_old_cache_async

После нового рендера старые WebP этого пользователя/стиля удаляются, чтобы cache не разрастался.

keep_filename = current cache
// DASHBOARD_SETTINGS

Настройка на сайте

В текущем модуле сайт управляет главным переключателем доступности через data/module_states.json. Детальные визуальные стили выбираются пользователем в команде.

dashboard mockupProfiles settings
profilesmodule state
Статус модуляВключён / выключен
toggle
Ключ состоянияprofiles
main
Aliasprofile / id_cards / cards
compat
Dashboard path/dashboard/guild/<id>/profiles
route
module statesmodule_states.json
data/module_states.json
{ "123456789": { "profiles": true, "profile": true } }
disabled aliasesСовместимость
profilesосновной ключ модуля.
profileкороткий alias.
id_cards / id-cardsстарые названия ID-карт.
cards / profile_cardsдополнительные alias.
future ideaЧто можно добавить позже
default_styleстиль по умолчанию сервера.
access_role_idsограничить команду ролями.
background_keyотдельный фон из Visual Core.
currency_labelзаменить PTS на ₽, COINS или RP.
// SAFE_DISABLED

Если модуль выключен

Если profiles выключен в module_states.json, команда не запускает рендер и показывает красный disabled embed.

disabled embedЧто видит игрок
🔌
safe stateПрофили отключены

🔌 МОДУЛЬ ПРОФИЛЕЙ ОТКЛЮЧЁН

Система визуальных ID-карт временно отключена администратором сервера.

🔌 ПРОФИЛИ ОТКЛЮЧЕНЫ
safe effectsЧто сохраняется
shop.dbбаланс игроков не удаляется.
reputation.dbрепутация игроков не удаляется.
cache/profilesстарые cache-файлы не критичны и могут быть пересозданы.
after enableпосле включения команда снова генерирует ID-карты.
// DEVELOPER_MAP

Карта технической логики

filesФайлы и данные
SHOP_DB

data/shop.db — баланс игрока.

REP_DB

data/reputation.db — reputation/karma/points игрока.

CACHE_DIR

data/cache/profiles — готовые WebP-карточки.

MODULES_FILE

data/module_states.json — включение/выключение profiles.

BG_DIR / FONTS_DIR

backgrounds/ и fonts/ используются renderer.

constantsГлавные константы
🖼️
WIDTH850×320
👤
AVATAR240 px
🎨
STYLES4 режима
🧊
COOLDOWN10 секунд
📦
CDN LIMIT4 MB
🔌
TTLstate cache 10s
ProfileCogОсновной pipeline
profile_cardslash-команда /profile.
send_profileпроверка сервера, состояния, defer и отправка embed.
fetch_avatar_bytesскачивание avatar PNG с Discord CDN.
render_or_get_cachedisk cache, active future, process pool.
cleanup_locksраз в 30 минут чистит неактивные user locks.
ProfileRendererЧто рисуется
get_backgroundлокальный фон из backgrounds/ или blur-аватар.
draw_avatarкругло-скруглённый avatar + glow.
draw_user_infousername, underline и акцент.
draw_stat_pillСТАТУС, ВЛИЯНИЕ, БАЛАНС.
draw_progress_barпрогресс до следующего уровня.
// TROUBLESHOOTING

Ошибки и решения

Почему у игрока нули?

В shop.db или reputation.db нет записи по guild_id/user_id, либо таблица не содержит нужную score-колонку.

Можно посмотреть профиль другого игрока?

Да. В /profile есть параметр user, поэтому можно выбрать участника сервера.

Почему картинка не обновилась сразу?

Если avatar_hash, стиль, balance и points такие же, бот отдаёт готовый WebP из cache.

Почему Discord CDN не отвечает?

Бот отдаёт timeout/ошибку аватара. Обычно достаточно повторить команду позже.

Почему профиль не работает в ЛС?

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

Почему emoji пропали из ника?

Emoji очищаются перед Pillow-рендером, чтобы старая font-система не ломала картинку.

// WIKI_NAVIGATION

Вернуться к списку Wiki

Ты дошёл до конца страницы Profiles. Можно вернуться в общий центр документации, открыть Dashboard или подняться наверх к началу этой страницы.

← К списку Wiki Dashboard Наверх ↑