Code your team's brain —player, tactics and coach— and compete in a deterministic simulator, on your machine or on the online platform. You write the logic; if you want, AI drives it.
git clone github.com/GoNNoTDa/PyLeaguePick your path: compete online with nothing to install, or clone the SDK and work locally. Both use the same deterministic engine.
Create your account, save your teams and play matches and leagues from the browser. The fastest way to start today.
Sign up freeClone the project (just Python 3.13, no dependencies), copy the template and compete on your machine.
You don't move players: you program how they decide. The engine referees the same for everyone and is deterministic — same seed, same match. AI decides at a slow pace; a deterministic layer runs every tick, so a model doesn't have to think 20 times per second.
Reads the score and the clock and sets the mentality: attack, balance or defend.
Positions the team: line height, width, pressing and attacking flank.
Decides every tick: move, pass or shoot. Fast and reactive.
A working prototype, no hype: this runs today.
Vector physics and clear rules. The same seed reproduces the exact match: fair, debuggable competitions.
Coach and tactics driven by an LLM — it already plays real matches on Gemini. Switch provider (Gemini, Claude, OpenAI, Amazon Bedrock, Ollama…) with an environment variable.
Every player manages their effort: sprinting and hard shots tire them out; with no fuel left they run and shoot worse. Another layer to program into your tactics.
Play all teams against each other, get a table with points and ELO, and an HTML report ready to share.
Possession, shots and shots on target, passes and accuracy, recoveries and distance. You know what to improve, not just the score.
Measure your team against several opponents over many seeds and get win-rate and averages. Compare changes with data, not hunches.
Third-party code runs in a subprocess with time limits and no network or disk: safe to compete against others' teams.
Tiki-taka, catenaccio, counter-attack, gegenpressing… templates ready to tune.
Every match plays back like a broadcast: pitch at ~60 fps, TV-style scoreboard, stats and AI commentary.
The engine uses only the standard library. The AI SDKs are optional. Copy the template and start in minutes.
You set four knobs —line, width, pressing and focus— as fixed values or as a function of the match. The engine turns them into positions.
from aicup.tactics import TacticalStrategy, progress, possession
def contraataque():
# Without the ball we drop back; on the recovery, we break.
def mandos(ctx):
defendiendo = possession(ctx) == "theirs" or progress(ctx) < 0.45
if defendiendo:
return {"line_height": 0.30, "pressing": 0.35}
return {"line_height": 0.74, "pressing": 0.50}
return TacticalStrategy("Contraataque", mandos)On top of the local SDK, there's a web platform: create your account, save your teams and play matches and leagues from the browser, with nothing to install. Each match runs isolated on the server and saves its replay.
Each team builds up ELO and a record from matches between registered teams. Climb the public leaderboard.
Competitions where anyone enters their team. Join with one click and the organizer runs it.
Your page with your teams, your best ELO, your record and your replays. Your track record, on display.
For every official match we store the exact code of each team (with its SHA-256), the seed and the engine version. Because the engine is deterministic, anyone can reproduce the match and verify the result — no trust required. In leagues, every fixture is audited one by one.
Generate a public link for any match to watch or audit it without an account. Download the code and the replay and check it yourself.
Build leagues from ready-made templates: metal divisions (iron to diamond), by country or continent, or fully custom. You pick the format —minutes, goal limit, sudden death— and every fixture inherits it.
Organizing? Generate a subscription link so anyone can enter their team —even if the league isn't open— and invite platform users directly by username.
Save several versions of your team, label them and choose which one plays each league without touching your default tactic. Your opponent's stays hidden unless they choose to show it. Every team has its own history and statistics.
PyLeague is an SDK: you copy a template that already plays well, make it yours and improve it by iterating. All local, deterministic and dependency-free. First time? Head to the Academy to learn how to code your team step by step, or check the full guide in the repository.
You only need Python 3.13 or later. The engine has no external dependencies.
Your team is a folder with three layers: coach, tactics and player. Start at the marked spots and change one thing at a time.
Play and watch it in the viewer with stats. Use sparring to measure your team against several opponents at once, and set up leagues with a table and ELO.
Coding stops being a solo exercise and becomes a tournament. Ideal for:
GDGs, meetups and associations: a challenge that hooks people and fuels several sessions.
A competitive format with a clear outcome: the best code wins, not the best pitch.
Universities and bootcamps: teach logic, AI and data structures by playing to win matches.
Technical team building and employer branding with an internal league in your brand.
The SDK is and will remain open source. If you want to run a competition for your event, we set it up turnkey for you.
Ideas on the roadmap. They're not here yet — we mention them because they show where the league is heading, not to sell you what doesn't exist.
Knockout format with a bracket, on top of round-robin leagues.
Per-role instructions the player executes, in addition to coach and tactics.
Throw-ins and corners, offside and fouls.
Describe your plan in natural language and it's turned into code.
An AI referee that reviews controversial plays.
Container/VM per match to open public execution at scale.
A virtual-football competition where you don't play with your legs but with code: you program each player's brain, the team's tactics and the coach's decisions in Python, and compete in a deterministic simulator.
No. Copy the included template —which already plays competitively— and improve one layer at a time. With basic Python you can start in minutes.
Yes. PyLeague is open source and you can use it, modify it and compete at no cost. We only offer optional services to organize custom tournaments.
No. The engine and the sample teams work without any API. AI is optional: if you want the coach or tactics to think with a language model, connect your favorite provider (Claude, OpenAI, Gemini, Groq, Mistral, DeepSeek or Ollama locally).
Yes. PyLeague fits hackathons, developer communities, education and events. Get in touch and we'll set up a custom competition.
On Windows, macOS and Linux. The engine only needs Python 3.13 or later and has no external dependencies.
Yes. On the online platform you create an account, save your teams and play matches and leagues from the browser. Each match runs isolated on the server and saves its replay, with a global ELO ranking, a public profile and open arenas where anyone competes.
Because every official match is reproducible: we store each team's exact code with its SHA-256, the seed and the engine version. Because the engine is deterministic, anyone can download everything and reproduce the match to verify the result is legitimate, with no need to trust anyone. In leagues, every fixture is audited one by one.
PyLeague brings together developers competing with code: a hard-to-reach audience, in a positive context —learning and winning—. Partner with a fair, verifiable league, and do it while you're still among the first.
You reach technical profiles —developers and students— while they build and compete. Perfect for talent acquisition and employer branding.
Your brand in the broadcast-style viewer, on the pitch-side boards and in the simulation messages —and in every replay that gets shared.
The league for your community or university, a hackathon challenge or an internal company league. You choose the scope.
Every official match is auditable and reproducible: the code, the seed and the engine version are stored. A serious prize tournament to attach your brand to, with no reputational risk.
There are no sponsors yet: you can be the first. Prime placement and a close relationship for those who back it before anyone else.
Example: your boards pitch-side and in every match's viewer.
Create your account and compete online in minutes, or clone it and play locally. In basic mode it works with no API and no setup.
python play.py · python sparring.py · python league.py