Wiki

BogaBot is a modular Discord bot. Module 1 (the current MVP) is a group of friends' League of Legends ranking: link a Riot account → ingest matches from the Riot API once a day → compute a configurable score per player → publish rankings in Discord.

It's built in replaceable layers: storage sits behind an interface (today it's “Discord as a database”; moving to SQLite or Postgres is a new class), modules are self-contained cogs, and the ranking formula is a YAML file you can edit without touching code.

If the bot is already on your server, the only thing you have to do is link yourself:

1. Run /link Name#TAG with your full Riot ID (the name and tag you see in the LoL client, e.g. Faker#KR1).
2. The bot validates the account against the Riot API. If it exists, it's linked and your matches this week start counting.
3. Use /ranking whenever you want to see the table, or wait for the automatic post every night.

Setup on Windows / PowerShell: python -m venv venv → venv\Scripts\activate → pip install -r requirements.txt.

Permissions when inviting it

In OAuth2 → URL Generator, scopes bot and applications.commands. Bot permissions:

• Send Messages, Embed Links, View Channel and Read Message History on the storage and rankings channels.
• Manage Roles only if you're going to use LOL_ROLE_ID (so the bot assigns that role on linking).
• It needs no privileged intents: leave them off.

With developer mode on (Settings → Advanced), right-clicking each channel or role lets you copy its ID. You also need the server ID for DISCORD_GUILD_ID.

At developer.riotgames.com you generate the key. It goes in RIOT_API_KEY.

Also set RIOT_PLATFORM and RIOT_REGION to your region. It defaults to LAS: RIOT_PLATFORM=la2, RIOT_REGION=americas (LAS, LAN and NA route to americas).

Everything comes from a .env file — the code never hardcodes secrets or IDs. None of the real .env.* files are committed.

The environment is chosen by the shell variable BOGABOT_ENV (set it in the terminal before running, not inside the .env):

# local, default staging
python run.py

# explicit
$env:BOGABOT_ENV = "production"
python run.py

# with the script (console + log in logs\)
.\scripts\run_bot.ps1 -Environment production

The default is staging on purpose: if you forget to set the variable, you never run against production by accident. Recommended: staging points at a different bot and a different server, not the same one, because storage lives in Discord channels and you'd mix test data with real data.

/ingest-now is idempotent: the dedup by (match_id, puuid) skips what's already stored, so running it extra times duplicates nothing.

1. Each match is stored as one record per player, but only if you played it alongside at least one other linked member of the group. Solo games are discarded on ingestion (it checks metadata.participants of the match-v5 JSON).
2. It excludes remakes (under 5 min or early surrender).
3. The windows are day and week from Monday 00:00 local time (TIMEZONE, default Buenos Aires).
4. In each window the stats are aggregated per player and the scoring engine applies the formula from config/scoring.yaml.
5. The daily job runs at DAILY_POST_HOUR:DAILY_POST_MINUTE (23:55 recommended): ingestion → the day's ranking. On Mondays it also posts the weekly “Trolls and Pros” recap for the week that just closed — counting Ranked Flex only (queue 440), to measure the group's serious play.
6. Dedup by (match_id, puuid) with no cursor: each run asks “since Monday” and skips what's already stored.

The formula lives in config/scoring.yaml and is edited without touching code. For each player every metric is computed (averaged per match), normalized across all players, and the final score is the sum of weight × normalized_value.

Metrics active by default

↓ = lower is better (the normalized value is inverted). The engine also supports avg_kills, avg_assists, cs_per_min, off by default — enable them by adding them to the YAML.

Match finished

If MATCH_NOTIFY_CHANNEL_ID is set, every MATCH_POLL_INTERVAL_MINUTES (5 by default) the bot checks for new matches and, for each one played with another linked member, posts a message tagging the group's players who were in it — with each one's result, in case they ended up on opposing teams.

Trolls and blowouts

Every scheduler run detects, within the last 48 h, trolled games (KDA < 0.5 and FF before 20 min) and blowouts (a loss before 25 min). Trolls are announced in RANKING_CHANNEL_ID; blowouts in GENERAL_CHANNEL_ID. There's an all-time trolls ranking, and the alert queries the match timeline to show the minute you first died.

Logs to Discord

If LOG_CHANNEL_ID is set, logs at level LOG_CHANNEL_LEVEL (WARNING by default) or higher are forwarded to that channel too, on top of the console. Meant to let you catch errors (Riot down, expired key) without watching the terminal.

Local

python run.py directly, or .\scripts\run_bot.ps1 [-Environment production], which opens a visible console and mirrors everything to logs\<ambiente>\. Don't start two instances against the same environment/server: they'd answer commands twice.

VPS (systemd)

The repo ships deploy/bogabot.service. Setup is one-time: clone, venv + pip install, copy the .env over scp, install the service and systemctl enable --now bogabot. After that, every push to main that passes the tests deploys itself via GitHub Actions (git pull + pip install + systemctl restart).

sudo cp deploy/bogabot.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now bogabot
sudo journalctl -u bogabot -f # live logs

• Scope: module 1 (LoL ranking). No AI features yet — they're in the backlog as a separate cog.
• Storage: today it's Discord (JSON messages in a private channel + an in-memory index). It's O(n) messages; moving to a real DB is a new class in storage/ and one line in bot.py.
• Queues: the daily/weekly ranking counts every queue (ARAM and rotating modes included); the “Trolls and Pros” recap is Ranked Flex only.
• Region: decided for LAS ( la2 / americas); configurable for others.

Bugs, ideas and requests → the repo's issues.