A cricket simulation bot for Discord
Ball-by-ball match engine · multi-format tournaments · draft mode · player careers

An actual match summary rendered by the bot (5-day Test, fully simulated)

CricVerse simulates cricket at the per-ball level - every delivery is a contest between a batter and a bowler, shaped by pitch, weather, ball age, match situation, and player ratings. It runs T20, ODI, and Test matches (including day-night pink-ball Tests), full tournaments, a knowledge-based draft mode, and a persistent player-career layer - all inside Discord, with broadcast-style scorecards rendered as images.

Everything is playable both interactively (pick your delivery and shot each ball) or instantly simulated.

Match engine

• Three formats: T20, ODI, and 5-day Tests with sessions, declarations, follow-ons, and new/old ball dynamics.
• Day-night pink-ball Tests: the ball swings under lights and the twilight session is a genuine danger period for pace.
• Conditions matter: 15 pitch types, ~10 weather states, pitch deterioration, ball-age swing and reverse, Super Overs for ties.
• Calibrated, not random: outcome weights are Monte-Carlo tuned so skill decides matches - no freak 250s or 30-all-out collapses between equal sides.

Tournaments & leagues

• Round robin, T20 World Cup (groups > Super 8 > knockouts), IPL-style seasons, and a bespoke 14-team Akatsuki Cricket League with Top-6 playoffs.
• The Dominators Super League: a recurring home/away ODI league with fixed home venues, season archives, player awards, and multi-season history.
• An open Elo-style rating ladder with trades and a boost economy.
• Auto-generated fixtures, live points tables with NRR, knockout brackets, per-player tournament leaderboards, and image-rendered standings.

Draft mode

• A blind, knowledge-based draft: ratings are hidden, each round asks a question ("name a leg-spinner", "name a finisher keeper") and captains build a balanced XI from memory before the match is played out. 1v1 or vs AI.

Career mode

• Create a player, earn coins from solo scenarios and club matches, upgrade attributes, climb tiers (Bronze through Diamond) with matching Discord roles.

Player system

• 1,200+ players with batting/bowling ratings, roles, and playing-style archetypes, plus per-server rating overrides.

Python 3.11+, discord.py 2.x (slash + prefix commands), MongoDB via pymongo for persistence, Pillow for image rendering, and a small Flask server for uptime pings.

git clone https://github.com/TheJaiv/CricVerse.git
cd CricVerse
pip install -r requirements.txt
cp .env.example .env    # fill in DISCORD_TOKEN and MONGO_URI
python bot.py

New to Discord bots or MongoDB? SETUP.md walks through the whole thing step by step - creating the Discord application, a free MongoDB Atlas cluster, inviting the bot, loading the player database, and hosting.

Commands work as both slash (/command) and the cv prefix (cvt = tournament, cvd = draft).

bot.py         Discord client, commands, interactive flows, image rendering
engine/        Ball-by-ball simulation: t20, odi, test + test scorecard images
league/        Tournaments, rating ladder, stadiums, draft mode
career/        Career mode: progression, club matches, UI views
core/          MongoDB persistence, tiers/quotas, keep-alive server
data/          Player database (CSV), ratings dump, curated draft pool
assets/        Image templates and fonts for rendered scorecards
tools/         Calibration harnesses and offline test suites
archive/       Superseded engine versions kept for A/B comparison

The engines are tuned against Monte-Carlo harnesses in tools/ rather than eyeballed: sim_harness.py checks first-innings par scores, upset rates at various rating gaps, and wicket distributions across formats and conditions.

Offline flow tests exercise the real bot code headlessly - no Discord or database connection needed:

python3 tools/career_flow_test.py    # 170 checks
python3 tools/ipl_flow_test.py       # 79 checks incl. 300 fuzzed seasons
python3 tools/rating_league_test.py  # 21 checks

CricVerse is built with AI assistance - most of the code here was written by Claude Code, working from specs and reviews by me. The cricket knowledge, the design calls, and the decision about what "right" looks like are mine; a lot of the typing is not.

That is also why the section above exists. A simulation is the worst possible place to trust generated code on sight, because wrong output still looks like cricket - a bowling average of 12 or a par score 40 runs light reads as a plausible scorecard until you run a thousand of them and check the distribution. So nothing in the engine is accepted because it compiles. Outcome weights are Monte-Carlo tuned against real-world par scores and upset rates, and the flow tests drive the actual bot code end to end rather than mocking it. Those harnesses are the review layer, and they caught more than they should have needed to.

Worth stating plainly for anyone reading the code: the balance work, the format rules, and the calibration targets are deliberate choices, not defaults someone generated and shipped.

Want to run your own instance? SETUP.md has everything - fork or clone away. If you'd like a change in this repo, open a pull request rather than expecting direct access: main auto-deploys the live bot, so changes are only merged after they've been tested.

This is a non-commercial fan project. It is not affiliated with, endorsed by, or connected to the ICC, IPL, or any cricket board. Player names are used in a fictional simulation context and all ratings are fan-made. Scorecard template imagery belongs to its respective owners; if you're a rights holder and want something removed, open an issue.

MIT © Jaiv Patel (code only - see disclaimer above for assets)