add: added readme, admin guide, license
This commit is contained in:
@@ -0,0 +1,197 @@
|
||||
# Hildebrand Administrator and User Guide
|
||||
|
||||
##### Note from the developer/designer
|
||||
|
||||
Hi there, I'm Wyatt/Arnkell. Thank you for reading this guide and using my Discord bot, Hildibrand. I hope you enjoy your time with it.
|
||||
|
||||
This guide is intended for both Discord servers adminisrators and Discord bot developers.
|
||||
|
||||
If you have any trouble with operation of this bot, please do not hesitate to reach out on Discord (wymiller) or email: wyatt@wyattjmiller.com
|
||||
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
Hildebrand is a Discord trivia buzzer bot. It creates a shared buzzer in a text
|
||||
channel, plays a buzzer sound in voice, identifies the first participant to
|
||||
buzz, and can mute the other participants so the winner can answer.
|
||||
|
||||
## Before you begin
|
||||
|
||||
Give the bot the following permissions in every text and voice channel where it
|
||||
will be used:
|
||||
|
||||
| Permission | Why it is needed |
|
||||
| --- | --- |
|
||||
| View Channel | See the channel in which a session is started |
|
||||
| Send Messages | Post the buzzer and command results |
|
||||
| Connect | Join the host's voice channel |
|
||||
| Speak | Play the buzzer sound |
|
||||
| Mute Members | Mute and unmute trivia participants |
|
||||
|
||||
Members also need permission to use application commands in the chosen text
|
||||
channel.
|
||||
|
||||
Place the Hildebrand bot role above the roles of the participants it must mute.
|
||||
Discord does not allow a bot to mute a member whose highest role is equal to or
|
||||
higher than the bot's highest role. Server owners cannot be muted by a bot.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Do not grant Hildebrand the full Administrator permission. The channel and
|
||||
> voice permissions listed above are sufficient.
|
||||
|
||||
## Quick start for a trivia host
|
||||
|
||||
1. Join the voice channel where the trivia game will take place.
|
||||
2. In the text channel where you want the buzzer to appear, run `/start`.
|
||||
3. Wait for Hildebrand to join voice and post **The buzzer is ready!**.
|
||||
4. Ask players to join the same voice channel and use the **BUZZ!** button in
|
||||
the bot's message.
|
||||
5. After a player answers, select **Reset** to begin the next question.
|
||||
6. At the end of the game, run `/stop`.
|
||||
|
||||
The member who runs `/start` becomes the **session host**. Only that member can
|
||||
reset, lock, unlock, or stop the session. Discord server administrators do not
|
||||
automatically override the session host and cannot do so. In other words,
|
||||
no one has the power to overrule the session host.
|
||||
|
||||
## What happens when someone buzzes
|
||||
|
||||
To buzz, a player must be in the voice channel in which the session was
|
||||
started. The first accepted button press does all of the following:
|
||||
|
||||
1. Locks the buzzer so later presses cannot win.
|
||||
2. Names the winning player in the buzzer message.
|
||||
3. Plays the buzzer sound in the voice channel.
|
||||
4. Server-mutes the other human participants currently in that channel.
|
||||
|
||||
Hildebrand does not mute the session host or winning player itself. Bots are
|
||||
not muted. Any pre-existing server mute still applies, however: Hildebrand
|
||||
leaves it alone and will not later remove that moderator-applied mute.
|
||||
|
||||
Players receive a private Discord response that only they can see if they try
|
||||
to use a stale or locked buzzer, or if they are not in the session's voice
|
||||
channel.
|
||||
|
||||
## Controls and commands
|
||||
|
||||
The controls in the buzzer message and their slash-command equivalents have
|
||||
the same effect. A button's confirmation or error response is visible only to
|
||||
the member who selected it.
|
||||
|
||||
| Control | Command | Result |
|
||||
| --- | --- | --- |
|
||||
| **Reset** | `/reset` | Clears the previous winner, opens the buzzer, and unmutes members muted by Hildebrand. Use this between questions. |
|
||||
| **Lock** | `/lock` | Closes the buzzer and mutes everyone currently in the voice channel except the host and the current winner, if there is one. |
|
||||
| **Unlock** | `/unlock` | Opens the buzzer and unmutes members muted by Hildebrand, but keeps the previous winner's name in the message. |
|
||||
| — | `/stop` | Unmutes members muted by Hildebrand, disconnects the bot from voice, ends the session, and disables the old controls. |
|
||||
|
||||
`/start` creates a session in the voice channel occupied by the person who runs
|
||||
the command. The buzzer message is posted in the text channel where the command
|
||||
was run.
|
||||
|
||||
> [!NOTE]
|
||||
> Use **Reset** for a new question because it clears the recorded winner. Use
|
||||
> **Unlock** when you want to reopen the same question without clearing the name
|
||||
> of the player who previously buzzed.
|
||||
|
||||
> [!NOTE]
|
||||
> The host can select **Lock** before anyone buzzes, for example while reading a
|
||||
> question. Select **Unlock** or **Reset** when players should be allowed to buzz.
|
||||
|
||||
## Ending a session safely
|
||||
|
||||
Always run `/stop` before the bot is shut down or restarted. This lets
|
||||
Hildebrand unmute the members it muted and disconnect cleanly.
|
||||
|
||||
If Hildebrand reports that it could not unmute one or more participants, fix
|
||||
its **Mute Members** permission or role position and run `/stop` again. The
|
||||
session is not stopped until its tracked members have been unmuted.
|
||||
|
||||
Session state exists only in the running bot's memory. If the bot crashes or is
|
||||
restarted during a locked round, an administrator may need to manually remove
|
||||
server mutes in Discord. After a restart, old buzzer buttons are no longer
|
||||
active; start a new session with `/start`.
|
||||
|
||||
## Operational limits
|
||||
|
||||
- A running Hildebrand instance supports only **one active session in total**,
|
||||
even if the bot has been added to multiple Discord servers.
|
||||
- A session remains tied to the voice channel selected at `/start`. Moving the
|
||||
host or the bot does not move the session.
|
||||
- Hildebrand mutes the people present when a player buzzes or the host selects
|
||||
**Lock**. It does not continuously mute people who join the channel later.
|
||||
- Control of an active session cannot be transferred to another member. The
|
||||
original host must stop it, or the bot operator must restart the bot and an
|
||||
administrator must clean up any remaining server mutes.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Slash commands do not appear
|
||||
|
||||
- Confirm that the bot was installed with the `applications.commands` scope.
|
||||
- Confirm that the member can use application commands in the text channel.
|
||||
- Confirm that the bot is online. If it has just been installed or restarted,
|
||||
allow Discord time to display its globally registered commands.
|
||||
|
||||
### `/start` says you must be in a voice channel
|
||||
|
||||
Join the intended voice channel before running `/start`. The bot selects the
|
||||
session channel from the host's current voice connection.
|
||||
|
||||
### The bot cannot join or play the sound
|
||||
|
||||
Check **View Channel**, **Connect**, and **Speak** for the bot in that voice
|
||||
channel. Channel-specific permission overrides can deny access even when the
|
||||
bot's server role allows it.
|
||||
|
||||
### The bot cannot post or update the buzzer
|
||||
|
||||
Check **View Channel** and **Send Messages** for the bot in the text channel.
|
||||
Do not delete the active buzzer message while a session is running.
|
||||
|
||||
### Some players are not muted or unmuted
|
||||
|
||||
Check all of the following:
|
||||
|
||||
- The bot has **Mute Members** in the voice channel.
|
||||
- The Hildebrand role is above each affected player's highest role.
|
||||
- The affected account is not the server owner.
|
||||
- The player is in the session's original voice channel.
|
||||
|
||||
Hildebrand intentionally does not unmute a member who was already server-muted
|
||||
before Hildebrand tried to mute them.
|
||||
|
||||
### A player cannot buzz
|
||||
|
||||
The player must be in the session's voice channel. Also check whether the
|
||||
buzzer is locked, the displayed message belongs to an old session, or another
|
||||
player has already buzzed.
|
||||
|
||||
### A command says another session is active
|
||||
|
||||
Only one session can run on a bot instance. Ask the current session host to run
|
||||
`/stop`. If no usable session exists after a bot failure, contact the bot
|
||||
operator to restart the instance and manually clear any remaining server mutes.
|
||||
|
||||
### A host is no longer available
|
||||
|
||||
There is no host-transfer command. Ask the original host to run `/stop`. If
|
||||
that is impossible, the bot operator must restart Hildebrand; afterward, a
|
||||
Discord administrator should manually unmute anyone left server-muted and a
|
||||
new host can run `/start`.
|
||||
|
||||
## Recommended administrator checklist
|
||||
|
||||
Before an event:
|
||||
|
||||
- Confirm that the bot is online and slash commands are visible.
|
||||
- Confirm the bot's text and voice channel permissions.
|
||||
- Move the bot role above participant roles, without granting Administrator.
|
||||
- Test `/start`, one buzz, `/reset`, and `/stop` with a volunteer.
|
||||
|
||||
After an event:
|
||||
|
||||
- Confirm that the host ran `/stop`.
|
||||
- Confirm that the bot left voice.
|
||||
- Confirm that no participant remains server-muted unexpectedly.
|
||||
Reference in New Issue
Block a user