Bot de Discord

Comandos, permisos, alertas automáticas, puesta en marcha y tablas de VANTCALL, el bot de Discord de VANTS escrito en Python con discord.py.

VANTCALL es el bot de Discord de VANTS (en algunos README aparece como ORION). Consulta perfiles y rankings, ayuda a moderar, publica anuncios y avisa de torneos, eventos y resultados nuevos. Está escrito en Python con discord.py y usa la misma base de datos que la plataforma, descrita en el esquema.

Su código está en la carpeta bot/ de Vantsgames.

Esta página describe la versión de Vantsgames. vants-dev-launcher incluye una copia con la misma estructura y Vants-Proteger una versión anterior, sin /agente, supervisor ni puente del agente.

Cómo funciona

El bot mantiene una conexión permanente con Discord (gateway) y registra sus comandos solo en el servidor indicado en DISCORD_GUILD_ID. Al arrancar sincroniza los comandos y lanza cuatro tareas en segundo plano.

Tarea	Qué hace
Health check	Responde ok en GET / (puerto PORT, 8080 por defecto) para que el alojamiento compruebe que el bot sigue vivo.
Alertas	Cada 30 segundos publica los torneos, eventos y resultados ranked nuevos en el canal de cada categoría.
Supervisor	Reenvía al propietario, por mensaje directo, los eventos que captura la web, como errores y fallos de red.
Puente del agente	Entrega al propietario, por mensaje directo, los incidentes del agente y las respuestas a las órdenes que quedan en cola.

El bot no se despliega con el Worker de Cloudflare: necesita un alojamiento que lo mantenga encendido, por ejemplo Railway o Render.

Puesta en marcha

1. Prepara la aplicación en Discord

   En el portal de desarrolladores abre la aplicación del bot. Si no tienes token, usa Bot → Reset Token y guárdalo solo en las variables de entorno del alojamiento.

2. Invita el bot al servidor

   Concédele los permisos de la tabla siguiente. Cada comando de moderación solo funciona si el bot tiene el permiso que necesita.

3. Deja vacía la URL de interacciones

   El campo Interactions Endpoint URL debe quedar vacío: el bot recibe los comandos por gateway. Usa los intents por defecto, así que no necesitas activar ningún intent privilegiado.

4. Configura las variables y arranca

   Las variables de entorno y los comandos de arranque están en la sección Bot de Discord de Vantsgames.

Permiso de Discord	Para qué
View Channels, Send Messages, Embed Links	Responder y publicar alertas y anuncios
Read Message History	/actividad, /top y /clear
Kick Members	/kick
Ban Members	/ban
Moderate Members	/mute y /unmute
Manage Messages	/clear
Manage Roles	/lock y /unlock

No ejecutes bot/register_commands.py. Reemplaza todos los comandos del servidor por una lista antigua. El bot registra los suyos al arrancar.

Comandos

Todos son comandos de barra (/) registrados en el servidor de VANTS. La columna Quién indica quién puede ejecutarlos:

• Todos: cualquier miembro que vea el comando.
• Staff: administradores del servidor y miembros con un rol de staff, que el bot reconoce por el nombre del rol. Los demás reciben un mensaje de error que solo ven ellos.
• Administrador: solo quien tiene el permiso de administrador.

Puedes limitar cualquier comando a roles o canales concretos en Ajustes del servidor → Integraciones.

Perfil y cuenta

Comando	Quién	Qué hace
/perfil [usuario]	Todos	Perfil VANTS de un jugador: rango, puntos, número de torneos, país y cuentas de Riot y Steam vinculadas, con botones de enlace. La respuesta es pública. Si el usuario no tiene cuenta vinculada, devuelve un error privado.
/verificar	Todos	Indica, en privado, si tu Discord está vinculado a un jugador VANTS y con qué rol (administrador o jugador). Si no lo está, te pide vincularlo en la web.
/vincular riot handle	Todos	Guarda tu Riot ID como cuenta sin verificar. Tu Discord debe estar vinculado antes a una cuenta VANTS. La respuesta es privada.

