Getting started

This will guide you through the basics of setting up DDBKit and your bot. By the end, we should have something that can connect to Discord, and you can work from there afterward.

Prerequisites

A decent understanding of the Swift programming language.
Something that can compile Swift code. macOS and Linux are preferred. Get Swift here.

Making our directory and package

We need to set up our bot’s directory. Open a terminal and copy and paste the following command.

mkdir MyNewBot && cd MyNewBot

mkdir makes a folder, cd changes the current directory to that folder. Now that we’re in the folder, we can create our Package.swift file. Copy and paste the following command.

swift package init --type executable
Creating executable package: MyNewBot
Creating Package.swift
Creating .gitignore
Creating Sources/
Creating Sources/main.swift

We now have a Package.swift. This just kind of tells Swift how to run our program, a bot in this case. The defaults aren’t exactly what we need, so copy and paste the following code into Package.swift.

let package = Package(
  name: "MyNewBot",
  platforms: [
    .macOS(.v13)
  ],
  dependencies: [
    .package(url: "https://github.com/llsc12/DDBKit", exact: "0.2.0"), // change this to latest ver
  ],
  targets: [
    // Targets are the basic building blocks of a package, defining a module or a test suite.
    // Targets can depend on other targets in this package and products from dependencies.
    .executableTarget(
      name: "MyNewBot",
      dependencies: [
        .product(name: "DDBKit", package: "DDBKit"),
        .product(name: "Database", package: "DDBKit"),
        .product(name: "DDBKitUtilities", package: "DDBKit"),
        .product(name: "DDBKitFoundation", package: "DDBKit"),
      ]
    ),
  ]
)

Creating our entry point

The entry point file is where the bot will be configured (token, intents, etc.) and what to do when the bot is ready. You can name this anything but main.swift. We will just go with Bot.swift here.

The command you ran earlier has already made a Sources/main.swift file. Rename this to your choice and copy and paste the following code into it.

import DDBKit

@main
struct MyNewBot: DiscordBotApp {
  init() async {
    let httpClient = HTTPClient()
    // Edit this as needed.
    bot = await BotGatewayManager(
      eventLoopGroup: httpClient.eventLoopGroup,
      httpClient: httpClient,
      token: "Token Here",  // Do not store your token in your code in production.
      largeThreshold: 250,
      presence: .init(activities: [], status: .online, afk: false),
      intents: [.messageContent, .guildMessages]
    )
    // Will be useful
    cache = await .init(
      gatewayManager: bot,
      intents: .all,  // it's better to minimise cached data to your needs
      requestAllMembers: .enabledWithPresences,
      messageCachingPolicy: .saveEditHistoryAndDeleted
    )
  }

  var body: [any BotScene] {
    ReadyEvent { ready in
      print("hi mom")
    }

    MessageCreateEvent { msg in
      print("[\(msg.author?.username ?? "unknown")] \(msg.content)")
    }
  }

  var bot: Bot
  var cache: Cache
}

Change the token to your bot’s token, and if any, specify the intents you need in intents under BotGatewayManager.

First Command

Let’s make a simple command to test the waters. In your Bot.swift file, add the following code.

Command("ping") { interaction in
  try? await interaction.respond(with: "Pong!")
}

Don’t yet concern yourself with try?, it’s not too important right now.

Try running your bot. After a minute or two, you’ll find a new /ping command available for use.

Command Modifiers

You’ll find that Command types feature many modifiers, such as the one you may have already discovered above. DDBKit implements these modifiers that configure your command’s options before they’re registered after body evaluation.

These modifiers help describe and configure your commands, such as default permission requirements, DM usability, integration contexts and more!

Expanding on this, DDBKit includes extra utilities as another module you can import as DDBKitUtilities, which contains builders for messages and other composable objects, and modifiers that offer extra client side functionality.

Organisation

The best way to organise your code is to extend your bot’s structure with a computed variable for groups of commands/events. Begin by making a new directory named Commands and Events or whatever suits your needs.

Make a new swift file, naming it appropriately. Use the following code to get started.

import DDBKit
import DDBKitUtilities

extension MyNewBot {
  var coolCommandGroup: Group {
    Group {
      Command("pong") { i in
        try await i.respond(with: "ping!")
      }
    }
  }
}

Your directory structure should now look a little like this:

Package.swift
DirectorySources
- DirectoryCommands and Events
  - TestCommands.swift
  - …
- Bot.swift

As such, you can continue organising your code in a similar fashion or in any way you desire.

Your bot is now ready to build and run, good job 🎉