Wiki

BogaBot is a modular Discord bot for a group of friends. The core module is the League of Legends ranking: link a Riot account → ingest matches from the Riot API → compute a configurable score per player → publish rankings in Discord. Around that there's a troll detector that judges every match, live alerts, sounds in voice channels and a points system you can redeem.

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), each module is a self-contained cog, and both the ranking formula and the troll detector are YAML files 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.

Also

• /trolls shows who's been trolling the most; /troll-analizar tells you why your last match added (or didn't add) troll points.
• /sonido makes the bot join your voice channel and play a clip.
• If you have the points role, you earn points hanging out in voice with friends and playing LoL. Check how many you have with /puntos and redeem them for your own sound with /canjear-sonido.
• If the server set up a commands channel, use them there. The ones marked 🔒 in /help reply only to you.

Setup on Windows / PowerShell: python -m venv venv → venv\Scripts\activate → pip install -r requirements.txt. On Linux: sudo apt install ffmpeg for the sounds.

Permissions when inviting it

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

• View Channel, Send Messages, Read Message History and Embed Links on the storage, rankings, general, trolls and alerts channels.
• Connect and Speak for the sounds in voice 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.

/riot-key <key> (dev role, in the admin channel) validates the new key against Riot, applies it without restarting and stores it in RIOT_KEY_FILE so it survives restarts. With no argument, it shows when the current one expires. With RIOT_KEY_TTL_HOURS above 0, the bot warns in the admin channel (tagging the dev role) RIOT_KEY_WARN_MINUTES before it expires and when it does.

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, and if a required variable is missing the bot won't start and says which one. 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.

If BOT_CHANNEL_ID is set, regular members can only use commands in that channel (or the admin one); devs, anywhere. The administration commands (/link-admin, /unlink-admin, /ingest-now, /riot-key, /trolls-reiniciar, /trolls-recalcular) also require the admin channel.

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 daily and weekly rankings count Ranked only (Solo/Duo and Flex). Normals, ARAM and rotating modes are still stored (they feed the troll detector and the points), but don't add to the ranking.
4. The windows are day and week from Monday 00:00 local time (TIMEZONE, default Buenos Aires).
5. In each window the stats are aggregated per player and the scoring engine applies the formula from config/scoring.yaml.
6. The daily job runs at DAILY_POST_HOUR:DAILY_POST_MINUTE (23:55 recommended): ingestion → the day's ranking → if there were trolled games, how the week's troll ranking is going. 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 — and crowns the Troll of the week.
7. Dedup by (match_id, discord_id) with no cursor: each run asks “since Monday” (with a one-day margin, for matches that cross midnight) 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.

normalization accepts zscore (recommended), minmax (0..1 scale between worst and best) or none (raw value; weights are calibrated by hand).

Metrics active by default

↓ = lower is better (the normalized value is inverted). A match is carried if you won it with KDA ≥ 5 and trolled if you finished with KDA < 0.5. The engine also supports these metrics, off by default — enable them by adding them to the YAML: avg_kills, avg_assists, cs_per_min, games_played.

After every match, each group player is judged with the rules below. The ones marked timeline use one more Riot query (what happened and when); the rest come from the match stats. Everything is tuned in config/trolls.yaml without touching code (restarting the bot), and since the troll ranking is computed on the fly, a change there recalculates the history too.

How points add up

• Each rule that's met is a charge with its troll points.
• In ranked (Solo/Duo or Flex) points are multiplied by ×1.25; if the team won anyway, by ×0.5 (they carried them).
• Minor charges (🔸 in the table: poor performance, low KP, low damage, lost lane, vision, farm, first blood, FF…) add up to 4 at most between all of them. A trolled game takes a strong signal: AFK, 0 kills and 0 assists, sold items, letting the base fall, feeding, a throw or being the team's anchor.
• Thresholds change by mode: ARAM and chaotic modes (URF, One for All…) tolerate more deaths, and the lane and base rules are Summoner's Rift only.
• Rules that measure the same thing don't stack: feeder replaces tragic KDA and time dead; blind replaces no control wards.

What happens depending on the match's points

