---

Contents

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

Installation

---

⚠️ 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
   Copy

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")
   Copy

   ℹ️ Note
   View all available client options here.

Custom Messages

---

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]
  ]
  `
}
Copy

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

Handling Interactions

---

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

giveawayEntry  
Copy

_{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! 
  ]
  `
}
Copy

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