A headless Clash Royale battle simulator built in Java, designed for reinforcement learning and AI research. Deterministic tick-based engine with data-driven cards, a LibGDX debug visualizer, and a Python Gymnasium integration via ZMQ bridge.
- Full combat: melee, ranged, AOE, chain lightning, scatter projectiles, charge, dash, hook, reflect, shields, death spawn, burst attacks
- Status effects: stun, slow, rage, freeze with multiplier-based stacking
- Level scaling: rarity-based iterative growth matching the original game's formulas
- Component-Entity-System: entities hold data, systems hold logic
- Community card data: >100 troops, spells, and buildings loaded from JSON with automatic reference resolution
Requirements: Java 17
# Build
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
./gradlew build
# Run tests
./gradlew :core:test :data:test
# Run debug visualizer
./gradlew :desktop:run
# Run gym bridge server (default port 9876)
./gradlew :gym-bridge:runmacOS: The visualizer needs
-XstartOnFirstThread. The Gradle task handles this; add it to VM options if running from an IDE.
Requirements: Python 3.10+, Java bridge server running
pip install -e python/
python python/examples/run_episodes.pyfrom crforge_gym import CRForgeEnv
env = CRForgeEnv()
obs, info = env.reset(seed=42)
while True:
action = env.action_space.sample()
obs, reward, terminated, truncated, info = env.step(action)
if terminated or truncated:
break
env.close()| Module | Description |
|---|---|
core |
Headless simulation engine -- entities, systems, match logic |
data |
Card/unit/projectile config loading from JSON into typed objects |
desktop |
LibGDX debug visualizer for watching and interacting with matches |
gym-bridge |
ZMQ server + Python Gymnasium environment for RL training |
core has no GUI dependencies. data depends on core. desktop and gym-bridge depend on
both.
| Document | Description |
|---|---|
| Simulation & Entities | Tick loop, entity lifecycle, entity types |
| Arena, Match & Economy | Arena layout, placement, win conditions, elixir, hand |
| Targeting, Combat & Abilities | Target locking, attack pipeline, 10 ability types |
| Card Data Schema | JSON schema, loading pipeline, reference resolution |
| Python Gymnasium Bridge | ZMQ transport, observation/action spaces, rewards |
See docs/architecture.md for the full documentation index.
| Tool | Description |
|---|---|
| Formation Visualizer | Tkinter app for viewing and editing multi-unit spawn formation offsets |
This project uses Google Java Format enforced via Spotless. Formatting is checked on build:
./gradlew spotlessApplyThis project was inspired by scholarlygaming's Clash Royale engine, the first somewhat complete open-source Clash Royale simulation engine.
This is an independent fan project created for educational and research purposes. It is not affiliated with, endorsed by, or associated with Supercell. "Clash Royale", "Supercell", and related names and imagery are trademarks of Supercell Oy. See NOTICE for full attribution.
Licensed under the Apache License 2.0.