diff --git a/GUIDE.md b/GUIDE.md new file mode 100644 index 0000000..1fbafaa --- /dev/null +++ b/GUIDE.md @@ -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. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..2604655 --- /dev/null +++ b/LICENSE @@ -0,0 +1,277 @@ +Eclipse Public License - v 2.0 + + THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE + PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION + OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT. + +1. DEFINITIONS + +"Contribution" means: + +a) in the case of the initial Contributor, the initial content +Distributed under this Agreement, and + +b) in the case of each subsequent Contributor: +i) changes to the Program, and +ii) additions to the Program; +where such changes and/or additions to the Program originate from +and are Distributed by that particular Contributor. A Contribution +"originates" from a Contributor if it was added to the Program by +such Contributor itself or anyone acting on such Contributor's behalf. +Contributions do not include changes or additions to the Program that +are not Modified Works. + +"Contributor" means any person or entity that Distributes the Program. + +"Licensed Patents" mean patent claims licensable by a Contributor which +are necessarily infringed by the use or sale of its Contribution alone +or when combined with the Program. + +"Program" means the Contributions Distributed in accordance with this +Agreement. + +"Recipient" means anyone who receives the Program under this Agreement +or any Secondary License (as applicable), including Contributors. + +"Derivative Works" shall mean any work, whether in Source Code or other +form, that is based on (or derived from) the Program and for which the +editorial revisions, annotations, elaborations, or other modifications +represent, as a whole, an original work of authorship. + +"Modified Works" shall mean any work in Source Code or other form that +results from an addition to, deletion from, or modification of the +contents of the Program, including, for purposes of clarity any new file +in Source Code form that contains any contents of the Program. Modified +Works shall not include works that contain only declarations, +interfaces, types, classes, structures, or files of the Program solely +in each case in order to link to, bind by name, or subclass the Program +or Modified Works thereof. + +"Distribute" means the acts of a) distributing or b) making available +in any manner that enables the transfer of a copy. + +"Source Code" means the form of a Program preferred for making +modifications, including but not limited to software source code, +documentation source, and configuration files. + +"Secondary License" means either the GNU General Public License, +Version 2.0, or any later versions of that license, including any +exceptions or additional permissions as identified by the initial +Contributor. + +2. GRANT OF RIGHTS + +a) Subject to the terms of this Agreement, each Contributor hereby +grants Recipient a non-exclusive, worldwide, royalty-free copyright +license to reproduce, prepare Derivative Works of, publicly display, +publicly perform, Distribute and sublicense the Contribution of such +Contributor, if any, and such Derivative Works. + +b) Subject to the terms of this Agreement, each Contributor hereby +grants Recipient a non-exclusive, worldwide, royalty-free patent +license under Licensed Patents to make, use, sell, offer to sell, +import and otherwise transfer the Contribution of such Contributor, +if any, in Source Code or other form. This patent license shall +apply to the combination of the Contribution and the Program if, at +the time the Contribution is added by the Contributor, such addition +of the Contribution causes such combination to be covered by the +Licensed Patents. The patent license shall not apply to any other +combinations which include the Contribution. No hardware per se is +licensed hereunder. + +c) Recipient understands that although each Contributor grants the +licenses to its Contributions set forth herein, no assurances are +provided by any Contributor that the Program does not infringe the +patent or other intellectual property rights of any other entity. +Each Contributor disclaims any liability to Recipient for claims +brought by any other entity based on infringement of intellectual +property rights or otherwise. As a condition to exercising the +rights and licenses granted hereunder, each Recipient hereby +assumes sole responsibility to secure any other intellectual +property rights needed, if any. For example, if a third party +patent license is required to allow Recipient to Distribute the +Program, it is Recipient's responsibility to acquire that license +before distributing the Program. + +d) Each Contributor represents that to its knowledge it has +sufficient copyright rights in its Contribution, if any, to grant +the copyright license set forth in this Agreement. + +e) Notwithstanding the terms of any Secondary License, no +Contributor makes additional grants to any Recipient (other than +those set forth in this Agreement) as a result of such Recipient's +receipt of the Program under the terms of a Secondary License +(if permitted under the terms of Section 3). + +3. REQUIREMENTS + +3.1 If a Contributor Distributes the Program in any form, then: + +a) the Program must also be made available as Source Code, in +accordance with section 3.2, and the Contributor must accompany +the Program with a statement that the Source Code for the Program +is available under this Agreement, and informs Recipients how to +obtain it in a reasonable manner on or through a medium customarily +used for software exchange; and + +b) the Contributor may Distribute the Program under a license +different than this Agreement, provided that such license: +i) effectively disclaims on behalf of all other Contributors all +warranties and conditions, express and implied, including +warranties or conditions of title and non-infringement, and +implied warranties or conditions of merchantability and fitness +for a particular purpose; + + ii) effectively excludes on behalf of all other Contributors all + liability for damages, including direct, indirect, special, + incidental and consequential damages, such as lost profits; + + iii) does not attempt to limit or alter the recipients' rights + in the Source Code under section 3.2; and + + iv) requires any subsequent distribution of the Program by any + party to be under a license that satisfies the requirements + of this section 3. + +3.2 When the Program is Distributed as Source Code: + +a) it must be made available under this Agreement, or if the +Program (i) is combined with other material in a separate file or +files made available under a Secondary License, and (ii) the initial +Contributor attached to the Source Code the notice described in +Exhibit A of this Agreement, then the Program may be made available +under the terms of such Secondary Licenses, and + +b) a copy of this Agreement must be included with each copy of +the Program. + +3.3 Contributors may not remove or alter any copyright, patent, +trademark, attribution notices, disclaimers of warranty, or limitations +of liability ("notices") contained within the Program from any copy of +the Program which they Distribute, provided that Contributors may add +their own appropriate notices. + +4. COMMERCIAL DISTRIBUTION + +Commercial distributors of software may accept certain responsibilities +with respect to end users, business partners and the like. While this +license is intended to facilitate the commercial use of the Program, +the Contributor who includes the Program in a commercial product +offering should do so in a manner which does not create potential +liability for other Contributors. Therefore, if a Contributor includes +the Program in a commercial product offering, such Contributor +("Commercial Contributor") hereby agrees to defend and indemnify every +other Contributor ("Indemnified Contributor") against any losses, +damages and costs (collectively "Losses") arising from claims, lawsuits +and other legal actions brought by a third party against the Indemnified +Contributor to the extent caused by the acts or omissions of such +Commercial Contributor in connection with its distribution of the Program +in a commercial product offering. The obligations in this section do not +apply to any claims or Losses relating to any actual or alleged +intellectual property infringement. In order to qualify, an Indemnified +Contributor must: a) promptly notify the Commercial Contributor in +writing of such claim, and b) allow the Commercial Contributor to control, +and cooperate with the Commercial Contributor in, the defense and any +related settlement negotiations. The Indemnified Contributor may +participate in any such claim at its own expense. + +For example, a Contributor might include the Program in a commercial +product offering, Product X. That Contributor is then a Commercial +Contributor. If that Commercial Contributor then makes performance +claims, or offers warranties related to Product X, those performance +claims and warranties are such Commercial Contributor's responsibility +alone. Under this section, the Commercial Contributor would have to +defend claims against the other Contributors related to those performance +claims and warranties, and if a court requires any other Contributor to +pay any damages as a result, the Commercial Contributor must pay +those damages. + +5. NO WARRANTY + +EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT +PERMITTED BY APPLICABLE LAW, THE PROGRAM IS PROVIDED ON AN "AS IS" +BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR +IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF +TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR +PURPOSE. Each Recipient is solely responsible for determining the +appropriateness of using and distributing the Program and assumes all +risks associated with its exercise of rights under this Agreement, +including but not limited to the risks and costs of program errors, +compliance with applicable laws, damage to or loss of data, programs +or equipment, and unavailability or interruption of operations. + +6. DISCLAIMER OF LIABILITY + +EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT +PERMITTED BY APPLICABLE LAW, NEITHER RECIPIENT NOR ANY CONTRIBUTORS +SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST +PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE +EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + +7. GENERAL + +If any provision of this Agreement is invalid or unenforceable under +applicable law, it shall not affect the validity or enforceability of +the remainder of the terms of this Agreement, and without further +action by the parties hereto, such provision shall be reformed to the +minimum extent necessary to make such provision valid and enforceable. + +If Recipient institutes patent litigation against any entity +(including a cross-claim or counterclaim in a lawsuit) alleging that the +Program itself (excluding combinations of the Program with other software +or hardware) infringes such Recipient's patent(s), then such Recipient's +rights granted under Section 2(b) shall terminate as of the date such +litigation is filed. + +All Recipient's rights under this Agreement shall terminate if it +fails to comply with any of the material terms or conditions of this +Agreement and does not cure such failure in a reasonable period of +time after becoming aware of such noncompliance. If all Recipient's +rights under this Agreement terminate, Recipient agrees to cease use +and distribution of the Program as soon as reasonably practicable. +However, Recipient's obligations under this Agreement and any licenses +granted by Recipient relating to the Program shall continue and survive. + +Everyone is permitted to copy and distribute copies of this Agreement, +but in order to avoid inconsistency the Agreement is copyrighted and +may only be modified in the following manner. The Agreement Steward +reserves the right to publish new versions (including revisions) of +this Agreement from time to time. No one other than the Agreement +Steward has the right to modify this Agreement. The Eclipse Foundation +is the initial Agreement Steward. The Eclipse Foundation may assign the +responsibility to serve as the Agreement Steward to a suitable separate +entity. Each new version of the Agreement will be given a distinguishing +version number. The Program (including Contributions) may always be +Distributed subject to the version of the Agreement under which it was +received. In addition, after a new version of the Agreement is published, +Contributor may elect to Distribute the Program (including its +Contributions) under the new version. + +Except as expressly stated in Sections 2(a) and 2(b) above, Recipient +receives no rights or licenses to the intellectual property of any +Contributor under this Agreement, whether expressly, by implication, +estoppel or otherwise. All rights in the Program not expressly granted +under this Agreement are reserved. Nothing in this Agreement is intended +to be enforceable by any entity that is not a Contributor or Recipient. +No third-party beneficiary rights are created under this Agreement. + +Exhibit A - Form of Secondary Licenses Notice + +"This Source Code may also be made available under the following +Secondary Licenses when the conditions for such availability set forth +in the Eclipse Public License, v. 2.0 are satisfied: {name license(s), +version(s), and exceptions or additional permissions here}." + +Simply including a copy of this Agreement, including this Exhibit A +is not sufficient to license the Source Code under Secondary Licenses. + +If it is not possible or desirable to put the notice in a particular +file, then You may include the notice in a location (such as a LICENSE +file in a relevant directory) where a recipient would be likely to +look for such a notice. + +You may add additional accurate notices of copyright ownership. diff --git a/README.md b/README.md new file mode 100644 index 0000000..3156f07 --- /dev/null +++ b/README.md @@ -0,0 +1,23 @@ +# Hildibrand + +A trivia buzzer bot + +Written by Wyatt J. Miller, 2026 + +All Rights Reserved + +Licensed by Eclipse Public License 2.0 + +## What is this? + +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. + +## How do I use this? + +Read [this](./GUIDE.md) for administrator driven "how-to" guide. + +## Contribution + +Sure, I don't have a contribution document right now but if you would like to help, I'd be more than willing to look over what's been done.