This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Reaction Roles — Self-Service Role Panels

GrumpyReactionRoles lets members assign roles to themselves — via buttons or dropdown menus, without needing to ask a moderator. Admins set up panels once, and users simply click.

---

Activation

In configs/config.yml:

addons:
  reactionroles: true

On first start, configs/modules/reactionroles.yml is created.

---

reactionroles.yml

enabled: true
defaultColor: "#5865F2"    # Default color for new panels

---

Setup Workflow

A panel consists of multiple groups — each group is either a button row or a dropdown. Each group contains role entries.

Panel
 └── Group 1 (e.g. Buttons, max 1 choice → Color roles)
 │    ├── Blue Role
 │    ├── Red Role
 │    └── Green Role
 └── Group 2 (e.g. Dropdown, unlimited → Ping roles)
      ├── @Events-Ping
      └── @Updates-Ping

Step 1 — Create a panel

/reactionrole panel create #channel Choose your roles

Step 2 — Add a group

/reactionrole group add <panel-id> buttons label:"Color Roles" max:1

• style: buttons (Buttons) or select (Dropdown)
• max: 0 = unlimited · 1 = Exclusive choice (old role is automatically removed) · 2–25 = Multi-select
• required-role: User needs this role to interact with the group (optional)
• placeholder: Dropdown placeholder text

Step 3 — Add roles

/reactionrole role add <panel-id> <group-id> @Blue-Role label:"💙 Blue"
/reactionrole role add <panel-id> <group-id> @Red-Role label:"❤️ Red" emoji:"❤️"

Step 4 — Deploy

/reactionrole panel deploy <panel-id>

The panel is posted in the configured channel. If the message is deleted, simply run /reactionrole panel deploy again — it re-posts automatically.

---

Command Overview

Command	Description	Permission
/reactionrole panel create	Create a panel	Manage Roles
/reactionrole panel deploy	Post / update a panel	Manage Roles
/reactionrole panel delete	Delete a panel	Manage Roles
/reactionrole panel list	List all panels	Manage Roles
/reactionrole panel info	Panel details	Manage Roles
/reactionrole group add	Add a group	Manage Roles
/reactionrole group remove	Remove a group	Manage Roles
/reactionrole role add	Add a role to a group	Manage Roles
/reactionrole role remove	Remove a role	Manage Roles

All subcommands support autocomplete for panel ID and group ID.

---

Limits

What	Limit
Groups per panel	5 (Discord: max 5 action rows)
Buttons per group	25 (5 rows × 5 buttons)
Options per dropdown	25
Panels per server	Unlimited

---

Security

• Role validation: Button custom IDs are validated against the database — manipulated clicks with foreign role IDs are rejected.
• Per-user lock: Double-click protection prevents race conditions with maxSelections.
• Hierarchy check: The bot cannot assign roles that are higher than its own highest role.
• Guild ownership: All subcommands verify that the panel belongs to the current server.