El Riot ID debe tener el formato Nombre#TAG: un nombre de 3 a 16 caracteres sin espacios ni # y una etiqueta de 3 a 5 caracteres alfanuméricos. Si ese Riot ID ya está vinculado a otra cuenta, el comando falla.

/perfil muestra en el canal el Riot ID y el enlace de Steam del jugador consultado.

Valorant

Comando	Quién	Qué hace
/valorant ranking	Todos	Top 10 de la temporada activa (o de la más reciente, si no hay ninguna activa) con posición, nombre, rango, MMR, victorias y porcentaje de victorias. La respuesta es pública.
/valorant perfil [usuario]	Todos	Rango actual y MMR, posición, victorias y derrotas, partidas y región. La respuesta es privada.

Estadísticas e informes

Comando	Quién	Qué hace
/stats_servidor	Todos	Miembros de Discord, jugadores registrados, torneos, partidas ranked, canales y roles.
/stats_jugador [usuario]	Todos	Usuario, juego principal, región, rango, MMR y balance de victorias y derrotas.
/actividad [dias]	Todos	Mensajes totales y los 5 canales más activos del período (7 días por defecto).
/top [dias]	Todos	Los 10 miembros más activos del período (7 días por defecto).
/informe	Todos	Jugadores nuevos y partidas ranked de la semana, torneos activos y en curso, y top 5 ranked.
/resumen	Todos	Jugadores, torneos, partidas ranked, eventos próximos y temporada actual.

Las respuestas de estos comandos son públicas. /actividad y /top recorren el historial de los canales de texto que el bot puede leer, así que con períodos largos pueden tardar mucho.

Moderación

Comando	Quién	Qué hace
/warn usuario razon	Staff	Envía una advertencia por mensaje directo al usuario y publica un aviso en el canal. No guarda ningún historial.
/kick usuario razon	Staff	Expulsa al usuario del servidor.
/ban usuario razon [borrar_dias]	Staff	Banea al usuario y borra sus mensajes de los últimos borrar_dias días (de 0 a 7).
/mute usuario minutos razon	Staff	Silencia al usuario con un timeout de Discord durante los minutos indicados.
/unmute usuario	Staff	Quita el silencio.
/clear cantidad	Staff	Borra hasta 100 mensajes del canal actual.
/lock	Staff	Impide que @everyone escriba en el canal actual.
/unlock	Staff	Devuelve a @everyone el permiso de escribir por defecto del canal actual.

Las respuestas se publican en el canal, salvo la de /clear, que es privada. Si un comando de moderación no responde, comprueba que el rol del bot esté por encima del rol del usuario y que tenga el permiso correspondiente.

Comunidad

Comando	Quién	Qué hace
/anuncio titulo mensaje [imagen]	Staff	Publica un anuncio en el canal de anuncios. imagen es una URL opcional.
/evento_crear titulo tipo fecha [descripcion]	Staff	Crea un evento. tipo es texto libre; los valores previstos son torneo, evento y scrim. fecha usa el formato YYYY-MM-DD o YYYY-MM-DD HH:MM, en UTC.
/torneo_crear nombre formato fecha_inicio [max_participantes]	Staff	Crea un torneo con la inscripción abierta. formato es texto libre; los valores previstos son single_elimination, double_elimination y round_robin. fecha_inicio usa el formato YYYY-MM-DD, en UTC, y max_participantes vale 16 por defecto. Si no se puede crear (por ejemplo, porque ya existe un torneo con ese nombre), el bot lo avisa.
/recordatorio mensaje minutos	Staff	Publica el mensaje en el canal actual cuando pasan los minutos indicados. Si el bot se reinicia antes, el recordatorio se pierde.

Las confirmaciones de /anuncio, /evento_crear y /torneo_crear son privadas. Los eventos y torneos que se crean aquí disparan las alertas automáticas.

