Files
dragonroll/discord-bot/README.md
Gitea OpenCode Agent 299380d143
All checks were successful
Test / test (push) Successful in 2s
Fix issue #72: Link actor with a discord user
2026-10-15 17:06:25 +00:00

4.8 KiB
Raw Permalink Blame History

Dragonroll Discord bot

A read-only Discord bot for consulting actors (characters, NPCs, and creatures) from Dragonroll. It talks to Dragonroll through authenticated API endpoints; it does not connect to MongoDB directly.

Configure one campaign per Discord server

The bot can sit in as many Discord servers as you like. A Discord Administrator connects their own Dragonroll account with /dragonroll connect, signs in on Dragonroll’s site, then chooses one of their campaigns with /dragonroll link. The bot posts an ephemeral confirmation in Discord as soon as the authorization goes through. Dragonroll remembers the account and campaign for that guild. The bot never stores the Dragonroll user's password or token.

Discord server A ──link──▶ Dragonroll campaign "Katlum"     (account gm-a@example.com)
Discord server B ──link──▶ Dragonroll campaign "Silang"     (account gm-b@example.com)

Commands

  • /characters [type] lists the linked campaign's actors, optionally filtered to characters, NPCs, or creatures. Each one that a player has claimed with /dragonroll assign shows that player next to it.
  • /character name public:true shows the matching actor's portrait (when one has been uploaded), profile, ability scores, combat stats, proficiencies, traits, spells, and inventory. Type part of a name to pick it from the campaign's current roster. Set public to true to show the reply to everyone in the channel.
  • /dragonroll connect starts a short-lived Dragonroll sign-in and authorization link, and confirms here once somebody authorizes the server.
  • /dragonroll link lets a server administrator choose a campaign owned by the connected Dragonroll account. Type part of a campaign name to filter the choices.
  • /dragonroll unlink removes this server’s campaign link.
  • /dragonroll status shows the campaign linked to this server, and the character linked to your Discord account on it.
  • /dragonroll assign character links that character of the campaign to your Discord account: each player holds one character, so claiming a second one frees the first. Anyone can take a free character; only a server administrator can take a character another player already holds.
  • /dragonroll unassign [character] removes a character link. Without the option you give up your own character; naming somebody else’s character takes it off them, which only a server administrator can do.
  • /dragonroll refresh rechecks the current connection and campaign in Dragonroll.

Replies are private by default. /character can be made public with its public option, so everyone in the channel can see the character sheet.

Setup

  1. Create a Discord application and bot in the Discord Developer Portal. It only needs permission to use application commands and send replies.

  2. Generate a long random shared secret. Set it as DRAGONROLL_DISCORD_BOT_SECRET in both the backend environment and the bot's .env. This authenticates the bot service; it is not a Dragonroll user account.

  3. Copy .env.example to .env and enter the Discord token, application id, API URL, frontend URL, and shared secret. DRAGONROLL_API_URL must be reachable by the bot. DRAGONROLL_FRONTEND_URL is the address people open when they click the sign-in button, and it defaults to http://localhost:3000. Keep .env private.

  4. Invite the bot to each server with the bot and applications.commands scopes. A Discord Administrator runs /dragonroll connect, opens the Dragonroll button, signs in and confirms the server link, then returns to Discord and runs /dragonroll link to select a campaign they own. Each campaign can be linked to one server at a time.

  5. Install packages and register the slash commands:

    npm install
    npm run deploy-commands
    

    Commands are registered globally, so every server the bot is in can use them. Global registration can take up to an hour to propagate; the bot also registers the commands itself as soon as it joins a server, and refreshes them in every server on each start so command changes reach guild commands too. For quick testing on one server only: npm run deploy-commands -- --guild <server id> (note that those guild commands then shadow the global ones in that server).

  6. From the repository root, start the backend, frontend, and Discord bot together:

    npm run dev
    

    To run only the bot, start the backend first and use npm start from discord-bot/.

The bot can start without any Dragonroll user account. It uses the shared service secret for guild-scoped API calls, so configure the secret in both environments before using Dragonroll commands. Dragonroll user credentials are entered only on Dragonroll's site and are not sent through Discord. The bot needs outbound access to both the Dragonroll API and Discord.