@tryforge/forge.giveaways

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

• Installation
• Custom Messages
• Handling Interactions
• Documentation

Installation

[!WARNING] ForgeGiveaways requires the extension ForgeDB installed in order to operate.

• Run the following command to install the required npm packages:

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

• 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.

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-$giveawayID;Join;Secondary;🎉]
      ;Green]
    ;true]
  ]
  `
}

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

Handling Interactions

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

giveawayEntry-GIVEAWAY_ID  

_{Replace "GIVEAWAY_ID" with the actual ID of the giveaway. 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! 
  ]
  `
}