ForgeGiveaways

ForgeGiveaways is a lightweight, flexible, and reliable extension for managing giveaways. Fully customizable features let you automate, track, and control every giveaway seamlessly.

Contents

1. Installation
2. Custom Messages
3. Handling Interactions
4. Documentation

⚠️ Warning
ForgeGiveaways requires the extension ForgeDB installed in order to operate.

1. Run the following command to install the required npm packages:

   npm i @tryforge/forge.giveaways @tryforge/forge.db

2. Here’s an example of how your main file should look:

   const { ForgeClient } = require("@tryforge/forgescript")
   const { ForgeGiveaways } = require("@tryforge/forge.giveaways")
   const { ForgeDB } = require("@tryforge/forge.db")
   
   const giveaways = new ForgeGiveaways({
       events: [
           "giveawayStart",
           "giveawayEnd"
       ],
       useDefault: true
   })
   
   const client = new ForgeClient({
       ...options // The options you currently have
       extensions: [
           giveaways,
           new ForgeDB()
       ]
   })
   
   client.commands.load("commands")
   giveaways.commands.load("giveaways")
   
   client.login("YourToken")

   ℹ️ Note
   View all available client options here.

You can disable the default messages by setting useDefault: false in the client options, and override them with custom messages emitted through events. Use desired functions to retrieve information about the current giveaway.

⚠️ Warning
Only one giveawayStart event is allowed per client instance!

Examples

When using custom start messages, your event must return the message ID of the sent giveaway message. To ensure that only the message ID is returned (and no additional text), use the $return[] function.

module.exports = {
  type: "giveawayStart",
  code: `
  $return[
    $sendMessage[$giveawayChannelID;
      $addContainer[
        $addTextDisplay[### 🎉 Giveaway 🎉]
        $addSeparator
        $addTextDisplay[**Prize:** $giveawayPrize\n**Winners:** $giveawayWinnersCount]
        $addSeparator
        $addActionRow
        $addButton[giveawayEntry;Join;Secondary;🎉]
      ;Green]
    ;true]
  ]
  `
}

module.exports = {
  type: "giveawayEnd",
  code: `
  $sendMessage[$giveawayChannelID;
    $reply[$giveawayChannelID;$giveawayMessageID;true]
    🏆 **Winners:** <@$newGiveaway[winners;>, <@]>
  ]
  `
}

The custom ID for giveaway entry buttons must follow this exact format:

giveawayEntry  

See the giveawayStart example above for reference.

Through the entry-related events, you can send custom responses directly to the current interaction context.

Examples

module.exports = {
  type: "giveawayEntryAdd",
  code: `
  $interactionReply[
    $ephemeral
    You have joined this giveaway as **$ordinal[$@[,]giveawayEntries]** participant! 
  ]
  `
}

module.exports = {
  type: "giveawayEntryRemove",
  code: `
  $interactionReply[
    $ephemeral
    You have left this giveaway! 
  ]
  `
}