Getting started

In this guide, you'll learn how to use adam, a discord bot framework written in Go. The aim here is to get you familiar with adam, but not to provide a full reference. Use the documentation for that. If you are unfamiliar with Go, start by taking the Go Tour. With that said, let's get your first bot up and running.

Project Layout

Depending on your use case, a bot's codebase can grow very large. Therefore, it is important to properly organize your bot. We recommend you group your code into three main folders:

cmd: This contains your main package. Here you initialize everything, add your plugins, and start the bot.

plugins: This is where your plugins go. Use one package per command/module.

pkg: This is where all your library code goes. Basically, everything that fits in neither cmd nor plugin.

Note, however, that this layout is not the holy grail of layouts. If you only want to run a small bot with a handful of commands, you might be better of with a custom layout. Still, this is a good start if you are unsure about how to structure your bot.

Example

📁 myBot
 ┣ 📁 cmd
 ┃  ┗ 📁 mybot - your main package running the bot
 ┣ 📁 plugins
 ┃  ┣ 📁 mod - the mod (moderation) module
 ┃  ┃  ┣ 📁 ban - the ban command
 ┃  ┃  ┗ 📁 kick - the kick command
 ┃  ┗ 📁 ping - the ping command
 ┗ 📁 pkg
    ┗ 📁 repository
       ┣ 📁 mongo - mongo db driver
       ┗ 📁 postgres - postgres db driver

Creating a bot

After you have run go mod init and added adam as a dependency using go get github.com/mavolin/adam, you can create a bot in your main package using bot.New. You now need to think about what parts of the bot you want to make configurable, as a lot of configuration is done through the bot.Options you pass to bot.New.

cmd/mybot/main.go

package main

import (
    "log"
    "os"
    "time"

    "github.com/mavolin/adam/pkg/bot"
)

func main() {
    bot, err := bot.New(bot.Options{
        Token:            os.Getenv("DISCORD_BOT_TOKEN"),
        SettingsProvider: bot.NewStaticSettingsProvider(parsePrefixes()...),
        EditAge:          45 * time.Seconds,
     })
     if err != nil {
         log.Fatal(err)
     }
}

func parsePrefixes() []string {
	prefixes := os.Getenv("BOT_PREFIXES")
	if len(prefixes) == 0 {
		return nil
	}

	return strings.Split(prefixes, ",")
}

Adding Plugins

After creating your bot, you can add plugins to it.

cmd/mybot/main.go

package main

import (    
    "github.com/mavolin/myBot/plugin/ping"
    "github.com/mavolin/myBot/plugin/mod"
    
    "github.com/mavolin/adam/pkg/bot"
    "github.com/mavolin/adam/pkg/impl/command/help"
    
    "log"
)

func main() {
    bot, err := bot.New(...)
    if err != nil {
        log.Fatal(err)
    }
    
    addPlugins(bot)
}

func addPlugins(b *bot.Bot) {
    // to add a help command you can either create your own, or use adam's
    // built-in one
    b.AddCommand(help.New(help.Options{}))
}

Head over to the next page, to see how to build your first command.