GitHub

Referencia Técnica Completa

Esta referencia documenta la totalidad de funciones y clases del proyecto. Generada automáticamente a partir del análisis del código fuente.

Modelos de Datos (utils/db.py)

Estructuras de datos definidas con @dataclass para mapeo Objeto-Documento con MongoDB.

GuildConfig

Configuración específica por servidor.

@dataclass
class GuildConfig:
    guild_id: int
    category_id: Optional[int]
    bracket_channel_id: Optional[int]
    lobby_channel_id: Optional[int]
    bot_admin_channel_id: Optional[int]
    admin_roles: List[str] # Lista de IDs de roles
                        

Tournament

Entidad principal de torneo. Mantiene el estado, rondas y configuración del evento.

@dataclass
class Tournament:
    id: str                 # UUID corto (8 chars)
    name: str               # Nombre display
    guild_id: int          
    settings: Dict          # Config snapshot (Deprecated)
    status: str            # "open", "active", "finished"
    current_round: int     
    matches: List[List]    # [Ronda 1 Matches, Ronda 2 Matches...]
    created_at: datetime
    start_date: str        # String formateado
    max_teams: int
    min/max_members: int
    image_url: str
    winner_id: str
                        

Team

Entidad de Equipo.

@dataclass
class Team:
    id: str
    name: str
    members: List[int] # IDs de Discord
    leader_id: int
    tournament_id: str
                        

Clase DBManager

Clase estática en utils/db.py que encapsula todas las operaciones de base de datos (Motor/MongoDB).

create_tournament(data)

Inserta un nuevo documento de torneo en la colección `tournaments`.

get_tournament(tournament_id)

Busca un torneo por su ID único.

get_active_tournament(guild_id)

Retorna el primer torneo del servidor con estado "open" o "active".

update_tournament(id, update_data)

Realiza un update atómico `$set` en el torneo especificado.

create_team(data)

Inserta un nuevo equipo.

get_team(team_id)

Recupera un equipo por ID.

get_team_by_name(name, tournament_id)

Busca un equipo por nombre dentro de un torneo específico (para evitar duplicados).

get_team_by_member(user_id, tournament_id)

Busca si un usuario pertenece a algún equipo en el torneo actual.

get_teams(tournament_id)

Retorna lista de todos los equipos registrados en un torneo.

delete_team(team_id)

Elimina un equipo de la base de datos.

Utilidades Visuales (visual.py)

Motor de renderizado de Brackets usando Pillow.

generate_bracket_image (tourney, current_round, team_names, ...) -> bytes

función principal. Decide si renderizar un bracket simple o doble basado en el número de equipos (>16). Retorna buffer PNG.

draw_single_bracket_fixed

Renderiza brackets tradicionales de eliminación simple. Calcula la geometría dinámicamente para ajustar al canvas 16:9.

draw_double_bracket_fixed

Renderiza un bracket simétrico (izquierda/derecha) convergiendo al centro para torneos grandes (16/32/64 equipos).

draw_match_slot

Dibuja una "caja" de partido individual.
Maneja la lógica de colores: Amarillo (Campeón), Verde (Ganador Ronda), Gris (Pendiente/Perdedor).

Módulo Principal (cogs/tourney.py)

Helpers y Checks

get_embed(title, description, color, author)

Fábrica de Embeds estandarizados con footer y timestamp.

send_log(guild, tourney_id, title, desc, color)

Sistema centralizado de logging. Verifica configuración del servidor y envía embed al canal designado si procede.

is_admin(ctx) / admin_check(ctx)

Check personalizado. Permite ejecución si el usuario es Admin nativo de Discord O si tiene uno de los roles configurados en DB.

channel_check(ctx)

Restringe comandos a canales específicos (Lobby/Admin) si están configurados.

Comandos de Torneo

create_tourney(ctx, args)

Parsea string de argumentos separados por `|`. Valida integridad de datos (potencias de 2, ints).
Crea documento `Tournament` y lo guarda.

delete_tourney(ctx, tourney_id)

Elimina torneo en cascada (Torneo + Equipos + Configuraciones vinculadas).

start_tourney(ctx, tourney_id)

Inicia el torneo.

Cierra registros.
Genera estructura de matches inicial (Ronda 1) con algoritmo de Seeding/BYE.
Llama a process_round.

Gestión de Equipos

register_team(ctx, name, members)

Inicia proceso de registro. Valida restricciones. Crea PendingTeam y envía ConfirmRegistrationView por DM.

create_team_final(pending_id)

Callback ejecutado cuando todos confirman. Crea el equipo en DB y notifica.

invite_member(ctx, user)

Permite a líderes invitar gente post-creación si hay hueco. Usa ConfirmInviteView.

Lógica Core de Torneo

process_round(ctx, tourney)

Ejecutado al iniciar cada ronda.

Genera/Actualiza imagen Bracket.
Genera canales de texto privados para cada enfrentamiento no resuelto.
Gestiona permisos de canales.

set_winner_cmd(ctx, member)

Establece ganador de un match basado en un miembro.
Si todos los matches de la ronda tienen ganador -> llama a `advance_round`.

advance_round(ctx, tourney)

Avanza a la siguiente ronda.

Si es final -> Declara ganador, actualiza DB, genera bracket final (Oro).
Si no -> Genera cruces de siguiente ronda basándose en ganadores previos.
Llama recursivamente a `process_round`.

Comandos de Administración

show_settings(ctx)

Muestra configuración actual del guild (canales, roles).

set_[category/bracket/lobby/bot_admin/logs](ctx, id)

Familia de comandos para actualizar cada campo de `GuildConfig`.

roles_group (add/remove)

Gestiona la lista de roles permitidos para administrar el bot.

report_bug(ctx, description)

Envía embed al canal de bugs centralizado definido en config global.