A Valorant bot developed by a Computer Science student as a practical application of Data Engineering and Software Architecture. This project is maintained alongside university commitments, following a weekly sprint cycle to ensure continuous improvement and code quality. It uses web scraping with Selenium on vlr.gg to archive data from VCT matches. It analyzes this data and makes it available for visualization via Discord. We use a PostgreSQL database (hosted on Neon Tech's free plan) to store information about teams and matches.
Now the bot also tracks the performance table from each active tournament (linked to campeonatos, see Database), capturing metrics like Rating, ACS and ADR to provide deeper match analysis.
Architectural Refactor: The code previously contained in main.py is now split between main.py and brain.py. File Structure to more information.
Data Analysis: Now we can access the information stored in stats_players. Integrated Pandas for advanced team statistics (based on player performance).
New UI: info_time Shows the mean stats of the last tournament (mean of the ACS of each players, for example. Clutches are shown in the format won/played, being won and played the sum instead of the mean) in the first page. Received a third page that contais the 'historical stats'. It works the same as the stats of the last tournament, but using data from all the tournaments registered.
Search Normalization: Users no longer need to include diacritics to find teams. For example, searching for "kru" will now correctly match "KRÜ".
The core command of the bot. It provides a multi-page "book" with deep insights into VCT teams.
- Page 1: Performance Summary: Shows average stats from the latest tournament (e.g. Rating, ACS, KAST, ADR) and the team's match history
- Page 2: Map Performance: Displays win rates for each composition used in the current map pool, including Attack vs. Defense efficiency.
- Page 3: Historical records: Average stats but using the mean of each tournament registered.
|
|
Note: Page 3 (Historical records) follows the same visual layout as Page 1. Thats why it's not shown. In the section below, we have links for all important files with description. If interested, look for
Screenshots
To ensure precision, this command lists all available teams and their corresponding tags, helping users find exactly what they are looking for.
| File/Folder | Type | Summary |
|---|---|---|
| Starting v2 | .ipynb |
Initial planning and first steps for the SQL database. |
| Auto | .py |
Web scraping logic featuring vlr_stealer and stats_manager classes. |
| DB_handler | .py |
INSERT logic handled by the DB_handler class. |
| Auto_scraper.py | .py |
Integration of auto.py and DB_handler.py (Scraping then inserting into DB). |
| Disc_buttons | .py |
Interactive buttons for navigating Discord embeds. |
| Main | .py |
Discord interface and bot command handling. |
| Brain | .py |
Back-end logic: handles database, caching, and data analysis. |
| Scraper | .yml |
Automation logic for GitHub Actions. |
| Agents | dir/ .png |
PNG files used to create Discord emojis for each agent. |
| Teams | dir/ .png |
PNG files used to create Discord emojis for each team. |
| Screenshots | dir/ .png |
Screenshots of the bot working. All of them, except info_time3, were already shown above. |
| Documentation | dir/ .md |
Project documentation and UML Diagram. |
| ⤷ Requirements | .md |
Functional and Non-Functional Requirements. |
| ⤷ Classes | .md |
Class Diagram representing the system structure. |
| ⤷ Sequence | .md |
Sequence Diagram showing object interactions. |
| ⤷ Deployment | .md |
Deployment Diagram showing infrastructure and cloud services. |
| ⤷ Privacy | .md |
Privacy Policy regarding data handling. |
| ⤷ Terms | .md |
Terms of Service for bot and dashboard usage. |
| DB Sch | .svg |
Database Schema diagram. |
| SQL_Script | .sql |
Database creation script. |
Below is the deployment architecture of the system, ilustrating how the different cloud services and containers interact:
further diagrams or detailed description is contained in
docs\files. Consult File Structure to find them.
Data Mapping Note:
stats_playerstable may raise errors during insertion if a record contains "N/A". This usually happens when a team changes its tag on vlr.gg (e.g., when DRX changed to KRX), causing a mismatch with the existing database records. While new players are added automatically, team tags must be updated manually in thetimestable to maintain Referential Integrity.
Hosted on PostgreSQL (Neon Tech free plan: 0.5GB storage, 100 CU-hours). The database consists of 9 tables. Descriptions of Portuguese attributes:
- Agentes: Agents ('nome' = name)
- Mapas_lista: Map list
- Composicoes: Team compositions
- Mapas_jogados: Played maps ('vencedor_mapa' = map winner)
- Partidas: Matches ('vencedor_time_letra' = winning team letter)
- Campeonatos: Tournaments ('completo' = completed)
- Times: Teams ('regiao' = region)
Technical Details:
- Emojis: Attributes like
emojiandemoji_discordfollow the Discord format:<:mibr:1370182490953748490>. - Pickban Log: Formatted as JSON:
{ "Abans": [12, 2], "Bbans": [7, 9], "Apicks": [5], "Bpicks": [4], "decider": 1 }, where numbers refer tomapas_lista.id. - Team References:
atk_str,vencedor_mapa, andvencedor_time_letrause 'A' or 'B' values. - Round History:
rounds_stringresemblesBBBBABBBABBBXAABAAAABAB. 'A'/'B' indicates the winner of that round; 'X' at position 13 marks half-time, and at position 26 marks overtime. - Percentage-based attributes: Stored as decimals (e.g.,
0.55for 55%). Examples are HS and KAST.
DISCORD_TOKEN: Your Discord bot token.DATABASE_URL: Your PostgreSQL connection string.GUILD_ID: Server ID for testing (removeguild=...from commands to sync globally, though this is slower).CREATOR_ID: Your Discord ID (restricts RAM cache updates to the owner).
- Clone the repository.
- Install dependencies:
pip install -r requirements.txt. - Set up the Database (see QuickBuild).
- Create a
.envfile with your credentials (rename .env.example and fill it in). - Run
python src/auto_scraper.pyto populate your database. - Run
python src/main.pyto start the bot.
To replicate the database on Neon Tech:
- Access Neon Tech Console.
- Create a new project.
- Open the SQL Editor.
- Copy and execute the SQL script provided to generate the tables and foreign keys.
- Copy your connection string from the dashboard.
Note: Ensure
sslmode=requireis present in the URL. - Manual Data Seeding: Some tables do not auto-populate in this version. You should checkout the
discBot_prototypebranch and usemigrar.ipynbto populate thetimes,mapas_lista, andagentestables. Note that some records (likecampeonatos) must be added manually. You will also need to manually update these tables when new maps or agents are released, or when the map pool changes.
This project follows Agile/Scrum principles for development. You can track the Real-time progress, upcoming features, and bug fixes on my Github Project Board.
Current Focus:
- Releasing project to public
- Preparing for Discord Bot Verification