Only matches from the last 36 h are announced (alert_max_age_hours): if the bot was down or someone just linked, old games aren't posted.

Troll ranking (/trolls)

It sorts by troll index — points per match —, not by the total, so playing more doesn't add up: whoever trolls hard in 2 matches ranks above whoever played 18 and trolled 2. So a single match doesn't decide by chance, each player starts with 2 “ghost” matches worth the group average (index.prior_games) and one match counts 30 points at most (index.max_game_points). It shows the tier, the share of trolled matches and the trend versus the previous period (📈 / 📉 / ➡️ / 🆕). /trolls-reiniciar resets it to zero from that moment.

Tiers (by index)

The rules

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 that counts, posts a board with the 10 positions, tagging the group's players who were in it (with each one's result, in case they ended up on opposing teams) and a troll-o-meter with everyone's troll points.

Alerts come out of any ingestion — the periodic check, the daily job or /ingest-now — and once per match: ingestion holds a lock and the dedup means running everything together duplicates nothing.

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. Network errors against Riot are retried with backoff before warning.

The bot joins a voice channel, plays a short clip and leaves. One playback at a time across the whole bot, and any clip is cut at 20 s just in case. It needs ffmpeg installed and the Connect and Speak permissions.

Three ways to trigger one

• On demand: /sonido [name] in your voice channel (empty = a random one).
• Forced (dev): /sonido-forzar [name] [channel] — in the channel you pick, in yours or in a random one with people. If another one is playing, it waits its turn.
• At random: every SOUNDS_CHECK_INTERVAL_MINUTES (5) the bot rolls a die with SOUNDS_CHANCE (15%). If it hits, within the active hours and past the cooldown (SOUNDS_COOLDOWN_MINUTES, 45), it picks a channel with at least one person (the AFK one doesn't count) and a random clip. Turned off with SOUNDS_ENABLED=false.

How they're loaded

• /sonido-add (dev): permanent. mp3, ogg or wav, up to 2 MB.
• /canjear-sonido (points role): temporary, paid with points. See below.
• Clips live in SOUNDS_DIR, outside git. Owner and expiry of redeemed ones are kept in SOUNDS_DIR/_meta.json; a sound with no entry there is permanent.

ffmpeg.org ↗

Members with POINTS_ROLE_ID earn points and redeem them. Without that role configured, the module isn't loaded.

How they're earned

• Voice: 1 point every 5 minutes to each member with the role who's in a voice channel with at least one other human (the AFK channel and being deafened don't count). Cap: 60 per day.
• LoL: 5 for each new match stored and 5 more if you won it. The ingestion dedup guarantees each match pays out only once.
• By hand: a dev can add or subtract with /puntos-dar.

Redeem: your own sound

/canjear-sonido <name> <audio> costs 100 points: the clip can be up to 8 s, stays loaded for 7 days and is deleted on its own when it expires. At most 1 active per person (you can delete it earlier with /sonido-del). The bot measures the length with ffprobe and only charges if the clip passes the check, then announces the redemption in the channel. Every number is changed through environment variables.

Local

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

Linux server (systemd)

The repo ships deploy/bogabot.service. Setup is one-time: clone, venv + pip install -r requirements.txt, install ffmpeg, copy the .env.production over scp (mode 600), install the service and systemctl enable --now bogabot. State (points, Riot key, troll ranking reset) lives in data/, outside git.

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

To update: git pull + pip install if requirements.txt changed + systemctl restart bogabot. Changing the Riot key needs no deploy: /riot-key from Discord. The repo also ships a GitHub Actions workflow that deploys every push to main that passes the tests, meant for when there's a VPS.

• Scope: beta with the group. LoL (ranking and trolls), sounds, points and help modules. 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. Points and redeemed sounds go to JSON files in data/ and sounds/.
• Queues: the daily and weekly ranking counts Ranked only (Solo/Duo and Flex); the “Trolls and Pros” recap, Flex only. The troll detector and the points look at every queue.
• Region: decided for LAS (la2 / americas); configurable for others.
• Tests: python -m pytest — scoring, dedup, match-v5 mapper with timeline, troll rules, config, troll ranking, ingestion and alert routing.

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