Fix issue #79: Implement documentation
All checks were successful
Test / test (push) Successful in 2s

This commit is contained in:
Gitea OpenCode Agent
2026-10-15 19:07:09 +00:00
parent a8a1e0ca41
commit 788f69efd3
27 changed files with 1731 additions and 70 deletions

View File

@@ -0,0 +1,62 @@
# Discord
The Dragonroll Discord bot lets a server read the characters of a campaign without anyone leaving
Discord: the roster, a character's sheet with its portrait, and who plays whom. It is a read-only bot —
it never changes your campaign.
## Connecting a server
1. Invite the bot to the server with the `bot` and `applications.commands` scopes.
2. A Discord **administrator** runs `/dragonroll connect`. The bot answers with a *Sign in to
Dragonroll* button.
3. Whoever opens it signs in to the Dragonroll account that owns the campaign and picks that campaign.
The server is now linked to it, and the bot says so.
4. From then on anybody in the server can look the campaign's characters up.
The authorization link lasts ten minutes and works once. A campaign is linked to one Discord server at
a time, and a server to one campaign; authorizing the server with a different Dragonroll account takes
over the connection.
## Commands
| Command | Who | What it does |
| --- | --- | --- |
| `/characters [type]` | everybody | Lists the characters of the campaign this server is linked to. `type` narrows the list to **Characters**, **NPCs** or **Creatures**. Every character a player has claimed shows up next to that player. |
| `/character name [public]` | everybody | Shows one actor's sheet: its portrait, description, race, class and level, background, armor class and speed, ability scores, proficiencies, traits, spells and inventory. Start typing a name and Discord offers the campaign's roster. Set `public` to `true` to show the sheet to the whole channel instead of only to you. |
| `/dragonroll connect` | administrators | Asks Dragonroll for the sign-up link that connects this server, and confirms here once somebody has authorized it. |
| `/dragonroll link campaign:` | administrators | Moves this server to another campaign of the connected Dragonroll account. Type part of a name to filter the choices. |
| `/dragonroll unlink` | administrators | Removes this server's campaign link. The campaign is untouched; the commands simply have nothing to read until one is linked again. |
| `/dragonroll status` | everybody | Shows which campaign this server reads, and which character your Discord account holds on it. |
| `/dragonroll refresh` | everybody | Asks Dragonroll again where the connection stands, and shows what it answered. |
| `/dragonroll assign character:` | everybody | Links a character of the campaign to your Discord account, so the bot knows it is yours and `/characters` says so. You can take a character nobody holds; a character somebody else holds can only be moved by an administrator. |
| `/dragonroll unassign [character]` | everybody | Drops a character link. Without the option you give up your own character; naming somebody else's takes it off them, which only an administrator can do. |
Replies are private: only you see them, so a player can look up their character in a busy channel. The
one exception is `/character` with `public:true`, which posts the sheet where everyone can read it — for
the villain the party is talking to, or the magic item they just found.
## Characters and their players
`/dragonroll assign` is how a player says *this one is mine*:
- each account holds one character, so claiming a second one frees the first,
- a free character can be taken by anybody,
- a character somebody holds can only be taken or freed by a server administrator,
- the pairing shows up in `/characters` and in `/dragonroll status`, which is what lets the table see
who is playing whom.
Assigning a character does not hide anything: the bot is read-only and every member of the server can
already read the campaign's characters with `/character`.
## When something goes wrong
| The bot says | What is going on |
| --- | --- |
| "Connect a Dragonroll account first with /dragonroll connect." | Nobody has authorized this server yet, or the authorization expired before anyone opened it. |
| "Only Discord server administrators can connect Dragonroll or change this campaign link." | The command changes the server's connection, so it needs the Discord Administrator permission. |
| "The bot API secret is missing or does not match the backend." | Whoever runs the bot has to set the same `DRAGONROLL_DISCORD_BOT_SECRET` in the bot and in the Dragonroll backend. |
| "This server does not have a linked campaign." | The link was removed; an administrator has to pick a campaign with `/dragonroll link`. |
Character portraits are read from Dragonroll's public upload folder, so the bot needs to be able to
reach the server Dragonroll runs on. Whoever hosts the bot finds its setup in `discord-bot/README.md`
in the source repository.