royalegym 0.1.12__tar.gz

royalegym-0.1.12/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RoyaleGym contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

royalegym-0.1.12/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: royalegym
+Version: 0.1.12
+Summary: RoyaleGym: reinforcement-learning environments for Clash Royale, over the RoyaleSim battle engine
+License: MIT
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Requires-Dist: gymnasium<2.0,>=1.3
+Requires-Dist: pettingzoo<2.0,>=1.27
+Requires-Dist: msgspec>=0.19
+Provides-Extra: sim
+Requires-Dist: royalesim>=0.1.10; extra == "sim"
+Provides-Extra: learn
+Requires-Dist: royalelearn[torch]>=0.5.4; extra == "learn"
+Provides-Extra: viser
+Requires-Dist: royaleviser>=0.1.1; extra == "viser"
+Provides-Extra: imitate
+Requires-Dist: royaleimitate[replays]>=0.2.6; extra == "imitate"
+Provides-Extra: all
+Requires-Dist: royalesim>=0.1.10; extra == "all"
+Requires-Dist: royalelearn[torch]>=0.5.4; extra == "all"
+Requires-Dist: royaleviser[media]>=0.1.1; extra == "all"
+Requires-Dist: royaleimitate[replays]>=0.2.6; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: hypothesis>=6.100; extra == "dev"
+Requires-Dist: ruff>=0.16; extra == "dev"
+Provides-Extra: train
+Requires-Dist: sb3-contrib>=2.3; extra == "train"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material<10,>=9.7; extra == "docs"
+Requires-Dist: mkdocstrings[python]<2,>=1.0; extra == "docs"
+Dynamic: license-file

royalegym-0.1.12/README.md

