varunda / pog-bot

Discord bot for Planetside Open Games (POG)

Planetside Open Games bot

This repository contains POG bot, a discord bot used by Planetside Open Games to provide a community-driven matchmaking system for 6v6 infantry scrims in Planetside2.

Work in progress: Github Pages

Requirements:

• This project relies on several python dependencies.
• A discord bot application and channels have to be created.
• A MongoDB database is used for persistent data storage.
• Jaeger accounts are pulled from a Google Sheet.
• To retrieve Planetside2 information a Daybreak Census ID has to be provided.
• To use the TeamSpeak 3 Integration, set up an instance of TS3AudioBot.
• Finally, to initialize the application, scripts functions are provided.

Python dependencies:

• Python 3.11 or above is required to run the project.
• We recommend using pdm to set up the project environment. It will install automatically install the required dependencies from the pdm.lock file provided with the project.
• Alternatively, the dependencies are also listed in the pyproject.toml file.

Notes for the developer:

• Master branch is a release branch, it will stay clean and is synced with the official POG hosting server.
• So developments should be done on feature or development branches and will be then merged in.
• Keep fork repos up to date from upstream as much as possible.
• google_api_secret.json and config.cfg are not available for confidentiality reasons, templates are given instead.
• The code of the application itself can be found in the bot folder. It contains:
  • The cogs folder: it holds cogs modules as described in discord.py. Each of them regroups a set of commands and their associated checks. These modules are not to be imported in any way (they are only launched through the discord.py client)
  • The display folder: it is a python package handling all the display from the application to discord. All discords embed and strings used are stored there.
  • The modules folder: it is a python package containing general interfaces and tools that can be used in the rest of the application.
  • The classes folder: it contains the main classes of the application: Player, Team, Weapon, Base, Account, etc...
  • The lib folder: it contains third-party modules that were modified for the purpose of the application.
  • The match folder: it contains all the code handling the match processes and commands.

Discord Bot Component

Create a bot application following the discord.py documentation. The client-secret retrieved at this manual has to put into the configuration file:

[General]
token = RetrievedDiscordApiBotToken

Create channels and roles

To retrieve discord channel, message and role-ids you have to enable Discord Developer Mode which can be toggled at appearance. Copy ID will then appear at the right click menu for channels, messages and roles. At that point you can populate the [channels] and [roles]sections of the configuration file.

Preparing MongoDB Component

Pymongo is used for interaction with the mongodb. The database should contain several collections:

• One for the user data.
• One for the bases.
• One for the weapons.
• One for the matches.
• One for the player stats
• One for persistent restart data
• One for jaeger account usage Check script.py to populate the databases. The naming of these collections can be configured at the [Collections] part of the configuration file.

There are two common ways to get MongoDB running: Atlas and Manual Deployment.

Atlas

Atlas can be run using a free instance at MongoDB Cloud Atlas When using MongoDB Atlas the following URI format is expected:

[Database]
url = mongodb+srv://username:password@clusteruri/databasename
cluster = ClusterName

Manual Deployment

When using a single manually deployed MongoDB instance, omit +srv and remove the database name from the url and put it at cluster instead:

[Database]
url = mongodb://username:password@host:port/
cluster = DatabaseName

Preparing Google Component

The Gspread module is used for interaction with google API. Follow these steps to create your google_api_secret.json

Prepare Google Sheet

An example sheet has been provided called accounts_sheet_template.xlsx. By creating a new Google Sheet in your Drive and importing the excel file through the menu you can avoid format and naming convention errors.

The accounts field from the [Database] section of the configuration file has to contain the ID of the Google Sheet. This ID can be easily retrieved from the URI of the document: https://docs.google.com/spreadsheets/d/GOOGLE_SHEET_ID/edit#gid=0.

Finally, add the service account email to the shared users with editor permissions to the google sheet. This email is also listed as client_email in the google_api_secret.json file.

Assigning Census ID

Communication with the Daybreak Census API is required to retrieve game information, therefore you have to supply a Service ID. You can apply for one at the Daybreak Census website. Once you obtained an ID, add it the configuration as api_key:

[General]
api_key = Daybreak_Registered_Service_ID

Teamspeak integration

The bot used for Teamspeak audio integration is Splamy's TS3AudioBot. This bot works on the dotnet runtime and can be built and installed following the readme available in TS3AudioBot github's repo.

TS3-bot folder structure

The structure of the TS3AudioBot folder is the following:

TS3-bot
+-- TS3AudioBot.dll
+-- rights.toml
+-- ts3audiobot.toml
+-- ...
+-- audio
|   +-- audio_file_1.mp3
|   +-- audio_file_1.mp3
|   +-- ...
+-- bots
|   +-- 1
|   | +-- bot.toml
|   +-- 2
|   | +-- bot.toml
|   +-- 3
|   | +-- bot.toml
|   +-- ...

The audio files should be put in the audio repository. Each sub-repository of bots represent TS3 bot (one bot per match channel is needed).

Main configuration file

The first file to modify is ts3audiobot.toml. The relevant parameters for are listed below. You may want to change the parameters depending on your project file structure.

[configs]
# Path for the bots
bots_path = "bots"

[factories]
# Path for audio files
media = { path = "audio" }

[bot.audio]
# Activate subscription-based whispers
send_mode = "!whisper subscription"


[bot.connect]
# TS3 default connect information
address = Your_TS3_Url
channel = Your_TS3_Bot_Channel_Id (example: /10)

Additionally, add access to all commands for localhost in the rights.toml file:

# Admin rule
[[rule]]
        # Treat requests from localhost as admin
        ip = [ "::ffff:127.0.0.1" ]
        "+" = "*"

Configuring individual bots

Each individual bot can also be configured, in each bot.toml files. This allows for example to change the name of each individual bot.

[connect]
# Client nickname when connecting.
name = "POG_3"

Setting up TS3 channels IDs

The Teamspeak section of the configuration file can now be completed

[Teamspeak]
url = # Teamspeak bot webapi url
lobby_id = # Lobby channel id
matches = # Matches channel ids (example: 1/2/3,4/5/6) (matches separated by commas, channels by slashes, no spaces)

Populating the collections

The file scripts.py contains two functions called push_accounts() and get_all_maps_from_api(). The file weapons_script.py contains the function push_all_weapons(). Running all of these functions will populate the MongoDB users, bases and weapons collections, allowing you to run main.py.