{"id":50316117,"url":"https://github.com/voonhous/crforge","last_synced_at":"2026-05-29T00:02:42.102Z","repository":{"id":345335023,"uuid":"1141017308","full_name":"voonhous/crforge","owner":"voonhous","description":"Headless Clash Royale battle simulator in Java for RL/AI training, with LibGDX debug visualizer","archived":false,"fork":false,"pushed_at":"2026-04-03T19:20:12.000Z","size":13945,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T21:36:49.876Z","etag":null,"topics":["ai-training","clash-royale","game-simulator","gymnasium","java","libgdx","reinforcement-learning"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/voonhous.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-24T05:01:48.000Z","updated_at":"2026-04-03T19:20:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/voonhous/crforge","commit_stats":null,"previous_names":["voonhous/crforge"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/voonhous/crforge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voonhous%2Fcrforge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voonhous%2Fcrforge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voonhous%2Fcrforge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voonhous%2Fcrforge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/voonhous","download_url":"https://codeload.github.com/voonhous/crforge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voonhous%2Fcrforge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33631000,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-training","clash-royale","game-simulator","gymnasium","java","libgdx","reinforcement-learning"],"created_at":"2026-05-29T00:02:37.333Z","updated_at":"2026-05-29T00:02:42.065Z","avatar_url":"https://github.com/voonhous.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# crforge\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![Build](https://github.com/voonhous/crforge/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/voonhous/crforge/actions/workflows/build-and-test.yml)\n[![Java 17](https://img.shields.io/badge/Java-17-orange.svg)](https://adoptium.net/)\n\nA headless Clash Royale battle simulator built in Java, designed for reinforcement learning and AI\nresearch. Deterministic tick-based engine with data-driven cards, a LibGDX debug visualizer,\nand a Python Gymnasium integration via ZMQ bridge.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/debug-visualizer.gif\" alt=\"Debug visualizer showing a simulated battle\" width=\"320\"\u003e\n\u003c/p\u003e\n\n## Features\n\n- **Full combat**: melee, ranged, AOE, chain lightning, scatter projectiles, charge, dash, hook, reflect, shields, death spawn, burst attacks\n- **Status effects**: stun, slow, rage, freeze with multiplier-based stacking\n- **Level scaling**: rarity-based iterative growth matching the original game's formulas\n- **Component-Entity-System**: entities hold data, systems hold logic\n- **Community card data**: \u003e100 troops, spells, and buildings loaded from JSON with automatic reference resolution\n\n## Quick Start\n\n**Requirements:** Java 17\n\n```bash\n# Build\nexport JAVA_HOME=$(/usr/libexec/java_home -v 17)\n./gradlew build\n\n# Run tests\n./gradlew :core:test :data:test\n\n# Run debug visualizer\n./gradlew :desktop:run\n\n# Run gym bridge server (default port 9876)\n./gradlew :gym-bridge:run\n\n# Run visualizer in AI mode (Python controls the game via ZMQ)\n./gradlew :desktop:run --args=\"--ai-port 9876\"\n```\n\n\u003e **macOS:** The visualizer needs `-XstartOnFirstThread`. The Gradle task handles this; add it to VM options if running from an IDE.\n\n### Python / RL Training\n\n**Requirements:** Python 3.10+, Java bridge server running\n\n```bash\npip install -e python/\npython python/examples/run_episodes.py\n```\n\n```python\nfrom crforge_gym import CRForgeEnv\n\nenv = CRForgeEnv()\nobs, info = env.reset(seed=42)\n\nwhile True:\n    action = env.action_space.sample()\n    obs, reward, terminated, truncated, info = env.step(action)\n    if terminated or truncated:\n        break\n\nenv.close()\n```\n\n## Modules\n\n| Module       | Description                                                       |\n|--------------|-------------------------------------------------------------------|\n| `core`       | Headless simulation engine -- entities, systems, match logic      |\n| `data`       | Card/unit/projectile config loading from JSON into typed objects  |\n| `desktop`    | LibGDX debug visualizer for watching and interacting with matches |\n| `gym-bridge` | ZMQ server + Python Gymnasium environment for RL training         |\n\n`core` has no GUI dependencies. `data` depends on `core`. `desktop` and `gym-bridge` depend on\nboth.\n\n## Docs\n\n| Document                                                   | Description                                              |\n|------------------------------------------------------------|----------------------------------------------------------|\n| [Simulation \u0026 Entities](docs/simulation.md)                | Tick loop, entity lifecycle, entity types                |\n| [Arena, Match \u0026 Economy](docs/arena-and-match.md)          | Arena layout, placement, win conditions, elixir, hand    |\n| [Targeting, Combat \u0026 Abilities](docs/combat.md)            | Target locking, attack pipeline, 10 ability types        |\n| [Card Data Schema](docs/schema.md)                         | JSON schema, loading pipeline, reference resolution      |\n| [Python Gymnasium Bridge](python/README.md)                | ZMQ transport, observation/action spaces, rewards        |\n\nSee [docs/architecture.md](docs/architecture.md) for the full documentation index.\n\n## Tools\n\n| Tool                                                | Description                                                            |\n|-----------------------------------------------------|------------------------------------------------------------------------|\n| [Formation Visualizer](tools/formation_visualizer/) | Tkinter app for viewing and editing multi-unit spawn formation offsets |\n\n## Code Style\n\nThis project uses [Google Java Format](https://github.com/google/google-java-format) enforced\nvia [Spotless](https://github.com/diffplug/spotless). Formatting is checked on build:\n\n```bash\n./gradlew spotlessApply\n```\n\n## Acknowledgements\n\nThis project was inspired by\n[scholarlygaming's Clash Royale engine](https://www.reddit.com/r/ClashRoyale/comments/f21isa/effort_post_clash_royale_engine_development/),\nthe first somewhat complete open-source Clash Royale simulation engine.\n\n## Disclaimer\n\nThis is an independent fan project created for educational and research purposes. It is **not**\naffiliated with, endorsed by, or associated with Supercell. \"Clash Royale\", \"Supercell\", and related\nnames and imagery are trademarks of Supercell Oy. See [NOTICE](NOTICE) for full attribution.\n\n## License\n\nLicensed under the [Apache License 2.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoonhous%2Fcrforge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoonhous%2Fcrforge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoonhous%2Fcrforge/lists"}