@@ -0,0 +1,40 @@
+<p align="center"><img src="docs/site/pages/assets/royalegym-mark.png" width="128" alt="The RoyaleGym logo: a blue crown shield with a white dumbbell on it, outlined in gold"></p>
+
+<h1 align="center">RoyaleGym</h1>
+
+<p align="center"><a href="https://github.com/RoyaleGym/RoyaleGym/actions/workflows/suite.yml"><img alt="CI" src="https://github.com/RoyaleGym/RoyaleGym/actions/workflows/suite.yml/badge.svg"></a> <img alt="License" src="https://img.shields.io/github/license/RoyaleGym/RoyaleGym?style=flat-square&color=555"> <img alt="Python" src="https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-3776AB?style=flat-square&logo=python&logoColor=white"> <a href="https://royalegym.github.io/RoyaleGym/"><img alt="Docs" src="https://img.shields.io/badge/docs-royalegym.github.io-8957e5?style=flat-square&logo=readthedocs&logoColor=white"></a> <a href="https://discord.gg/4D2BS5JBHP"><img alt="Discord" src="https://img.shields.io/discord/1551699576304705647?style=flat-square&logo=discord&logoColor=white&label=discord&color=5865F2"></a> <img alt="Last commit" src="https://img.shields.io/github/last-commit/RoyaleGym/RoyaleGym?style=flat-square&color=555"></p>
+
+<p align="center"><img alt="APIs: Gymnasium and PettingZoo" src="https://img.shields.io/badge/APIs-Gymnasium%20%2B%20PettingZoo-0b7285?style=flat-square"> <img alt="Engine: Rust, deterministic" src="https://img.shields.io/badge/engine-Rust%2C%20deterministic-DEA584?style=flat-square&logo=rust&logoColor=white"> <img alt="Tick: 50 ms, 20 per second" src="https://img.shields.io/badge/tick-50%20ms%2C%2020%20per%20second-555?style=flat-square"> <img alt="Action space: 2305 moves" src="https://img.shields.io/badge/action%20space-2305%20moves-555?style=flat-square"></p>
+
+**Make a Clash Royale bot in Python.** You write what your bot should want; this gives it the
+battles, what it sees, the moves it can make, and a trainer.
+
+<p align="center"><img src="docs/site/pages/media/whole-battle.gif" width="100%" alt="A whole battle between two random players, shown in the viewer"></p>
+
+## Install
+
+    pip install "royalegym[all]" --find-links https://github.com/RoyaleGym/RoyaleGym/releases/expanded_assets/v0.1.11
+
+Python 3.12, 3.13 or 3.14. No Rust, no game files. On Windows with an NVIDIA card, install PyTorch first
+([Install](https://royalegym.github.io/RoyaleGym/install/), step 4).
+
+## Try it
+
+```python
+from royalegym import make_env, play_battle
+
+battle = play_battle(make_env(), blue="random", red="random", save_to="first_battle.msgpack")
+print("winner", battle.winner, "crowns", battle.crowns)
+```
+
+Save it as `first_battle.py` and run `python first_battle.py` (a few seconds). `winner` is 0 for
+Blue, 1 for Red and 2 for a draw. Then watch it: `royaleviser first_battle.msgpack`. To train a bot,
+follow the [Quick Start](https://royalegym.github.io/RoyaleGym/quickstart/): it gives you `quickstart.py`.
+
+## Next
+
+- Quick Start, guides and FAQ: [the docs](https://royalegym.github.io/RoyaleGym/)
+- How it works inside (Advanced): [architecture](https://royalegym.github.io/RoyaleGym/repos/royalegym/architecture/)
+- Questions: [Discord](https://discord.gg/4D2BS5JBHP)
+
+MIT licensed. See [LICENSE](LICENSE).

royalegym-0.1.12/pyproject.toml

@@ -0,0 +1,100 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "royalegym"
+version = "0.1.12"
+description = "RoyaleGym: reinforcement-learning environments for Clash Royale, over the RoyaleSim battle engine"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+dependencies = [
+    "numpy>=2.0",
+    "gymnasium>=1.3,<2.0",
+    "pettingzoo>=1.27,<2.0",
+    "msgspec>=0.19",
+]
+
+[project.optional-dependencies]
+# One install line for every piece: pip install "royalegym[all]".
+# The engine (a prebuilt wheel; it carries its own data). The package imports without it
+# (MockEngine is the pure-Python reference), and RustEngine() and make_env() say how to
+# install it.
+sim = ["royalesim>=0.1.10"]
+# The learner, with PyTorch, which trains on a CPU.
+learn = ["royalelearn[torch]>=0.5.4"]
+# The viewer: watch a battle live or from a saved file.
+viser = ["royaleviser>=0.1.1"]
+# Imitation from replays.
+imitate = ["royaleimitate[replays]>=0.2.6"]
+# Every piece names a minimum, so `pip install --upgrade "royalegym[all]"` moves each one
+# (pip upgrades a dependency only when a requirement forces it).
+all = [
+    "royalesim>=0.1.10",
+    "royalelearn[torch]>=0.5.4",
+    "royaleviser[media]>=0.1.1",
+    "royaleimitate[replays]>=0.2.6",
+]
+dev = [
+    "pytest>=8.0",
+    "hypothesis>=6.100",
+    "ruff>=0.16",
+]
+train = [
+    "sb3-contrib>=2.3",
+]
+# The documentation site, built from docs/site with `mkdocs serve` or `mkdocs build`.
+docs = [
+    "mkdocs-material>=9.7,<10",
+    "mkdocstrings[python]>=1.0,<2",
+]
+
+[tool.setuptools]
+packages = ["royalegym"]
+
+[tool.setuptools.package-data]
+# PEP 561: type checkers read an installed package's hints only when it ships this marker.
+royalegym = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+pythonpath = ["."]
+addopts = "-ra --strict-markers"
+markers = ["slow: long-running rollouts"]
+filterwarnings = [
+    # pettingzoo's api test warns through gymnasium's logger on purpose for some checks
+    "ignore::DeprecationWarning:pettingzoo.*",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["royalegym", "tests", "examples"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF", "NPY", "PT"]
+ignore = [
+    "RUF001", "RUF002", "RUF003",  # ambiguous unicode in comments/docstrings
+    "SIM108",                       # ternaries are not always clearer
+]
+
+[tool.ruff.lint.per-file-ignores]
+# An example unpacks the whole five-tuple a step returns even when it only reads the
+# first entry, because seeing the shape IS what the example is for. Shortening it to
+# `obs, *_ = env.step(...)` would lint better and teach worse.
+"examples/*.py" = ["RUF059"]
+# The quickstart imports its config objects in groups by what they do (the env, what the
+# bot sees and does, what it is paid for, when a battle ends), so a reader sees which piece
+# is which. One sorted block would teach the list and lose the grouping.
+"examples/quickstart.py" = ["RUF059", "I001"]
+# A VENDORED copy, kept byte-identical to the original in the cross-repo harness so the
+# copies in the four public repos can be diffed against each other and against it. Every
+# public repo carries its own, because a guard that lives only in the private repo cannot
+# run for an outside contributor, who is the reader it protects. Reformatting it to this
+# repo's line length would make that diff noisy for no behaviour change, so the line
+# length is waived here and nothing else is.
+"tests/_shell_fences.py" = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["royalegym", "royalesim"]

royalegym-0.1.12/royalegym/__init__.py

@@ -0,0 +1,238 @@
+"""royalegym -- RL environments over a deterministic Clash Royale engine (RoyaleSim).
+
+Components (each an ABC with swappable implementations):
+    ObsBuilder        obs.py           SpatialObsBuilder, EntityListObsBuilder
+    ActionParser      action.py        TileActionParser (Discrete 2305, + ability buttons
+                                       when asked), HalfTileActionParser
+    RewardFunction    reward.py        WinLoss, Crown, TowerHP, ElixirTrade, ElixirLeak, Combined;
+                                       IllegalAction and PlacementDepth ship unused, as templates
+    DoneCondition     done_condition.py  GameOver, FirstCrown (terminations); StepLimit,
+                                         TickLimit (truncations); Any, All (either role)
+    StateMutator      state_mutator.py   Default, MidGame, ScriptedBoard, Snapshot, Weighted
+
+A DoneCondition is used in one of two roles, termination (the outcome is decided)
+or truncation (the episode is cut); TerminationCondition and TruncationCondition
+are the role-declaring subclasses, and the envs take termination_cond and
+truncation_cond.
+
+Environments (env.py): ClashParallelEnv (PettingZoo), ClashGymEnv (Gymnasium),
+ClashSelfPlayVecEnv (vectorised self-play). Engine contract: protocol.Engine;
+MockEngine is the pure-Python reference implementation; RustEngine
+(rust_engine.py) drives the compiled Rust core through the same protocol.
+
+Opponents: selfplay.py has the trivial two (noop, random); opponents.py adds four
+scripted strategies and ``ladder()``, whose ordering is measured rather than assumed.
+
+Comparing bots: evaluate.py plays two Opponents head to head on both seats and
+reports a win rate with a Wilson interval, so "A is better" is a claim with an error
+bar rather than a percentage. selfplay.py's OpponentPool keeps Elo across many such
+results.
+
+Replays: replay.py records and re-verifies traces; render.py turns one into a
+self-contained HTML viewer (``python -m royalegym.render trace.msgpack -o out.html``).
+render is deliberately NOT imported here: importing it from the package would make
+``python -m royalegym.render`` load the module twice (runpy's RuntimeWarning).
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .action import ActionParser, HalfTileActionParser, PlacementOracle, TileActionParser
+from .done_condition import (
+    AllCondition,
+    AnyCondition,
+    DoneCondition,
+    FirstCrownCondition,
+    GameOverCondition,
+    StepLimitCondition,
+    TerminalCondition,
+    TerminationCondition,
+    TickLimitCondition,
+    TruncationCondition,
+)
+from .env import (
+    STARTER_DECK,
+    ClashGymEnv,
+    ClashParallelEnv,
+    ClashSelfPlayVecEnv,
+    make_env,
+    make_gym_vec_env,
+)
+from .evaluate import Battle, MatchResult, SeatResult, evaluate, play_battle
+from .mock_engine import MockEngine
+from .obs import (
+    EntityListObsBuilder,
+    MatchClock,
+    MatchMemory,
+    ObsBuilder,
+    Reveal,
+    SpatialObsBuilder,
+    Variability,
+    fair_fields,
+    measure_variability,
+)
+from .opponents import (
+    DefendOpponent,
+    FirstAffordableOpponent,
+    PatientOpponent,
+    PushOpponent,
+    ladder,
+)
+from .protocol import Engine, EntityKind, MatchSetup, TowerSlot, Winner, to_own
+from .replay import ReplayRecorder, load_trace, save_trace, verify_trace
+from .reward import (
+    CombinedReward,
+    CrownReward,
+    ElixirLeakPenalty,
+    ElixirTradeReward,
+    IllegalActionPenalty,
+    PlacementDepthReward,
+    RewardFunction,
+    TowerHPReward,
+    WinLossReward,
+    default_reward,
+)
+
+# The Rust engine is optional: rust_engine.py imports without the compiled
+# extension and RustEngine() raises ImportError naming the build command.
+from .rust_engine import CORE_IMPORT_ERROR, RustEngine, core_available
+from .selfplay import (
+    CallableOpponent,
+    NoopOpponent,
+    OpponentPool,
+    RandomLegalOpponent,
+)
+from .state_mutator import (
+    DeckCurriculumStateMutator,
+    DefaultStateMutator,
+    DefaultStateSetter,
+    MidGameStateMutator,
+    MidGameStateSetter,
+    ScriptedBoardStateMutator,
+    ScriptedBoardStateSetter,
+    SnapshotStateMutator,
+    SnapshotStateSetter,
+    StateMutator,
+    StateSetter,
+    WeightedStateMutator,
+    WeightedStateSetter,
+    deck_ids,
+)
+
+#: ``gym.make`` ids. The plain one takes whatever engine you pass and defaults to the
+#: mock WITH A WARNING, because a default that decides which engine a result came from
+#: and does not say so is the one thing this package should never do. The other two name
+#: their engine, so a reader can tell from the id what a number means, and neither warns.
+GYM_ENV_ID = "royalegym/ClashRoyale-v0"
+GYM_MOCK_ENV_ID = "royalegym/ClashRoyaleMock-v0"
+GYM_RUST_ENV_ID = "royalegym/ClashRoyaleRust-v0"
+
+#: id -> entry point. Registered at import, as gymnasium expects.
+GYM_ENV_IDS = {
+    GYM_ENV_ID: "royalegym.env:ClashGymEnv",
+    GYM_MOCK_ENV_ID: "royalegym.env:mock_gym_env",
+    GYM_RUST_ENV_ID: "royalegym.env:rust_gym_env",
+}
+
+
+def _register() -> None:
+    import gymnasium
+
+    for env_id, entry_point in GYM_ENV_IDS.items():
+        if env_id not in gymnasium.registry:
+            gymnasium.register(id=env_id, entry_point=entry_point)
+
+
+_register()
+
+try:
+    __version__ = version("royalegym")
+except PackageNotFoundError:  # a source tree that was never installed
+    __version__ = "0+unknown"
+
+__all__ = [
+    "CORE_IMPORT_ERROR",
+    "GYM_ENV_ID",
+    "GYM_ENV_IDS",
+    "GYM_MOCK_ENV_ID",
+    "GYM_RUST_ENV_ID",
+    "STARTER_DECK",
+    "ActionParser",
+    "AllCondition",
+    "AnyCondition",
+    "Battle",
+    "CallableOpponent",
+    "ClashGymEnv",
+    "ClashParallelEnv",
+    "ClashSelfPlayVecEnv",
+    "CombinedReward",
+    "CrownReward",
+    "DeckCurriculumStateMutator",
+    "DefaultStateMutator",
+    "DefaultStateSetter",
+    "DefendOpponent",
+    "DoneCondition",
+    "ElixirLeakPenalty",
+    "ElixirTradeReward",
+    "Engine",
+    "EntityKind",
+    "EntityListObsBuilder",
+    "FirstAffordableOpponent",
+    "FirstCrownCondition",
+    "GameOverCondition",
+    "HalfTileActionParser",
+    "IllegalActionPenalty",
+    "MatchClock",
+    "MatchMemory",
+    "MatchResult",
+    "MatchSetup",
+    "MidGameStateMutator",
+    "MidGameStateSetter",
+    "MockEngine",
+    "NoopOpponent",
+    "ObsBuilder",
+    "OpponentPool",
+    "PatientOpponent",
+    "PlacementDepthReward",
+    "PlacementOracle",
+    "PushOpponent",
+    "RandomLegalOpponent",
+    "ReplayRecorder",
+    "Reveal",
+    "RewardFunction",
+    "RustEngine",
+    "ScriptedBoardStateMutator",
+    "ScriptedBoardStateSetter",
+    "SeatResult",
+    "SnapshotStateMutator",
+    "SnapshotStateSetter",
+    "SpatialObsBuilder",
+    "StateMutator",
+    "StateSetter",
+    "StepLimitCondition",
+    "TerminalCondition",
+    "TerminationCondition",
+    "TickLimitCondition",
+    "TileActionParser",
+    "TowerHPReward",
+    "TowerSlot",
+    "TruncationCondition",
+    "Variability",
+    "WeightedStateMutator",
+    "WeightedStateSetter",
+    "WinLossReward",
+    "Winner",
+    "core_available",
+    "deck_ids",
+    "default_reward",
+    "evaluate",
+    "fair_fields",
+    "ladder",
+    "load_trace",
+    "make_env",
+    "make_gym_vec_env",
+    "measure_variability",
+    "play_battle",
+    "save_trace",
+    "to_own",
+    "verify_trace",
+]