Giveaway System

1. Feature Brief

The Giveaway System provides a complete, GUI-driven solution for running giveaways inside your Discord server - no complicated slash command arguments, no manual winner picking. Everything is handled through buttons and modals. The core system includes the following:

1. Giveaway creation - managers create giveaways via a modal form, specifying prize, winner count, duration, and target channel
2. Automatic end & winner selection - the bot checks every 10 seconds and randomly selects winners the moment a giveaway expires
3. Public announcements - the original embed is updated with results and a winner mention is posted in the channel
4. Winner DMs - optionally DMs each winner privately with the prize and channel details on end or reroll
5. Entry validation - entries are silently blocked for ineligible members based on configured requirements
6. Active giveaway management - managers can view, end early, or cancel any running giveaway from the dashboard

Who can use this?

Any member with Manage Channels permission, or anyone holding the configured Giveaway Manager role, can create and manage giveaways. Enabling the system itself requires Manage Server.

---

2. Sub-Systems

Entry Requirements

Every giveaway automatically inherits the server’s active requirements at creation time:

• Minimum account age - Discord account must be at least N days old
• Minimum server age - member must have been in the server for at least N days
• Blacklisted roles - members holding any blacklisted role are silently blocked from entering
• All requirements are configured globally in Settings and apply to every new giveaway without any extra steps

Reroll System

• After a giveaway ends, a Reroll Winners button appears directly on the ended embed
• Picks a new winner randomly from the remaining entry pool (anyone not already selected as a winner)
• The reroll winner is announced publicly in the channel
• If DM Winners is enabled, the new winner also receives a private notification
• Only the giveaway host, Manage Server members, or Manager Role holders can trigger a reroll

Winner Announcements

• The original giveaway embed is edited in-place to display winners and total entries on end
• A separate public message is sent mentioning all winners by name
• If there are zero valid entries, the bot gracefully announces that no one entered - no errors
• If entries are fewer than the configured winner count, the bot picks all available entries as winners

Active Management

• The dashboard surfaces a live list of all running giveaways with entry counts and time remaining
• Select any giveaway from the dropdown to open its individual management panel
• End Early - immediately triggers the winner selection flow ahead of schedule
• Cancel - closes the giveaway with no winner selected and updates the embed to show cancelled status

Notification System

• DM Winners - each selected winner receives a private embed with the prize name, server name, and source channel
• Ping Role - an optional role that gets pinged when a new giveaway is posted, to alert interested members
• Auto Announce - controls whether the bot posts a public end announcement; can be toggled off if you prefer silent resolution

---

3. Setup

Run /giveaway to access the full GUI - no configuration files or extra commands needed.

1. Enable the system - run /giveaway and click Enable System. Requires Manage Server permission.

2. Configure roles - open Settings and set:

   • Manager Role - grants non-admin members full giveaway management access
   • Ping Role - role to be mentioned whenever a new giveaway goes live (optional)

3. Configure restrictions - still inside Settings, set any of the following to lock down who can enter or where one can be posted:

   • Allowed Channels - comma-separated channel IDs; leave empty to allow all channels
   • Account Age - minimum Discord account age in days (0 = disabled)
   • Server Age - minimum days a member must have been in the server (0 = disabled)
   • Blacklisted Roles - comma-separated role IDs whose holders cannot enter any giveaway

4. Set defaults - configure Default Duration (in hours) so it pre-fills every time you open the create form. Can always be overridden per giveaway.

5. Toggle notifications - enable or disable Auto Announce and DM Winners to match your server’s style.

6. Create your first giveaway - from the dashboard click Create Giveaway and fill in:

   • Prize name
   • Number of winners (1–20)
   • Duration in hours (1–720)
   • Channel ID (optional - leave blank to post in the current channel)

Settings Reference

Setting	Description	Default
Default Duration	Pre-filled hours in the create form	24h
Auto Announce	Post a public end message in channel	Enabled
DM Winners	Privately notify each winner on selection	Enabled
Manager Role	Role with full giveaway management access	None
Ping Role	Role pinged on new giveaway creation	None
Allowed Channels	Restrict giveaway posting to specific channels	All channels
Account Age	Minimum Discord account age to enter (days)	Disabled
Server Age	Minimum server membership age to enter (days)	Disabled
Blacklisted Roles	Roles barred from entering giveaways	None

---

Reliability & Edge Cases

• The bot checks for expired giveaways every 10 seconds - expect at most a brief delay between the scheduled end time and the announcement.
• Rerolls draw exclusively from non-winning entries, so the same person cannot win twice via reroll.
• Giveaways each carry a unique ID visible in the dashboard and on ended embeds - useful for tracking or auditing past giveaways.
• If the bot goes offline and restarts, active giveaways are loaded from the database and will end correctly once the checker resumes.