Tournaments

[karaktaka]

Feature: Tournament System

A generic, per-guild tournament system for organizing competitions of any kind (gaming, foosball, etc.) with bracket management, sign-ups, and result tracking.

---

Phase 1 — Single Elimination + Core

Tournament Lifecycle

1. Create — Admin creates a tournament with name, description, max participants, and format
2. Sign-up — Bot posts an embed; users react to sign up (similar to raidplaner pattern)
3. Start — Admin locks sign-ups, bracket is auto-generated (seeding: random or manual)
4. Play — Matches are announced; participants report results
5. Complete — Winner announced, final standings posted

Sign-Ups

• Reaction-based on a tournament embed
• Admins can set a max participant count
• Admins can manually add/remove participants
• Sign-up deadline (optional)

Match Reporting

• Participants can submit their match result via command (e.g., /tournament report <score>)
• Admins can override or correct any result
• Optional: require both players to confirm a result before it's accepted

Commands

• /tournament create <name> — Start tournament creation (admin)
• /tournament delete <name> — Delete a tournament (admin)
• /tournament start <name> — Lock sign-ups and generate bracket (admin)
• /tournament report <score> — Report match result (participant)
• /tournament override <match> <score> — Admin result override
• /tournament bracket <name> — View current bracket
• /tournament standings <name> — View standings/results

Bracket Display

• Text-based bracket embed or image generation
• Updates automatically as results come in

---

Phase 2 — Additional Formats

Double Elimination

• Winners and losers bracket
• Grand finals with bracket reset option

Swiss / Round-Robin

• Configurable number of rounds
• Point-based standings (win/loss/draw scoring configurable)
• Tiebreaker rules (Buchholz, head-to-head, etc.)

---

Phase 3 — Advanced Features

• Team tournaments — 2v2 or NvN team support
• Points integration — Award Discord Points (issue Discord Points #82) for participation and placement
• Recurring tournaments — Schedule weekly/monthly auto-created tournaments
• History — Past tournament results archive

---

Data Model

• Tournament — guild, name, description, format, status, max participants, created_by
• TournamentParticipant — tournament + user, seed, status
• TournamentMatch — tournament, round, match number, participant1, participant2, score, status
• No Alembic migration needed — new tables auto-create at startup

Technical Notes

• New cog in NerdyPy/modules/tournament.py
• Models in NerdyPy/models/tournament.py
• Bracket generation logic as a utility (separation of concerns from Discord UI)
• Uses @Cog.listener() for on_raw_reaction_add (sign-ups)
• Admin commands gated with @checks.has_permissions(administrator=True)