Wiki

BogaBot es un bot de Discord modular para un grupo de amigos. El módulo central es el ranking de League of Legends: vincular cuenta de Riot → ingerir partidas desde la Riot API → calcular un puntaje configurable por jugador → publicar rankings en Discord. Alrededor de eso hay un detector de trolls que juzga cada partida, avisos en vivo, sonidos en los canales de voz y un sistema de puntos canjeables.

Está armado por capas reemplazables: el storage vive detrás de una interfaz (hoy es “Discord como base de datos”; migrar a SQLite o Postgres es una clase nueva), cada módulo es un cog autocontenido y tanto la fórmula del ranking como el detector de trolls son archivos YAML editables sin tocar código.

Si el bot ya está en tu server, lo único que tenés que hacer es vincularte:

1. Corré /link Nombre#TAG con tu Riot ID completo (el nombre y el tag que ves en el cliente de LoL, ej. Faker#KR1).
2. El bot valida la cuenta contra la Riot API. Si existe, queda vinculada y tus partidas de esta semana empiezan a contar.
3. Usá /ranking cuando quieras ver la tabla, o esperá el posteo automático de cada noche.

Además

• /trolls muestra quién viene trolleando más; /troll-analizar te dice por qué tu última partida sumó (o no) puntos troll.
• /sonido hace que el bot entre a tu canal de voz y tire un audio.
• Si tenés el rol de puntos, sumás estando en voz con amigos y jugando LoL. Mirá cuántos tenés con /puntos y canjealos por un sonido propio con /canjear-sonido.
• Si el server configuró un canal de comandos, usalos ahí. Los que tienen 🔒 en /help te responden solo a vos.

Setup en Windows / PowerShell: python -m venv venv → venv\Scripts\activate → pip install -r requirements.txt. En Linux: sudo apt install ffmpeg para los sonidos.

Permisos al invitarlo

En OAuth2 → URL Generator, scopes bot y applications.commands. Bot permissions:

• View Channel, Send Messages, Read Message History y Embed Links en los canales de storage, rankings, general, trolls y avisos.
• Connect y Speak para los sonidos en los canales de voz.
• Manage Roles solo si vas a usar LOL_ROLE_ID (para que el bot asigne ese rol al vincular).
• No requiere intents privilegiados: dejalos apagados.

Con el modo desarrollador activado (Ajustes → Avanzado), click derecho sobre cada canal o rol te deja copiar su ID. Necesitás también el ID del server para DISCORD_GUILD_ID.

En developer.riotgames.com generás la key. Va en RIOT_API_KEY.

/riot-key <key> (rol dev, en el canal de admin) valida la key nueva contra Riot, la aplica sin reiniciar y la guarda en RIOT_KEY_FILE para que sobreviva reinicios. Sin argumento, muestra cuándo vence la actual. Con RIOT_KEY_TTL_HOURS mayor a 0, el bot avisa en el canal de admin (etiquetando al rol dev) RIOT_KEY_WARN_MINUTES antes de que venza y cuando vence.

Ajustá también RIOT_PLATFORM y RIOT_REGION a tu región. Por defecto está en LAS: RIOT_PLATFORM=la2, RIOT_REGION=americas (LAS, LAN y NA rutean a americas).

Todo sale de un archivo .env — el código nunca hardcodea secretos ni IDs, y si falta una variable requerida el bot no arranca y dice cuál. Ninguno de los .env.* reales se commitea.

El ambiente lo elige la variable de shell BOGABOT_ENV (se setea en la terminal antes de correr, *no* dentro del .env):

# local, default staging
python run.py

# explícito
$env:BOGABOT_ENV = "production"
python run.py

# con el script (consola + log en logs\)
.\scripts\run_bot.ps1 -Environment production

El default es staging a propósito: si te olvidás de setear la variable, nunca corrés contra producción por accidente. Recomendado: staging apunta a otro bot y otro server, no al mismo, porque el storage vive en canales de Discord y mezclarías datos de prueba con datos reales.

Si hay BOT_CHANNEL_ID, los miembros comunes solo pueden usar comandos en ese canal (o en el de admin); los devs, en cualquier lado. Los comandos de administración (/link-admin, /unlink-admin, /ingest-now, /riot-key, /trolls-reiniciar, /trolls-recalcular) además exigen el canal de admin.

