A competitive companion tool for Pokémon Champions (2026). Built for players who want real team analysis, rival tracking, and set optimization — all offline, all local.
- Search and add any Pokémon to your team of 6, with drag-and-drop reordering
- Synergy analysis in a background thread as you build: strengths, type weaknesses, critical problems, pairs, items and speed tiers
- Natures and stat points applied for real — both to the numbers and the advice
- Undo/redo (Ctrl+Z / Ctrl+Shift+Z), shortcut help on F1, and preferences that survive a restart (size, format, tab)
- Showdown / Pokepaste import and export
- Mega evolutions: 75 forms with their own types, stats, abilities, sprites and stone. The ones that split into X and Y (Charizard, Raichu) get their own set each
- Every one-on-one against the 235 sets of the format, both ways round
- Three plays that cost a turn are modelled for both sides: putting a status on, boosting stats, and retyping the opponent (Soak)
- Sleep counts too — it is the most carried status in the rotation (36 sets in singles). It does not chip away at HP, it takes turns away
- Abilities that change accuracy are counted: No Guard (both ways — nobody misses, in either direction) and Compound Eyes. Machamp's Dynamic Punch is an 85.9%-usage move that never misses, and it was being scored as a coin flip
- Weather charges both sides: sand chips, snow raises Ice defence
- Doubles is a different format, not another rival table: spread moves hit 25% softer per target, Protect and Fake Out deny turns, and a separate team report covers what a one-on-one grid cannot show — speed control, redirection, friendly fire and abilities that work on both opponents
- Log opponent usernames and their revealed Pokémon data
- Moves, items and abilities seen, consolidated per rival across battles
- Separate record per format: a rival does not run the same set in singles and doubles
- Record wins and losses with opponent and format
- Winrate split by format — a global 60% can be 75% singles and 40% doubles, and the combined number does not tell you which one to work on
- Capture loop with a per-session backend:
spectacleon Wayland,msson X11 - Screen classification and OCR, published on an event bus
- Pick the monitor or a manual region from the header (⛶), with a "test capture" button that tells you what came back. The choice survives a restart
- Not yet measured against the real game. The circuit is closed and tested, but how well the OCR reads names depends on resolution, scaling and the chosen region
- Python 3.10+ (
x | Noneannotations are evaluated at runtime) - Linux / macOS / Windows
- For the overlay and screen reading: the system
tesseractbinary (dnf install tesseract/apt install tesseract-ocr)
git clone https://github.com/yourusername/rivalscope.git
cd rivalscope
pip install -r requirements.txt
python3 main.pyOnly PySide6 is needed to open the team builder. OpenCV, numpy, Pillow,
pytesseract and mss are loaded lazily and only by the overlay.
Two databases, deliberately separate:
| Path | Contents | |
|---|---|---|
| Catalogue | data/rivalscope.db |
The 315 Pokémon. Versioned, ships with the repo, same for everyone |
| Yours | ~/.local/share/rivalscope/usuario.db |
Saved team, rivals, battle log |
Your data used to live inside the versioned file, so saving a team dirtied the
repository and a git checkout could wipe it. Anything already stored there is
migrated on first run. RIVALSCOPE_USER_DB and RIVALSCOPE_DB redirect each.
python3 -m unittest discover -s tests -t . # 449 tests
python3 -m compileall -q core ui_qt tests scripts
ruff check core ui_qt scripts tests main.py # config in ruff.toml
QT_QPA_PLATFORM=offscreen python3 main.py # headless startThe -t . matters: without it the test package's __init__.py never runs and
the databases are not redirected to a temporary copy.
CI runs all of the above on every push, on Python 3.10 and 3.13, plus two checks
that only a clean machine catches: that the test run leaves data/rivalscope.db
byte-for-byte identical, and that the app starts without the overlay
dependencies installed. Both of those broke silently in the past.
- Measure the overlay against the real game — accuracy of the OCR and of
detect_screen, and whether the default region (primary monitor) is right - Confusion, but only the free case. Measured and decided against for the dedicated one: confusing costs a full turn and denies about 0.83 of one, so it is a losing play the engine would reject anyway. Moves that confuse while dealing damage (Dynamic Punch, Hurricane) get it for free, and that part is still uncounted
- Python 3.10+
- PySide6 / Qt6 (UI) — the migration from CustomTkinter is complete
- SQLite (local — no server, no account)
- Local CSVs for meta data (470 files, Singles and Doubles)
- OpenCV, numpy, Pillow and pytesseract — only for the overlay and screen reading; the team builder starts without them
No network calls at runtime: all data is local. The scripts in scripts/ do use
requests, but only to repopulate the database on demand.
Project state, what works and what does not, lives in STATE.md. Architecture and conventions live in AGENTS.md.
Currently tracking: Regulation M-B — Season M-4 Active: July 7 – August 4, 2026
Copyright (c) 2026 Hugo Herrera. All rights reserved.
This repository is published for reference and evaluation purposes only. No license to use, copy, modify or redistribute the code is granted. See COPYRIGHT.md for details.
Pokémon and all related names, trademarks and game data are property of Nintendo, Creatures Inc. and GAME FREAK Inc. This project is not affiliated with, sponsored or endorsed by them.