Driftwood

Driftwood is a modular Discord bot framework designed for flexibility and ease of use. By leveraging Lua scripts, it empowers developers to define application commands and subcommands seamlessly, making it an excellent choice for building multi-purpose, customisable Discord bots.

Features

• Lua Scripting for Commands: Commands and subcommands are defined in Lua for maximum flexibility and simplicity.
• Application Command Registration: Supports registering commands with detailed options, including subcommands and arguments.
• Dockerised Deployment: Easily deploy Driftwood as a containerised application.
• Extensible Architecture: Add single-file commands or complex modular commands with an intuitive directory structure.
• Environment Configurations: Configure the bot using environment variables.

Getting Started

To quickly create your own Discord bot using Driftwood, you can use the prebuilt Docker image available on GitHub Container Registry.

Step 1: Pull the Docker Image

docker pull ghcr.io/aussiebroadwan/driftwood:v1.1.0

Step 2: Prepare Your Lua Scripts

Set up a directory for your Lua scripts on your host machine (e.g., ./lua). Add command scripts to this directory following the structure explained in the Creating Commands section.

Tip: For better development experience, place the driftwood.lua file in your ./lua directory. This file provides type annotations and documentation, helping with IDE autocomplete and type checking.

Step 3: Run the Docker Container

Run the container with the required environment variables and mount your Lua script directory:

docker run -d \
  -e DISCORD_TOKEN=your_token_here \
  -e GUILD_ID=your_guild_id_here \
  -v $(pwd)/lua:/lua \
  ghcr.io/aussiebroadwan/driftwood:latest

Alternatively, simplify your setup using docker-compose.yml.

Development Setup

Step 1: Clone the Repository

git clone https://github.com/aussiebroadwan/driftwood.git
cd driftwood

Step 2: Build the Project

go build -o driftwood ./cmd/driftwood.go

Step 3: Run the Bot Locally

Set the necessary environment variables and run the bot:

export DISCORD_TOKEN=your_token_here
export GUILD_ID=your_guild_id_here
./driftwood

Environment Variables

The following environment variables are required:

Variable	Description
DISCORD_TOKEN	Your Discord bot token.
GUILD_ID	The ID of the guild (server) to register commands.

Creating Commands

Driftwood supports both single-file and modular command structures.

Single-File Command Example

-- file: lua/commands/ping.lua

local driftwood = require("driftwood")

-- Register the /ping command
driftwood.register_application_command({
    name = "ping",
    description = "Check bot responsiveness",
    handler = function(interaction)
        interaction:reply("Pong!")
    end,
}

Modular Command Example

In this the command entry point is the init.lua file.

Example: Command Entry Point (init.lua)

-- file: lua/commands/example_game/init.lua

local driftwood = require("driftwood")

-- Import subcommands.
local start_subcommand = require("commands.example_game.start")
local join_subcommand = require("commands.example_game.join")

-- Register the "game" command.
driftwood.register_application_command({
    name = "game",
    description = "Manage and play games",
    options = {
        start_subcommand,
        join_subcommand,
    },
})

Example: Start Subcommand

-- file: lua/commands/example_game/start.lua

local driftwood = require("driftwood")

return {
    name = "start",
    description = "Start a new game",
    type = driftwood.option_subcommand,
    handler = function(interaction)
        interaction:reply("Game started!")
    end,
}

Example: Join Subcommand

-- file: lua/commands/example_game/join.lua

local driftwood = require("driftwood")

return {
    name = "join",
    description = "Join an existing game",
    type = driftwood.option_subcommand,
    options = {
        driftwood.option.new_string("game_id", "ID of the game to join", true),
        driftwood.option.new_bool("mention", "Mention the user in the response"),
    },
    handler = function(interaction)
        local game_id = interaction.options.game_id
        local mention = interaction.options.mention or false

        interaction:reply("Joined game with ID: " .. game_id, { ephemeral = true, mention = mention })
    end,
}