Fix issue #79: Implement documentation
All checks were successful
Test / test (push) Successful in 2s
All checks were successful
Test / test (push) Successful in 2s
This commit is contained in:
62
frontend/app/content/docs/03-integrations/02-discord.md
Normal file
62
frontend/app/content/docs/03-integrations/02-discord.md
Normal 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.
|
||||
Reference in New Issue
Block a user