Open Source Rise of Kingdoms Stats Management Tool. Track TOP X players in kingdom / alliance / honor leaderboard. Depending on what you scan the resulting spreadsheet will look different:
Kingdom rankings: Governor ID, Governor Name, Power, Kill Points, Ranged Points, T1-T5 Kills, Total Kills, T4+T5 Kills, Dead Troops, RSS Gathered, RSS Assistance, Helps and Alliance name.
Honor, alliance and seed rankings: Governor name and score only. Because the game doesn't guarantee name accuracy, a screenshot of the name is saved in addition.
This is a heavily modified version of the original tool from nikolakis1919.
There are two ways of using the scanner:
- Simple installation — download the released
.exe, no Python required. Instructions below. - Advanced installation — clone the source and run with Python. Instructions below.
- Config restructured: The single
config.jsonhas been replaced with aconfig/folder containing multiple files for global settings, scanner presets, and GUI config. Version 5 configs are not compatible. - Unified scanner: The individual
kingdom_scanner,alliance_scanner,honor_scanner, andseed_scannerentry points have been merged into a singlescanner_console.pyandscanner_ui.py. The CLI presents an interactive menu to select the scan type.
- Unified scanner
- More config options
- Options per scan type
- UI positions no longer hard coded → now in
config/internal/*.json
- Support for Acclaim
- New GUI with theme support
Click to expand
| Light Theme | Dark Theme |
|---|---|
 |
 |
Download the latest RoK Tracker.zip release. Extract it and:
- Download tessdata (trained data) → place into
deps/tessdata/ - Download ADB Platform Tools → place into
deps/platform-tools/ - Configure Bluestacks 5 (resolution 1600x900, DPI 450, ADB enabled) — see below
- Adjust default options in the config files
- Double-click the
.exeto run
Prerequisites: Bluestacks 5, Python 3.14+ (download) or uv (instructions), tessdata, ADB Platform Tools. On Windows, Build Tools for C++ may be required. Here is how to set it up with uv:
- Download the source code release
- Place tessdata and platform-tools into the
deps/folder (see Folder Structure) - Configure Bluestacks 5 — see below
- Install dependencies:
uv sync - Run the scanner:
uv run scanner_console.py— CLI (select scan type interactively)uv run scanner_ui.py— GUI (tabs for Kingdom and Rankings)
The config/ folder contains these files:
| File | Purpose |
|---|---|
config.json |
Global settings (Bluestacks instance name, ADB port, log paths) |
kingdom_defaults.json |
Default options for kingdom scans |
seed_defaults.json |
Default options for seed (quick) scans |
alliance_defaults.json |
Default options for alliance ranking scans |
honor_defaults.json |
Default options for honor ranking scans |
gui_config.json |
GUI settings (default theme) |
Only two directories need manual attention:
deps/
├── tessdata/
└── platform-tools/
Everything else (config/, _internal/, source scripts) is either downloaded from the release or generated automatically. Scan results go into scans_kingdom/, scans_alliance/, scans_honor/, scans_seed/. Intermediate screenshots go into temp_images/.
- Full kingdom ranking scan (all governors)
- Wrong kill detection: validates that kills match kill points; suspicious items are saved to
manual_review/withFprefix and a warning is logged - Kill reconstruction: option to try recovering wrong kill values; reconstructed items get
Rprefix inmanual_review/ - Inactive account detection: accounts that can't be clicked are skipped automatically; screenshots can optionally be saved to
inactives/ - Stats to scan can be selected (if only stats from 1st page are use 2nd and 3rd page will get skipped to make the scan faster)
- Full alliance ranking scan
- Full personal honor ranking scan
- Seed scan (from kingdom rankings)
- Names are approximate (game limitation); governor ID is not tracked
- Display tab: Resolution 1600x900, DPI Custom (450) (screenshot)
- Advanced tab: Android Debug Bridge — Enabled (screenshot)
By default, the scanner assumes ADB port 5555. To configure automatic port detection:
- Set
bluestacks_configinconfig/config.jsonto your Bluestacks config file location (usuallyC:\ProgramData\Bluestacks_nxt\bluestacks.conf) - Make sure the instance name in
config.jsonmatches your Bluestacks instance name — the scanner asks for it interactively - The scanner auto-detects the ADB port from the config file. If no
bluestacks.confexists, your instance likely always uses port 5555
Not every Bluestacks variant has a config, that is not a limitation of the scanner but the installed android or Bluestacks versions. However, in those cases it is very likely that the port 5555 is used.
- Your active character must be in Home Kingdom to scan only your kingdom (otherwise KvK players from other kingdoms are included)
- Start the scanner from the top of the relevant ranking page — don't scroll during the scan
- Kingdom scan only: Your rank must be lower than the number of players you want to scan (e.g., can't scan top 100 if you're ranked 85). Use an alt account
- Kingdom scan only: "Resume scan" starts from the governor currently visible on screen (the 4th one down)
- Game Language must be English — other languages break inactive governor detection
- Chinese characters may not render in CMD but are visible in the final export file
- You can do other things on your PC while scanning, but avoid copying text since the scanner uses the clipboard to read names
- Important: Always copy the scan
.xlsxfile when finished — on the next scan there is a (small) chance it gets overwritten
- Always use
\\or forward slashes/in the Bluestacks path fields in config files (raw\will cause aJSONDecodeError)
The best way to get help is on Discord — my username is cyrexxis (same as my GitHub username). I'm on the official RoK Server and the Chisgule server.
To get help faster, follow these rules:
- Send a message request explaining your problem
- Include your
scanner.logfile — "it doesn't work" without logs won't get answered - There's no guaranteed response time since this is a free-time project
GitHub Discussions is another option — others may benefit from your troubleshooting