1. Cada partida se guarda como un registro por jugador, pero solo si la jugaste acompañado de al menos otro vinculado del grupo. Las solitarias se descartan en la ingesta (se chequea metadata.participants del JSON de match-v5).
2. Se excluyen los remakes (menos de 5 min o early surrender).
3. El ranking diario y el semanal cuentan solo Ranked (Solo/Duo y Flex). Normales, ARAM y rotativos se guardan igual (sirven para el detector de trolls y los puntos), pero no suman al ranking.
4. Las ventanas son día y semana desde el lunes 00:00 hora local (TIMEZONE, default Buenos Aires).
5. En cada ventana se agregan las stats por jugador y el motor de scoring aplica la fórmula de config/scoring.yaml.
6. El job diario corre a DAILY_POST_HOUR:DAILY_POST_MINUTE (recomendado 23:55): ingesta → ranking del día → si hubo trolleadas, cómo va el ranking troll de la semana. Los lunes, además, el recap semanal “Trolls y Pros” de la semana que cerró — contando solo Ranked Flex (queue 440), para medir el juego serio del grupo — y la corona del Troll de la semana.
7. Dedup por (match_id, discord_id) sin cursor: cada corrida pide “desde el lunes” (con un día de margen, por las partidas que cruzan la medianoche) y saltea lo ya guardado.

La fórmula vive en config/scoring.yaml y se edita sin tocar código. Para cada jugador se calcula cada métrica (promediada por partida), se normaliza entre todos los jugadores y el puntaje final es la suma de peso × valor_normalizado.

normalization acepta zscore (recomendado), minmax (escala 0..1 entre el peor y el mejor) o none (valor crudo; los pesos se calibran a mano).

Métricas activas por defecto

↓ = menos es mejor (el valor normalizado se invierte). Una partida es carreada si la ganaste con KDA ≥ 5 y troleada si terminaste con KDA < 0,5. El motor soporta además estas métricas, desactivadas por defecto — se activan agregándolas al YAML: avg_kills, avg_assists, cs_per_min, games_played.

Después de cada partida, cada jugador del grupo se juzga con las reglas de abajo. Las que dicen timeline usan una consulta más a Riot (qué pasó y cuándo); el resto sale de las stats de la partida. Todo se ajusta en config/trolls.yaml sin tocar código (reiniciando el bot), y como el ranking troll se calcula al vuelo, un cambio ahí recalcula también el historial.

Cómo se suman los puntos

• Cada regla que se cumple es un cargo con sus puntos troll.
• En ranked (Solo/Duo o Flex) los puntos se multiplican por ×1,25; si igual ganaron, por ×0,5 (lo llevaron de mochila).
• Los cargos menores (🔸 en la tabla: mal rendimiento, poca KP, poco daño, línea perdida, visión, farm, primera sangre, FF…) suman entre todos como mucho 4. Para ser trolleada hace falta una señal fuerte: AFK, 0 kills y 0 asistencias, items vendidos, dejar caer la base, feeder, throw o ancla del equipo.
• Los umbrales cambian según el modo: ARAM y los modos caóticos (URF, One for All…) toleran más muertes, y las reglas de línea y de base son solo de la Grieta.
• Reglas que miden lo mismo no se suman: feeder reemplaza a KDA de la vergüenza y a tiempo muerto; ciego reemplaza a sin control wards.

Qué pasa según los puntos de la partida

Solo se avisan partidas de las últimas 36 h (alert_max_age_hours): si el bot estuvo caído o alguien se acaba de vincular, lo viejo no se anuncia.

Ranking troll (/trolls)

Ordena por índice troll — puntos por partida —, no por el total, así que jugar más no suma: el que la trollea fuerte en 2 partidas queda arriba del que jugó 18 y trolleó 2. Para que una partida suelta no decida por azar, cada jugador arranca con 2 partidas “fantasma” que valen el promedio del grupo (index.prior_games) y una sola partida cuenta como mucho 30 puntos (index.max_game_points). Muestra la categoría, el % de partidas trolleadas y la tendencia contra el período anterior (📈 / 📉 / ➡️ / 🆕). /trolls-reiniciar lo pone en cero desde ese momento.

Categorías (según el índice)

Las reglas

Partida terminada

Si MATCH_NOTIFY_CHANNEL_ID está seteado, cada MATCH_POLL_INTERVAL_MINUTES (5 por defecto) el bot chequea partidas nuevas y, por cada una que cuente, postea un cuadro con las 10 posiciones, etiquetando a los jugadores del grupo que la jugaron (con el resultado de cada uno, por si quedaron en equipos contrarios) y un troll-o-metro con los puntos troll de cada uno.

Los avisos salen de cualquier ingesta — el chequeo periódico, el job diario o /ingest-now — y una sola vez por partida: la ingesta tiene un lock y el dedup hace que correr todo junto no duplique nada.

