ClashRoyaleBuildABot: a computer-vision state generator for a game

The project's own terms forbid running it live

The most important paragraph in this repository is a legal disclaimer, and it does not leave much room. The software is described as intended solely for educational and research purposes, and as not affiliated with, authorized by, or endorsed by Supercell Oy. It then states that using the bot in connection with the Clash Royale game is strictly prohibited, that such use may violate the publisher's terms of service, and that it may result in penalties including account suspension or termination. The disclaimer also concedes the point that is hardest to argue around: while the bot primarily affects only the account it runs on, it may harm the competitive gameplay experience of other players, and by using it the user accepts sole responsibility. That is a candid statement of the harm, written by the people who built the thing. Any evaluation of this project has to start there, because the gap between what the code can do and what its authors permit is the defining feature of the repository.

Every dependency is pinned, and inference is an extra

The packaging is unusually exacting. All fifteen runtime dependencies are pinned to specific versions rather than ranges, including the numerical stack, the imaging stack, the video library, and the user interface toolkit. The interpreter requirement is equally narrow, pinned to a single minor series of Python 3.12, which means an existing environment will not be reused but rebuilt. The more interesting structural choice is how inference is packaged. The base dependency set contains no inference runtime at all. Instead there are two optional extras, one installing a CPU build of the ONNX runtime and one installing the GPU build at a matching version. So a user chooses their acceleration path explicitly at install time rather than inheriting whichever runtime happens to be present, which avoids the common failure where a CPU build silently shadows a GPU one. Developer tooling sits in a third extra, with the formatter, linter, and type checker, and the linter is configured to a seventy-nine column line length with a specific rule set selected.

The state generator reads frames and predicts units

How the system perceives the game is inferable from the libraries rather than from a description, since the readme's feature section is effectively empty. A video decoding library plus OpenCV plus Pillow is a frame-reading stack, which is what you need to turn an emulator window into images. The unit detection model runs as ONNX, which is why both CPU and GPU runtimes are offered as extras, and a YOLOv8 model for units appears in the release history for version 1.2.0, along with additional data. The next release, version 1.3, added synthetic data to unit training, which is the more interesting of the two changes: it means the detection pipeline can be improved without collecting more labelled gameplay, which is the practical bottleneck for any object detector applied to a screen. The inference result then feeds a control loop. Supporting libraries point at the shape of the state: a pair of serialization libraries for structured state, a linear algebra library and a scientific library for the maths, and a progress library for the long-running passes. The remainder fills in the surrounding work, with a logging library, a terminal formatting library that suggests readable console output during long detection runs, a configuration parser, an HTTP client, and a C++ binding tool, which implies at least one compiled extension rather than a pure-Python pipeline.

The current features section lists nothing

There is a section of the readme headed current features, and it contains no features. What it actually says is that the bot has a set of functionalities designed for educational and research purposes, and that the list will be updated soon because the bot has expanded significantly. That is an honest admission of documentation debt rather than a marketing claim, but it has a practical consequence: anyone assessing the project has to reconstruct the capability set from the issue backlog and the dependency list. The backlog is itself informative, because the nine tracked items are specific. They include improving error handling, opening chests, a tutorial for using the bot on a phone, surfacing unit detection counts in the interface, swapping decks from the interface, enhancing synthetic data generation, fixing the hit-point detector, adding ignore regions to the detector, and developing a new tracking algorithm. Read in order, that list describes a project whose detection accuracy and interface are the weak points, which is consistent with the dependency choices.

Keyboard capture and a Qt interface put it on the desktop

Two dependencies and one repository file define how this thing is used rather than built. A keyboard capture library appears in the base requirements, which is how the bot sends its actions to whatever window has focus, and a Qt interface toolkit is also a base requirement, so there is a graphical front end rather than a terminal-only tool. That combination explains two of the backlog items, since a graphical interface is exactly what you would want for picking decks or reading detection counts, and it also explains why packaging matters here. Because actions are delivered as keyboard events to a focused window and the front end is graphical, this is inherently a program that has to sit on a desktop rather than something you could schedule on a remote machine. The repository root holds a file named after the project with a spec extension, which is the build configuration for packaging a Python program into a standalone executable." There is also a top-level directory dedicated to error handling, sitting alongside the main entry script and the package directory, which suggests error handling was given its own boundary rather than being scattered through the code, and matches the top item on the backlog.

Three wiki guides, with an emulator in front

The install path is the clearest signal that this is not a library you add to something. Setup is documented as three separate guides that must be done in order. The first is an emulator setup guide, which comes before any Python work at all, because the state generator needs something to read frames from. The second covers uv and Git, establishing the toolchain and version control. The third is the bot installation guide. Putting the emulator first is the detail that matters, because it means the prerequisite is a full mobile game environment running on the desktop, and every subsequent step depends on it. The choice of uv as the package manager is visible in the repository, which carries a lock file alongside the project configuration, and that pairing is what makes the exact dependency pins reproducible rather than merely stated. Support is routed to a Discord server rather than to the issue tracker, and the readme asks for bug reports there.

Releases stopped in 2024 while commits continued

The release history and the commit history have drifted apart, which is worth noting before drawing conclusions about the project's state. There are three tagged releases. The first added a YOLOv8 model for units along with more data, the second fixed an ONNX bug and a Pillow bug, and the third added synthetic data to unit training. Those landed in early 2023, late 2023, and mid 2024 respectively. After that the releases stop, while the branch itself continued to receive commits, with the most recent push dated 24 July 2026. A related inconsistency sits in the project configuration, where the version field still reads a pre-release-looking value rather than tracking the tagged releases. Taken together this says the tagged releases are not a reliable guide to current code, so anyone reproducing a published setup should pin to a commit rather than to a tag, and should expect the readme's own characterisations of the bot to lag behind the implementation. The repository itself is MIT licensed, carries a contributors file and a pre-commit configuration, and follows the all-contributors specification, with an explicit request that anyone who develops it further acknowledges the original project and keeps the corresponding credits.

Editorial conclusion

ClashRoyaleBuildABot suits someone studying state detection, screen reading, and control loops as research, since the decoding, inference, and interface layers are separable and the dependency pins make the environment reproducible. It is a poor fit for anyone intending to run it against the live game, because the project's own documentation prohibits exactly that and warns of account suspension, and because doing so degrades matches for real opponents. Before spending time on it, read the disclaimer the project puts near the top, and if your interest is the machine learning rather than the game, the unit detection model and the synthetic data path are the parts worth isolating.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Pbatch/ClashRoyaleBuildABot on GitHub
4. README
5. Releases