CONTRIBUTING.md

Contributing

Thanks for wanting to improve the BingoParty bot! This document describes some important things you should know regarding the project setup and code. For a general introduction, go through the Readme file.

Please keep in mind that this file's contents are currently undergoing a rewrite (and hopefully won't remain as unstructured). At the current point in time, this document may feature potentially incorrect, and almost certainly incomplete info, too.

Getting set up & related topics

Code & module structure

For potential contributors, or myself, when coming back to fix or extend something:

• TODO: update this section with some explanations. For now, a handy overview list of files:

.
├── CONTRIBUTING.md
├── Config.example.mjs
├── Config.mjs
├── README.md
├── data
│   ├── autoKickWords.json
│   ├── backup-playerNames.json
│   ├── banned.json
│   ├── bingoBrewersRules.json
│   ├── generalDatabase.json
│   ├── playerNames.json
├── index.mjs
├── one-time-scripts
│   ├── convert-data-util_old.mjs
│   ├── exportCommandData.mjs
│   └── updatedb-preferredAccount.mjs
├── package-lock.json
├── package.json
├── run-bot
└── src
    ├── discord
    │   ├── Discord.mjs
    │   ├── components
    │   │   └── commands
    │   │       └── (all Discord slash commands)
│   │   └── handlers
│   │       └── CommandHandler.mjs
    ├── mineflayer
    │   ├── Bot.mjs
    │   ├── commands
    │   │   ├── EXAMPLECOMMAND.mjs
    │   │   ├── admin
    │   │   │   └── (in-game commands for admin activities)
    │   │   ├── misc
    │   │   │   └── (in-game commands for users and their data)
    │   │   └── party
    │   │       └── (in-game commands mimicking Hypixel commands for parties)
    │   ├── events
    │   │   ├── MessageEvent.mjs
    │   │   ├── OnKick.mjs
    │   │   └── OnceLogin.mjs
    │   └── handlers
    │       └── PartyCommandHandler.mjs
    └── utils
        ├── Interfaces.mjs
        ├── Utils.mjs
        └── Webhook.mjs

How to run

If you are a user of the BingoParty bot system, you do not need to install anything (same as with the previous version based on ChatTriggers), see the table here on how to use.

If you want to run this system yourself, or would like to experiment with the code, you can:

• Install NodeJS, which is the runtime used for the bot
• (optionally) Install the Prettier formatter if you're going to modify the code and plan on merging the changes back into the main project
• Then, git clone https://github.com/aphased/BingoPartyBot
• Execute npm install in your command line to get the dependencies installed
• Duplicate the file Config.example.mjs and rename it to Config.mjs. Then, fill out the values for your bot Minecraft account's Microsoft email, and optionally the values needed for Discord integration.

Regarding the database:

• On the first launch, the bot will promptly exit if it doesn't find the player allowlist file at data/playerNames.json populated, leaving a new/empty template file there for you to fill out with your potential main account's IGN as the bot owner.
• Alternatively, copy the data/backup-playerNames.json list into the file and work with the "canonical" allowed player database right away, in which case you will grant other people with permissions chat access to your designated bot Minecraft account!

At this point, you may finally:

• Run ./BingoPartyBot/run-bot for Unix (Linux/macOS/…), on Windows you can execute the run-bot.bat file (which will however not restart the bot upon crashes) – or just node ., which will also not restart on crash, but works everywhere
• Add something for (re)starting with more convenience and only needing to remember a single command to to your .{shell}rc config file, for example using screen: alias restartbpb="screen -d -RR bpb $HOME/BingoPartyBot/run-bot"

Writing new functionality

When adding new party commands, make sure to verify if it needs an entry in the documentation.

Rule of thumb: If it's using !p, it should be added to the documentation repo, especially so if all splashers can use it (but also new commands only for staff-and-up)

Custom functions/use of aliases

These might have only a single one, or several reasons for their existence.

Either way, for consistency, always use the following abstractions rather than directly going to their underlying implementations:

• If a command has a response/status-like message to return:

  bot.reply(sender, message);

  • (with the full sender object)
  • This does several things: reply to the correct person, not reply when the sender was using Discord (TODO) or the admin console to send the command and finally adding a randomizer string to the message in order to bypass the anti-spam limitations of Hypixel chatting.

• If you want to send a message to party chat about the commands action (like Party mute was toggled by Name for example), use sender.preferredName:

  bot.chat(`/pc Party mute was toggled by ${sender.preferredName}.`);

  • This ensures the name that is preferred and/or chosen by users is actually taken when producing output which all party members can see.
  • A preferred name is one of the IGN from any of the existing account(s) on record for one player.

• If you want to access a command's functionality outside of just defining it in the commands/ directory:

  bot.utils.getCommandByAlias(bot, name).execute() …

• If you want to issue multiple commands to Hypixel via Minecraft chat back to back:

  await bot.utils.delay(bot.utils.minMsgDelay);
  bot.chat(`/someCommand`);
  
  await bot.utils.delay(bot.utils.minMsgDelay);
  bot.chat(`/p doSomething ${player}`);

  • This is necessary as Hypixel demands a pause/wait of at least certain time in between messages sent.