Logs a Discord

Si LOG_CHANNEL_ID está seteado, los logs de nivel LOG_CHANNEL_LEVEL (WARNING por defecto) o superior se reenvían también a ese canal, además de la consola. Pensado para enterarte de errores (Riot caído, key vencida) sin mirar la terminal. Los errores de red contra Riot se reintentan con backoff antes de avisar.

El bot entra a un canal de voz, tira un audio corto y se va. Una sola reproducción a la vez en todo el bot, y cualquier audio se corta a los 20 s por las dudas. Necesita ffmpeg instalado y los permisos Connect y Speak.

Tres formas de que suene

• A pedido: /sonido [nombre] en tu canal de voz (vacío = uno al azar).
• Forzado (dev): /sonido-forzar [nombre] [canal] — en el canal que elijas, en el tuyo o en uno con gente al azar. Si hay otro sonando, espera su turno.
• Al azar: cada SOUNDS_CHECK_INTERVAL_MINUTES (5) el bot tira un dado con SOUNDS_CHANCE (15%). Si sale, dentro del horario activo y pasado el cooldown (SOUNDS_COOLDOWN_MINUTES, 45), elige un canal con al menos una persona (no cuenta el AFK) y un audio al azar. Se apaga con SOUNDS_ENABLED=false.

Cómo se cargan

• /sonido-add (dev): permanente. mp3, ogg o wav, hasta 2 MB.
• /canjear-sonido (rol puntos): temporal, pagado con puntos. Ver abajo.
• Los audios viven en SOUNDS_DIR, fuera de git. Dueño y vencimiento de los canjeados quedan en SOUNDS_DIR/_meta.json; un sonido sin entrada ahí es permanente.

ffmpeg.org ↗

Los miembros con POINTS_ROLE_ID juntan puntos y los canjean. Sin ese rol configurado, el módulo no se carga.

Cómo se ganan

• Voz: 1 punto cada 5 minutos a cada miembro con el rol que esté en un canal de voz con al menos otro humano (no cuenta el canal AFK ni estar ensordecido). Tope: 60 por día.
• LoL: 5 por cada partida nueva que se guarda y 5 más si la ganaste. El dedup de la ingesta garantiza que cada partida se paga una sola vez.
• A mano: un dev puede sumar o restar con /puntos-dar.

Canje: un sonido propio

/canjear-sonido <nombre> <audio> cuesta 100 puntos: el audio puede durar hasta 8 s, queda cargado 7 días y se borra solo al vencer. Máximo 1 activo por persona (lo podés borrar antes con /sonido-del). El bot mide la duración con ffprobe y recién cobra si el audio pasa el chequeo, y avisa en el canal que canjeaste. Todos los números se cambian por variables de entorno.

Local

python run.py directo, o .\scripts\run_bot.ps1 [-Environment production], que abre consola visible y espeja todo a logs\<ambiente>\. No levantes dos instancias contra el mismo ambiente/server: te responderían los comandos dos veces.

Server Linux (systemd)

El repo trae deploy/bogabot.service. El setup es una vez: clonar, venv + pip install -r requirements.txt, instalar ffmpeg, copiar el .env.production por scp (con permisos 600), instalar el service y systemctl enable --now bogabot. El estado (puntos, key de Riot, reinicio del ranking troll) vive en data/, fuera de 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 # logs en vivo

Para actualizar: git pull + pip install si cambió requirements.txt + systemctl restart bogabot. Cambiar la key de Riot no requiere deploy: /riot-key desde Discord. El repo trae además un workflow de GitHub Actions que despliega cada push a main que pasa los tests, pensado para cuando haya VPS.

• Alcance: beta con el grupo. Módulos de LoL (ranking y trolls), sonidos, puntos y ayuda. Sin funciones de IA todavía — están en el backlog como cog aparte.
• Storage: hoy es Discord (mensajes JSON en un canal privado + índice en memoria). Es O(n) mensajes; migrar a una DB real es una clase nueva en storage/ y una línea en bot.py. Puntos y sonidos canjeados van a archivos JSON en data/ y sounds/.
• Colas: el ranking diario y semanal cuenta solo Ranked (Solo/Duo y Flex); el recap “Trolls y Pros”, solo Flex. El detector de trolls y los puntos miran todas las colas.
• Región: decisión tomada para LAS (la2 / americas); configurable para otras.
• Tests: python -m pytest — scoring, dedup, mapper de match-v5 con timeline, reglas troll, config, ranking troll, ingesta y ruteo de avisos.

Bugs, ideas y pedidos → issues del repo.