> ## Documentation Index > Fetch the complete documentation index at: https://vantsgg.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Documentación interna de VANTS, la plataforma de esports, escrita en español. Cubre siete repositorios de la organización de GitHub VANTSNET y dos de la cuenta feispla: el prototipo VANTSNET, que se llama igual que la organización, y vantsoport. > Empieza por /mapa-del-codigo para saber qué repositorio y qué carpeta tocar, y consulta /glosario para los términos propios como pt_, mm_, RR, VANTS-BUS o VANTCALL. > Cuando un componente existe en varios repositorios, estas páginas describen la versión de Vantsgames salvo que digan otra cosa. El esquema de la base de datos se versiona en VantsBasededatos. > La web y la API pública están en https://vants.vants.workers.dev. Rutas y respuestas: /referencia/api-publica. Tablas y estados: /referencia/esquema-base-de-datos. > No inventes rutas, tablas, comandos ni variables de entorno: si algo no aparece aquí, revisa el código del repositorio correspondiente. # 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](https://vantsgg.mintlify.site/referencia/esquema-base-de-datos.md). Su código está en la carpeta `bot/` de [Vantsgames](https://vantsgg.mintlify.site/repos/vantsgames.md). > [!NOTE] > > Esta página describe la versión de Vantsgames. [vants-dev-launcher](https://vantsgg.mintlify.site/repos/vants-dev-launcher.md) incluye una copia con la misma estructura y [Vants-Proteger](https://vantsgg.mintlify.site/repos/vants-proteger.md) 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. ```mermaid theme={null} flowchart LR D[Discord] <-->|gateway| B[Bot VANTCALL] B <--> N[(Neon Postgres)] B -->|alertas y anuncios| C[Canales del servidor] B -->|avisos| O[Mensaje directo al propietario] W[Web de VANTS] --> N A[Agente VANTS] --> N ``` | 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](https://discord.com/developers/applications) 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](https://vantsgg.mintlify.site/repos/vantsgames.md#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` | > [!WARNING] > > 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. > [!NOTE] > > `/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](#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. | > [!WARNING] > > 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. > [!WARNING] > > `/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](https://vantsgg.mintlify.site/referencia/esquema-base-de-datos.md#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](https://vantsgg.mintlify.site/repos/vantsgames.md): código del bot y del resto de la plataforma. * [Esquema de la base de datos](https://vantsgg.mintlify.site/referencia/esquema-base-de-datos.md): tablas del bot, de las alertas y del agente. * [Arquitectura](https://vantsgg.mintlify.site/arquitectura.md): cómo encaja el bot con el resto de componentes. * [Seguridad](https://vantsgg.mintlify.site/referencia/seguridad.md): secretos, webhooks y buenas prácticas. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.