Stockton University Discord Bot

This repository contains a private Discord bot for Stockton University's Esports Discord server.

Motivation: Due to an inevitable increase in server traffic, this bot has been developed to automate moderation tasks, maximize user retention, provide help resources and handle professional aesthetics.

Table of contents:

• Feature list
• Technologies used
• Repository demystified
• Google Sheets configuration file
• Contribution/install instructions
• Gallery

If you have questions, feel free to send me an email at: lawrencechiappelli@gmail.com

Likewise, if you are already a member of the Stockton Esports Server, you are more than welcome to message a moderator or leadership staff member using the contact information provided by the bot.

Feature list

1. Automated user authentication via signposting
2. User-friendly bot configuration via Google Sheets for admins
3. Role menus for event subscriptions and supported games
4. Configurable leadership directory with professional contact information
5. Configurable game manager contact information via Discord embed
6. Configurable FAQ section via Discord embed
7. Real-time updates of the campus's gaming lab PC usage
8. Custom Twitter feed with detailed information to augment University branding
9. Retrievable server metrics (number of staff members, roles, and bot status)
10. Bot reports pertaining to bot failures and number of @everyone pings
11. Audit logs that feature more detailed info than what Discord provides for deleted messages
12. Capability to remotely restart the bot in the event of bot issues

See these features in action at the bottom of this README.

Technologies used

• Python 3 - Version 3.8
• Heroku - Hosting service
• Selenium - Web scraper
• Discord API - discord.py
• Google Sheets API - gspread
• Dropbox API - dropbox
• Heroku API - heroku3
• Twitter API - tweepy

See major/minor versions of these technologies in requirements.txt.

Repository demystified

The following is an explanation of the repository's project structure, whether you are simply curious or a potential contributor.

Heroku Files:

• bot.py - the "brains" of the code. The user provides their bot token here, and directs end-user functionality to different modules. Set this as your script path.
• config.ini - contains a unique configuration specific to the needs of Discord server. Config info is retrieved from the Google Sheets configuration file and stored here. The primary motivation for this is to improve API response times and efficiently utilize sparse rate limit quotas.
• Aptfile - "Heroku will ... install these packages ... when you deploy your application"
• Procfile - "Heroku apps include a Procfile that specifies the commands that are executed by the app on startup"
• runtime.txt - "The Heroku Runtime is responsible for provisioning and orchestrating containers (dynos), managing and monitoring their -lifecycle, providing proper network configuration, HTTP routing, log aggregation, and more."
• requirements.txt - "The requirements. txt file lists the app dependencies together. When an app is deployed, Heroku reads this file and installs the appropriate Python dependencies using the pip install -r command."

In short, the above non-python files required for hosting on Heroku. They must remain in the root directory. I recommend the free version of Heroku if you need a hosting solution during development.

Packages:

• StocktonBotPackage Contains modules, functionality and utility unique to the Stockton Esports Discord server and its requirements.

  • DevUtilities Contains utilities for programmers and server moderators.

    • configutil.py - A shorthand way of receiving the parsed configuration file config.ini. While currently short in scope, the parser may need additional functionality in the possible event that config.ini becomes more complex. Also contains useful debugging functions.

    • dropboxAPI.py - Used to access the API credentials needed to connect to the Google Sheets config document. The file contained in the dropbox account is a raw JSON file- the motivation to have this file separate is to work around the lack of environment variable support coming from a non-Python file.

    • gsheetsAPI.py - Used to retrieve customizable data from a Google Sheets file, including but not limited to entire sheets and specific pieces of data. This is done by utilizing multi-threading to persistently retrieve data. Note: the majority of API calls will occur here, so please be wary of your rate limits. More info on rate limits here. Emphasis on the importance of this module.

    • herokuAPI.py - Contains utility functions that interact with Heroku, such as the capability restarting the bot remotely.

    • seleniumbrowser.py - Contains functionality and error handling necessary to successfully start the selenium browser for web scraping.

    • utils.py - Contains custom, commonly used utility functions to assist me during development. This module is also the wrapper that retrieves local configuration information previously pulled from Google Sheets. Please see the below section on the Google Sheets configuration file for more information.

    • validators.py - Contains shorthand methods of checking the validity of command execution, such that we are able efficiently use sparse rate limit quotas.

  • Features Contains interactive properties for server members.

    • embeddirectory.py - A generic module that is responsible for handling features that utilizes Discord embeds and isn't categorized as contact information.

    • gaminglabscraper.py - A wrapper module developed in-place of the actual labstats API locked behind University credentials. It's built around Selenium- it being the supporting structure that scrapes data from main Stockton Esports website.

    • helpdirectory.py - A series of contact info-related embeds that can be sent out by entering !helppanel. These embeds are customizable through a Google Sheets config file.

    • reactiondirectory.py - Contains features that rely on reaction events, such as user authentication, event subscriptions, game selection and audit logs.

    • servermetrics.py - Contains metric-related

    • twitterfeed.py - A real-time Tweet streamer that maximizes asynchronous programming to continuously update Stockton's tweets via Discord embeds. Type !populate to populate the #social-media-feed channel with the last 20 tweets.

    Make sure to type !help for instructions on where to enter commands. Such configuration can also be observed in config.ini.

Google Sheets configuration file

This bot queries customizable information used in a private Google Sheets document. The intent here is for admins to make configuration adjustments to the bot using a familiar and friendly GUI-interface. This also eliminates the need for busy students to memorize complex commands. Please refer to the Wiki for more information regarding this document.

However, emphasis on the critical nature of this config file- it's functionality is crucial to the codebase, such that most modules eventually rely on this. It is utils.py that pulls the config data from gsheetsAPI.py.

Contributor and Installation instructions

Interested in contributing to the bot, or simply want to install it in your own server? Check out the Wiki for instructions.

Gallery

Help Directory - !helppanel

Game Selection - !gameselection

Real-time Gaming Lab PC usage - !gamelab