All checks were successful
Build and Deploy Nuxt / build (push) Successful in 1m51s
49 lines
4.2 KiB
Markdown
49 lines
4.2 KiB
Markdown
# 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.
|
||
- `/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.
|
||
- `/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](https://discord.com/developers/applications). 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:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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.
|