Giveaway

Command Details

• Name: gstart
• Aliases: gs
• Category: Giveaway
• Description: Start a giveaway with a specified duration, number of winners, and prize
• Usage: P gstart <description> <prize> <duration> <winners> [image] [thumbnail] [autopay], p gstart <description> <prize> <duration> <winners> [image] [thumbnail] [autopay], or /gstart <description> <prize> <duration> <winners> [image] [thumbnail] [autopay]
• Examples:
  • P gstart "Win amazing coins!" 1000 1h 2
  • p gs "Weekly giveaway" 10000 12h 5
  • /gstart "Special Event" 50000 1d 3 autopay
• Cooldown: Not specified
• Arguments:
  • description (required) - Custom description for the giveaway
  • prize (required) - The prize amount in coins (supports multipliers like 1k, 1m, 1b, 1t, 1q)
  • duration (required) - Time until giveaway ends (e.g., 1h, 1d, 1w)
  • winners (required) - Number of winners to select (1-20)
  • image (optional) - Attach an image for the giveaway
  • thumbnail (optional) - Attach a thumbnail for the giveaway
  • autopay (optional) - Automatically pay the winners after the giveaway ends
• Slash Command: Enabled
• Permissions:
  • Bot: SendMessages, ViewChannel, EmbedLinks
  • User: None (any user can create giveaways)
• Player Requirements: None (no voice, DJ, or active player required)

Functionality

• Coin-Based Giveaways: Creates giveaways specifically for bot coins with formatted prize displays.
• Flexible Prize Input: Supports multiplier formats (k, m, b, t, q) and comma-separated numbers for easy prize entry.
• Custom Descriptions: Allows custom giveaway descriptions or defaults to formatted coin amount display.
• Button-Based Entry System: Users join by clicking the main button instead of reactions.
• Image and Thumbnail Support: Optional image and thumbnail attachments for enhanced visual appeal.
• Autopay Functionality: Optional automatic payment to winners upon giveaway completion.
• Balance Validation: Checks host's coin balance for autopay giveaways and deducts total prize amount upfront.
• Special Permission System: Users with special permissions can create autopay giveaways without balance deduction.
• Participant Tracking: Real-time participant count display with dedicated participants button.
• Database Persistence: Comprehensive giveaway data storage including participants, settings, and status.
• Error Recovery: Automatic coin refunding if giveaway creation fails for autopay giveaways.
• Duration Validation: Robust duration parsing and validation through utility functions.
• Winner Limit Control: Enforces winner count limits (1-20) for fair giveaway management.
• Guild Integration: Properly tracks giveaways per guild with channel and message identification.

Code Overview

The command is built using a Command class structure and handles both message-based and interaction-based (slash command) inputs. It uses:

• client.utils.validateCommonParams() for duration and winner count validation with comprehensive error handling.
• Prize parsing with multiplier support (k, m, b, t, q) and negative number validation for coin amounts.
• ctx.interaction.deferReply() and ctx.sendDeferMessage() for handling command processing delays.
• Autopay balance checking using client.utils.getUser() and client.utils.hasSpecialPermission() for authorization.
• Automatic coin deduction from host's balance for autopay giveaways with error recovery and refunding.
• client.embed() creation with dynamic title, description, image, and thumbnail support.
• Button-based interaction system using client.utils.fullOptionButton() and client.utils.createButtonRow().
• client.utils.createGiveawayMessage() for sending giveaway messages with proper error handling.
• GiveawaySchema.create() for database persistence with comprehensive giveaway data storage.
• Error recovery mechanisms including automatic coin refunding on database save failures.
• Special permission system integration for privileged users bypassing balance requirements.
• Attachment handling for optional images and thumbnails through Discord interaction options.
• Real-time participant tracking with dedicated participants button for transparency.
• Comprehensive error handling with appropriate user feedback for various failure scenarios.