Reaction Roles

Moduł Reaction Roles umożliwia użytkownikom samodzielne przypisywanie sobie ról przez interakcję z wiadomościami bota — za pomocą przycisków, menu rozwijanego (dropdown) lub reakcji emoji.

Włączanie modułu

1. Dashboard → Twój serwer → toggle Reaction Roles
2. Kliknij Edit aby zarządzać konfiguracjami
3. Dodaj nową konfigurację (panel) lub edytuj istniejącą
4. Wdroż (deploy) konfigurację na wybrany kanał

Tryby interakcji

Tryb	Opis
buttons	Przyciski pod wiadomością — jedno kliknięcie = toggle roli
dropdown	Menu rozwijane z wielokrotnym wyborem
reactions	Klasyczne reakcje emoji pod wiadomością

Zachowanie (behavior)

Tryb	Opis
toggle	Kliknięcie dodaje rolę, ponowne kliknięcie ją usuwa
add_only	Kliknięcie tylko dodaje rolę — nie można jej usunąć tym sposobem

Konfiguracja

Każda konfiguracja reaction roles (panel) zawiera:

Opcja	Typ	Opis
mode	string	Tryb: buttons, dropdown, reactions
behavior	string	Zachowanie: toggle, add_only
channel_id	string	Kanał docelowy
embed	object	Konfiguracja embeda (tytuł, opis, kolor)
role_mappings	array	Lista mapowań: emoji → rola
max_roles	number	Max ról do wyboru w dropdown (domyślnie 25)
placeholder	string	Tekst placeholder w dropdown

Struktura role_mappings

[
  {
    "role_id": "123456789",
    "emoji": "🎮",
    "label": "Gamer"
  },
  {
    "role_id": "987654321",
    "emoji": "🎵",
    "label": "Music Lover"
  }
]

Dashboard — konfiguracja

Panel edycji Reaction Roles wyświetla siatkę kart — jedna karta na konfigurację:

Każda karta zawiera:

• Podgląd embeda z kolorowymi badge'ami
• Status: Deployed / Not deployed
• Tryb (buttons/dropdown/reactions)
• Przycisk Edit i Delete

Tworzenie nowej konfiguracji

1. Kliknij przycisk dodawania nowej konfiguracji
2. Wypełnij embed (tytuł, opis, kolor)
3. Dodaj mapowania ról (emoji + rola + label)
4. Wybierz tryb i zachowanie
5. Zapisz i wdroż (deploy)

Auto-redeploy

Gdy edytujesz już wdrożoną konfigurację i zapiszesz zmiany, bot automatycznie edytuje istniejącą wiadomość na Discordzie — aktualizuje embed i komponenty (przyciski/dropdown). Nie trzeba ręcznie usuwać i ponownie wdrażać.

Nasłuchiwane zdarzenia

Zdarzenie	Akcja
on_interaction	Obsługa kliknięć przycisków i wyborów z dropdown
on_raw_reaction_add	Obsługa dodania reakcji (tryb reactions)
on_raw_reaction_remove	Obsługa usunięcia reakcji (tryb reactions, tylko toggle)

Proces działania

Tryb Buttons

1. Użytkownik klika przycisk
2. Bot parsuje custom_id (format: rr:{role_id})
3. Sprawdza, czy bot może zarządzać tą rolą (hierarchia)
4. Toggle: jeśli użytkownik ma rolę → usuwa; jeśli nie ma → dodaje
5. Wysyła efemeralną odpowiedź
6. Loguje zmianę w module Logs

Tryb Dropdown

1. Użytkownik wybiera role z menu (może wybrać wiele)
2. Bot porównuje wybrane role z aktualnie posiadanymi
3. Dodaje brakujące, usuwa odznaczone (w trybie toggle)
4. Wysyła podsumowanie zmian

Tryb Reactions

1. Użytkownik dodaje reakcję emoji
2. Bot mapuje emoji na role_id
3. Dodaje rolę użytkownikowi
4. Przy usunięciu reakcji (toggle) — usuwa rolę

Śledzenie wdrożonych wiadomości

Wdrożone wiadomości są zapisywane w tabeli reaction_role_messages:

• message_id — ID wiadomości na Discordzie
• config_index — indeks konfiguracji w tablicy

Bot ładuje te dane przy starcie i trzyma w pamięci dla szybkiego routingu interakcji.

Logowanie

Zmiany ról są logowane przez Logs pod kategorią reaction_roles:

• Role Added — dodanie roli (z informacją o metodzie: button/dropdown/reaction)
• Role Removed — usunięcie roli
• Error — brakująca rola (rola została usunięta z serwera po konfiguracji)

Obsługa błędów

• Brakująca rola — jeśli skonfigurowana rola nie istnieje, użytkownik dostaje efemeralną wiadomość "This role no longer exists. Please contact an administrator." + log błędu
• Hierarchia ról — jeśli bot nie może zarządzać daną rolą, wyświetla komunikat o konieczności przesunięcia roli bota wyżej

Wskazówki

Best practices

• Używaj trybu Buttons dla małej liczby ról (1–5) — najbardziej intuicyjne
• Używaj trybu Dropdown dla wielu ról (6+) — zajmuje mniej miejsca
• Tryb Reactions jest legacy — buttons/dropdown są bardziej niezawodne
• Ustaw czytelne emoji i labels aby użytkownicy wiedzieli, co wybierają
• Sprawdź hierarchię ról po konfiguracji — rola bota musi być wyżej niż role self-assign

Ważne

Po usunięciu roli z serwera Discord, konfiguracja reaction roles nie aktualizuje się automatycznie. Usuń nieistniejącą rolę z konfiguracji w dashboardzie, aby uniknąć błędów.