Configuración

Comando	Quién	Qué hace
/setup	Administrador	Registra los canales de anuncios, registros, ranked y staff que usan las alertas y publica el anuncio de lanzamiento del bot en el canal de anuncios, mencionando a todos. Solo rellena las categorías que aún no tienen canal. La respuesta es privada.

Los canales de /setup (en bot/main.py) y el de /anuncio (en bot/commands/comunidad.py) están fijados en el código para el servidor de VANTS. En otro servidor, cámbialos antes de usar esos comandos.

Agente

/agente controla el agente de VANTS (web, launcher, base de datos y CI). Todas sus respuestas son privadas.

Subcomando	Qué hace
/agente estado	Último ciclo del agente e incidentes abiertos.
/agente informe	Diagnóstico completo del agente.
/agente incidentes	Lista hasta 15 incidentes abiertos.
/agente resolver id_incidente	Marca un incidente como resuelto.
/agente comando texto	Envía una orden en texto libre al agente.

Si el servicio HTTP del agente está configurado, /agente comando recibe la respuesta al momento. Si no, la orden queda en cola, el agente la procesa en su próximo ciclo (hasta unos 30 minutos) y la respuesta llega por mensaje directo.

/agente actúa sobre la plataforma y está pensado para el propietario. Restringe su uso a personas de confianza en Ajustes del servidor → Integraciones.

Alertas automáticas

El bot publica por sí solo en el canal que corresponde a cada categoría. Cada 30 segundos registra lo nuevo en una cola y envía hasta 10 alertas pendientes.

Alerta	Canal	Cuándo se envía
Nuevo torneo	Anuncios	Se crea un torneo (solo se miran los creados en el último día).
Nuevo evento	Anuncios	Se crea un evento (solo se miran los creados en el último día).
Evento a punto de empezar	Anuncios	Falta una hora o menos para que empiece un evento.
Resultado ranked	Ranked	Termina una partida ranked (solo se miran las del último día).

• Cada elemento genera una sola alerta, aunque el bot lo vea en varios ciclos.
• Si un envío falla, el bot lo reintenta hasta 3 veces. Después la alerta queda como fallida y se puede reintentar desde la pestaña Alertas del panel de administración.
• Cada tipo de alerta se puede apagar desde ese panel.
• Los mensajes salen sin menciones: @everyone y @here se neutralizan en los textos.
• En cada ciclo el bot guarda también su latido, que el panel usa para mostrar si está conectado.

Los canales de cada categoría se leen de la tabla discord_channels, que rellena /setup.

Tablas que usa

Tabla	Uso
players, leaderboard (vista), seasons	Perfiles, ranking y temporadas
tournaments, tournament_entries, events	Torneos, inscripciones y eventos
ranked_matches	Partidas ranked
discord_channels, bot_alerts, bot_heartbeat, bot_settings	Canales, cola de alertas, latido e interruptores
agent_*	Órdenes, incidentes y memoria del agente

Además lee las cuentas de Riot, Steam y Discord vinculadas para /perfil, /verificar y /vincular. Las tablas del bot están descritas en Bot y eventos web.

Permisos y buenas prácticas

• El staff se reconoce por el nombre del rol. Crea esos roles solo para personas de confianza y limita quién puede gestionar roles en el servidor.
• /setup solo lo ejecutan administradores. Los comandos de moderación y de comunidad requieren ser staff.
• Si no quieres que todos los miembros usen las estadísticas, restríngelas a un canal desde Integraciones.
• Concede al bot solo los permisos de la tabla y colócalo por encima de los roles que deba moderar.
• Mantén el token fuera del repositorio y regéneralo con Reset Token si se filtra.

Más información

• Vantsgames: código del bot y del resto de la plataforma.
• Esquema de la base de datos: tablas del bot, de las alertas y del agente.
• Arquitectura: cómo encaja el bot con el resto de componentes.
• Seguridad: secretos, webhooks y buenas prácticas.