https://github.com/DDBKit/DDBKit
A declarative Discord bot framework
https://github.com/DDBKit/DDBKit
declarative-programming discord-bots swift
Last synced: about 5 hours ago
JSON representation
A declarative Discord bot framework
- Host: GitHub
- URL: https://github.com/DDBKit/DDBKit
- Owner: DDBKit
- License: apache-2.0
- Created: 2024-03-22T17:35:39.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-02-11T00:32:51.000Z (5 months ago)
- Last Synced: 2026-02-11T02:27:10.610Z (5 months ago)
- Topics: declarative-programming, discord-bots, swift
- Language: Swift
- Homepage: https://ddbkit.llsc12.me
- Size: 695 KB
- Stars: 13
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
DDBKit
## What is it?
DDBKit stands for Declarative Discord Bot Kit, name proposed by [Tobias](https://github.com/tobiasdickinson). DDBKit is designed to abstract away the complexities of Discord’s API into something that feels right at home. Similar to SwiftUI, DDBKit lets you declare commands and add modifiers to create functionality in your bot. It’s kinda like [Commando](https://github.com/discordjs/commando). DDBKit relies on [DiscordBM](https://github.com/DiscordBM/DiscordBM) under the hood.
## Quick Start
Already know what you're doing? Get started faster by using the [DDBKit Template](https://github.com/DDBKit/DDBKit-Template).
## Getting started
Begin by making a new project directory with
```sh
mkdir MyNewBot && cd MyNewBot
```
Then make a new executable package in the directory with
```sh
swift package init --type executable
```
Open `Package.swift` in your preferred editor, and copy this configuration.
```swift
let package = Package(
name: "MyNewBot",
platforms: [
.macOS(.v13)
],
dependencies: [
.package(url: "https://github.com/llsc12/DDBKit", exact: "0.1.4"), // 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: "DDBKitUtilities", package: "DDBKit"),
.product(name: "DDBKitFoundation", package: "DDBKit"),
]
),
]
)
```
You’ve now configured the package to use DDBKit! Next, rename the file at `./Sources/main.swift` to anything that isn’t `main.swift`, such as `Bot.swift`.
Why do this?
Having a file named main.swift makes it the entrypoint, and code is executed at the top level. DDBKit uses a protocol that declares it’s own entrypoint, you’ll declare a struct conforming to the protocol and you’ll prefix the struct with @main. This is the simplest setup for a discord bot with DDBKit. You can run multiple clients by executing the run() async throws method on each DiscordBotApp struct you've defined.
You can now replace any existing code in your Swift file with
```swift
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
}
```
Congratulations! You’ve connected to Discord as your bot and reacted to an event!
> Wanna learn the good stuff and make commands? Check out the [docs](https://ddbkit.llsc12.me/start-here/getting-started/#first-command)!
> [!NOTE]
> **Using Linux**? Run swift run in the project directory.
>
> **If you need another entrypoint (iOS, etc.)**; you can run a `DiscordBotApp` instance with the run() async throws function available on your Bot struct. You can use this to run multiple clients at once if needed. If deploying to an iOS device or similar, it's easier to use [DiscordBotShell](https://github.com/DDBKit/DiscordBotShell).
>
> **Don't have a bot yet?** You can create one at https://discord.com/developers/applications. Make sure your bot has the correct permissions and intents.
> [!WARNING]
> You cannot use logic in the `body` property; The property is only read once on startup.
> Commands are registered in batch globally or per groups with [guild targets](https://ddbkit.llsc12.me/start-here/getting-started/#first-command).
> Logic is only evaluated in defined events and commands, and their respective modifiers that accept code.
You've now got a solid place to start with your bot. Check out the [docs](https://ddbkit.llsc12.me/) for more information!
## Contributing
Feel free to work on providing more abstractions and adding general utilities.
My code isn't exactly amazing so if you'd like to improve it for everyone else, be sure to make a PR!
I have a silly database thing going on. I think it might be useful but it also might be dumb and bad at large scale. If someone rewrites it to use a real database behind the scenes whilst also providing more utilities, it would be much appreciated.
Contributors should clone this repository and open `DDBKit.xcworkspace` as it loads the example bot alongside the DDBKit package. This way, you can test your work live whilst making changes. You can also create your own tests if you'd like.
I only ask that contributions are somewhat commented in cases of dense code or wherever fit.
Use `self` explicitly whenever it's used.
## Goals
- [x] Using builders for composable objects (main bot logic, messages etc.)
- [x] Abstraction over common objects (eg. extending objects like Interaction with useful methods)
- [ ] Feature parity with Discord, though this could mean anything
- [ ] Make database good
- [x] Linting
## Sponsoring
If you really love this project, you should first support [DiscordBM's development](https://github.com/DiscordBM/DiscordBM) above all, considering it lies as the foundation of DDBKit.
Afterwards, feel free to sponsor the development of DDBKit and my other projects!
[](https://github.com/sponsors/llsc12)