muppetinside/beep-boop repository overview

⁠Beep Boop, a bot for siege

⁠Installation

• install libraries by running pip3 install -r requirements.txt in the root directory (you may need admin)
• run python3 main.py bot web. Must specify at least one of bot, web. If bot is not enabled, the web api will not be able to send messages to discord servers

⁠Configuration

• configuration occurs in .env or settings.json(depreciated). There are a number of settings that need to be specified. Some settings aren't needed for the bot (bot) or webapi (api), but some are needed for both (both).
  • ubisoft_user (both): Ubisoft username used for fetching stats from r6 api
  • ubisoft_password (both): Ubisoft password used for fetching stats from r6 api
  • db_string (both): Database string used to communicate with the database
    • the format is: {database-type}://{username}:{password}@{hostname-or-ip}/{optional database}
    • for example: postgres://postgres:[email protected]
  • bot_token (bot): The token used by the bot to send/receive messages
  • discord_oauth_client_id (api): Client Id of the web application for OAuth
  • discord_oauth_client_secret (api): Client secret of the web application for OAuth
  • backend_url (api): the url the backend is hosted on. Needed for CORS and redirects
  • frontend_url (api): the url the frontend is hosted on. Needed for CORS and redirects
  • POSTGRES_PASSWORD (docker): the password of the postgres user if you are using docker
  • POSTGRES_USERNAME (optional, docker): the username of the postgres user. Defaults to postgres

⁠Database configuration

• Beep Boop requires a database to store and retrieve data from. Currently, we are using a postgres database, but the stack is mostly database-agnostic. Setting up database for development is a little involved, and can involve a few steps. Below are a few options:
  • Remote database: Use an already setup database. Easiest option
  • Developer-local database: Either a raw postgres installation from postgres.org⁠ or in the docker container. Install docker from docker⁠. Then, start a database instance by running docker-compose up in the beep-boop directory

    • Next, we need to create the tables on the database. Make sure db_string is properly set in the environment. For the manual install, run alembic upgrade head in the alembic folder, and for docker users an additional dockerfile is provided, which can be run by docker-compose -f docker-compose.yml -f initalize-db.yml up. Since this is a local database, normally the connection is through localhost as the hostname and the default port 5432.

⁠Database initialization

• From feature/admin-system, beep-boop now uses an administration system separately from discord roles. Beep-Boop will also only work on a series of whitelisted servers, stored in the servers table/model. The add-server will whitelist the server where the command is run, setting the owner of the server to the invoker. add-server may only be run by the application owner (the person who made the discord application), except indebug mode, where anyone may use the add-server command.

⁠Permissions model

• Three levels of permission in beep-boop. Each server has its own set of owners and admins, but players are shared.
  • Owner: The owner of beep-boop in this server. Generally the discord user who ran the add-server command, but may be changed using change-owner (TODO). The owner is the only one who can add and remove admins in this server, and have all the permissions of the other users
  • Admin: An admin in the server. Admins may create, start and end games, as well as manage the players in a game via add/remove/freeze.
  • Player: A normal player. They may join and leave games via the website (TODO) or the discord bot message.

⁠Frontend/Backend login and register process

• frontend/login: open backend/discord in window

  • backend/discord redirects to discord.com/oauth
  • user authenticates via discord which redirects to backend/discord_callback?code=blah
  • backend/discord_callback stores the code and generates an API Key
    • then backend/discord_callback sends a message via postMessage to the parent window (frontend/login)
    • the message is in the format {"signedUp": boolean, apiKey: "string"}. If a user is not signed up, they should be prompted to activate their account by redirecting to frontend/register. (TODO - message is currently just the API-key, feature/webapi-register will change this)

• frontend/login stores the apiKey in localStorage and redirects to /register or the main page /

• frontend/register: register a player. Use a form to grab some values from the user.

  • then, post /player with required ubisoft account using the apiKey. A user is UNABLE to join, create games unless their account is activated.[]

⁠API summary

• [^create | POST /waiting_room] forms a waiting room. Users may join by reacting to a message the bot sends or via the web frontend. This will happen over a period of time, with the room slowly filling up.
  • [^set-message message] or via website (TODO) to change the message used in the discord message
• [^kick @name | DELETE /waiting_room/{id}/players ] Admins may remove players from the room. Individuals may also remove themselves by calling this endpoint without any params
• [^add @name | POST /waiting_room/{id}/players ] Admins may add players from the room. Semantics same as remove
• [^freeze | PUT /waiting_room/{id} ] admin can freeze the lobby to prevent other people from joining or leaving
• [^unfreeze | PUT /waiting_room/{id} ] unfreezes the lobby. Semantics same as freeze
• [^start | POST /waiting_room/{id}/create-lobbies ] Admin may start a lobby from the players in the waiting room, "balanced" teams will be formed, and an unconfirmed set of lobbies will be returned. Start may be called multiple times to the effect of shuffling the members
• [^register @discord uplay_name | POST /players] Register a new player with a uplay name
  • [^link @discord uplay_name | PUT /players/{id} ] change the uplay name of this player
  • [^refresh-stats @discord | POST /players/{id}/refresh-stats ] refresh the stats on this player
• [^stats @player | GET /players ] get stats
• [^owo] owo

⁠WIP - this may change in the future

• [^enter-results [lobby-num]]
  • enter match results in format [team1 - team 2]
  • save to individual players stats
  • read the image; spit back a bunch of scores of each individual person.
• [^auto-ban map1 map2 map3 ... ] ban maps for all lobbies in a round
• [^start-bans lobby-num] start the bans for lobby x;
• [^map-pool add | remove map ] add a map
  • [^ban x] bans a map; also enforce that only the team captains (first player) of each team
  • automatically list the remaining map
• • ability for admin to change the text channel that gets printed to [^set-updates #channel]
  • ability to get your stats via dm or through server chat [^stats @name]
  • general improvements to the algorithm
  • **move people to appropriate vc's [^move-people]**ne) [^lobby] ability for anyone to view the currently lobby
  • (done
  • add descriptions to each command

⁠Bingo (depreciated)

For bingo, you need to activate the Google docs api, given here: https://developers.google.com/docs/api/quickstart/python⁠ Complete step 1. Step 2 is covered by the requirements.txt.

Create a directory in the root folder called data. Move the credentials.json file you got from the Google docs api activation into this directory. In this directory, create a json file called file_location.json of the format:

{
  "document_id": "your_document_id_here"
}

The document id can be found in the url of the google drive document. This document is where the bingo list will be created.

The bingo bot as of now requires read and write access to the google drive. Make sure you have access to the drive.