godot-rl: Python training loops around a real Godot game
An Open Source package that allows video game creators, AI researchers and hobbyists the opportunity to learn complex behaviors for their Non Player Characters or agents
At a glance
- What is it?
- godot-rl bridges the Godot Engine and Python reinforcement learning, with wrappers for StableBaselines3, Sample Factory, Ray RLlib and CleanRL, a sensor suite and experimental ONNX export. It is MIT licensed and pre-1.0, and its packaging metadata carries a version that trails the released tag.
- Who is it for?
- Adopt godot-rl when your agent has to act in a rendered 2D or 3D world rather than an abstract environment, and start with the StableBaselines3 backend on Windows, since Sample Factory is not listed there, then move to ONNX export so the shipped game does not need a Python process. Do not adopt it for a non-game environment or if you need a stable API before version 1.0, since the gdrl entry point is deprecated for removal.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 83 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 1, 2026, and from our analysis. They are not legal advice.
Editorial analysis
A Python training loop around a real game
godot_rl, installed as `godot-rl`, is an interface between games created in the Godot Engine and machine learning algorithms running in Python. That one sentence is the whole value proposition, and everything else in the repository exists to make the two halves meet.
The mismatch it solves is real. Reinforcement learning libraries live in Python and expect an environment that exposes observations and actions in a standard shape. Game engines are rendering loops with a scene graph, physics, and sensors. Connecting them means writing a bridge that turns game state into tensors and actions back into input events, and doing that from scratch for each project is the boring work nobody wants.
The repository lists what it provides: the interface itself, wrappers for four reinforcement learning frameworks, support for memory-based agents with LSTM or attention based interfaces, support for both 2D and 3D games, and a suite of AI sensors to augment an agent's capacity to observe the game world.
The four wrappers matter because they are the frameworks people already use. StableBaselines3, Sample Factory, Ray RLLib and CleanRL, each with a dedicated advanced guide in `docs/` and example scripts in `examples/`. Being able to swap backends without rewriting your environment is the feature that makes this usable in research, where the algorithm of the month changes and the game should not.
The project is MIT licensed and says so in unusually blunt terms: no strings attached, no royalties, nothing. The AAAI-2022 Workshop paper is on arXiv at 2112.03636 for the design rationale.
Installing the library and fetching an example environment
The package is on PyPI and the install is one line. The README suggests creating a virtual environment with venv or Conda first if you are new to Python or not already using one.
pip install godot-rlThe training environments are not in this repository. They live in a separate one, `godot_rl_agents_examples`, and are fetched through a helper that reads from a hub.
gdrl.env_from_hub -r edbeeching/godot_rl_JumperHardThe README names BallChase, JumperHard and FlyBy as examples worth downloading, and you can take one or more.
On Linux and macOS the downloaded project may not be executable, because the repository arrives with file permissions that are not preserved.
chmod +x examples/godot_rl_JumperHard/bin/JumperHard.x86_64That `chmod` is not a detail. The training script launches the Godot binary as a subprocess, and if the executable bit is missing you get a permission error from the operating system rather than anything that names the real problem.
The first training run, with visualisation
Training is a Python script from the `examples/` directory. The quickstart uses the StableBaselines3 example because that backend supports Windows, Mac and Linux, and it passes three arguments worth understanding individually.
python examples/stable_baselines3_example.py --env_path=examples/godot_rl_JumperHard/bin/JumperHard.x86_64 --experiment_name=Experiment_01 --viz`--env_path` is the exported Godot binary, so the Python process is launching your game and talking to it. `--experiment_name` labels the run, which matters because a training session produces output you will want to distinguish from the next one. `--viz` opens the game window so you can watch the agent learn rather than staring at a reward curve.
There is also a shorter path that skips the export entirely. The README documents in-editor training, where you download the Godot 4 Game Engine in its .NET version, open the engine, import the JumperHard example from `examples/godot_rl_JumperHard`, and start training from inside the editor.
python examples/stable_baselines3_example.pyNote the .NET version requirement. That is a hard constraint for in-editor training and the .NET build is not the default download most people grab.
There is a deprecated form still in the README, `gdrl --env=gdrl --env_path=... --experiment_name=... --viz`, marked as deprecated usage with an entrypoint and to be removed in version 1.0.
Sample Factory is the backend without Windows
Four backends are supported and the README gives each one a platform line, which is the detail that decides your stack.
StableBaselines3 is listed for Windows, Mac and Linux, as is CleanRL, as is Ray rllib. SampleFactory is listed for Mac and Linux only.
That asymmetry matters because Sample Factory is the framework aimed at the highest-throughput training on many machines, so a team planning to scale out across Windows nodes loses its preferred backend with no substitute offered. The quickstart itself steers you toward StableBaselines3 for exactly this reason, stating that it supports Windows, Mac and Linux and suggesting you start there before moving to the advanced tutorials.
Each backend has a dedicated document, `ADV_STABLE_BASELINES_3.md`, `ADV_SAMPLE_FACTORY.md`, `ADV_CLEAN_RL.md` and `ADV_RLLIB.md`, and the repository ships matching example scripts: `sample_factory_example.py`, `clean_rl_example.py`, `rllib_example.py` alongside `rllib_config.yaml`, plus `stable_baselines3_hp_tuning.py` for hyperparameter tuning and an `sb3_imitation.py` script that pairs with the imitation learning tutorial.
That last pairing is worth noting. Most of the documentation is about reinforcement learning from a reward signal, and the imitation learning tutorial on Hugging Face is the route for a project where you already have demonstrations and want an agent that copies them.
Version skew and a metadata error worth knowing about
Two details in the packaging metadata will save you an hour if you hit them.
The declared distribution version and the released version do not match. `pyproject.toml` sets `version = "0.8.1"` under a project named `godot_rl`, while the most recent release is v0.8.2 from 2025-02-25, with v0.8.0 before it on 2024-06-18 and v0.7.0 on 2024-02-02. So the tag you see on GitHub and the version your installer reports can differ by a patch.
The project URLs point at the wrong organisation. The `project.urls` block sets the homepage to `https://github.com/pypa/godot_rl_agents` and the bug tracker to the same path, while the repository you are reading is `edbeeching/godot_rl_agents`. Anything that resolves the homepage from package metadata, including some documentation tooling, will send you somewhere else. The issues go to `https://github.com/edbeeching/godot_rl_agents/issues` as the README states.
The Python floor is also inconsistent. `requires-python = ">=3.7"` while the classifiers stop at Python 3.10 and start at 3.8, so 3.7 is claimed as installable and untested by any classifier, and 3.11 and later are not claimed at all despite being the versions most people run.
Dependencies are declared dynamically rather than in `pyproject.toml`, listed under `dynamic`, and the concrete versions live in `setup.cfg`. That means you cannot read the version constraints from the file most tooling looks at.
ONNX export is the way to ship without Python
Everything above keeps a Python process attached to a running Godot game for the whole training session. The library also offers a way out, and the README labels it plainly as experimental: support for onnx models with the Stable Baselines 3, rllib and CleanRL training frameworks.
The export is a training flag rather than a separate script. You run your agent as usual and enable the option `--onnx_export_path=GameModel.onnx` on the training command.
Then the game loads the model directly. The steps are: use the mono version of the Godot Editor, add the onnx model path to the sync node, and let the project run against the model.
Two friction points are documented. If the onnx path option is missing in your editor, you have to download the plugin from its own source repository, `godot_rl_agents_plugin`, which is a separate repository from this one. And if the project fails to build, the README tells you to ensure the contents of the `.csproj` and `.sln` files match those of the plugin source, which is a class of problem that arrives as a build error with no message pointing at the cause.
This is the option that matters for shipping. An exported ONNX model with the plugin means the inference happens inside the game process, so the shipped build does not need Python, the training dependencies, or the bridge. Note it does not cover Sample Factory, so a project on that backend has no export route as documented.
Where godot-rl is the wrong tool
Four cases are ruled out by the documentation itself, and one by arithmetic.
If your environment is not a game, this is the wrong package. The value is the Godot side: a rendering loop, a scene graph and an AI sensor suite. A plain Python environment with no renderer is simpler to build with StableBaselines3 or CleanRL directly, and you lose nothing by not routing observations through a game engine.
If you need Sample Factory on Windows, stop. That combination is not listed, and the quickstart's choice of StableBaselines3 exists because of this.
If you need a stable API, wait. The version line is 0.8.x, the `gdrl` entry point is deprecated and scheduled for removal in version 1.0, and the deprecated form in the README still differs from the current one by an entire flag. Pre-1.0 means your integration will be rewritten.
The arithmetic is about training cost. This approach launches a graphical game as a subprocess and communicates with it, and there is no statement anywhere in the README about headless throughput, about running many environments per machine, or about what a training hour costs in render time. Anyone who has trained a policy on a non-game environment has a reference point for how slow that is. If your target is an agent that acts in a world rather than a grid, accept that your iteration loop is minutes, not milliseconds, and check that against how many experiments you intend to run.
Editorial conclusion
Adopt godot-rl when your agent has to act in a rendered 2D or 3D world rather than an abstract environment, and start with the StableBaselines3 backend on Windows, since Sample Factory is not listed there, then move to ONNX export so the shipped game does not need a Python process. Do not adopt it for a non-game environment or if you need a stable API before version 1.0, since the gdrl entry point is deprecated for removal. Verify first that the installed godot_rl version matches what you expect, because pyproject.toml declares 0.8.1 while the latest release is v0.8.2.
Frequently asked questions
How do I install godot-rl?
The package is godot-rl on PyPI, so pip install godot-rl inside a virtual environment. The README suggests venv or Conda to isolate dependencies, and you should also install git-lfs before running the tests.
Which reinforcement learning frameworks does godot-rl support?
Four: StableBaselines3, Sample Factory, Ray RLlib and CleanRL, each with an advanced guide in docs and example scripts in examples. StableBaselines3, RLlib and CleanRL are listed for Windows, Mac and Linux, while Sample Factory is listed for Mac and Linux.
Can I train a Godot agent without exporting the game?
Yes, the README documents in-editor training. Download the Godot 4 Game Engine in its .NET version, open the example project, and start training with python examples/stable_baselines3_example.py with no arguments.
How do I export a trained agent to ONNX?
Train with the --onnx_export_path flag set to a filename, then in the mono version of the Godot Editor add that onnx path to the sync node. The README calls this support experimental and covers Stable Baselines 3, rllib and CleanRL, and you may need the plugin from its own source repository.
Where do the example training environments come from?
They are in a separate repository, godot_rl_agents_examples, and are fetched with gdrl.env_from_hub -r edbeeching/godot_rl_JumperHard. On Linux and macOS you may need to run chmod +x on the downloaded game executable.
What licence is godot-rl under?
MIT, and the README states that Godot and Godot RL Agents are free and open source with no strings attached and no royalties. Check the LICENSE file for the terms themselves; this is not legal advice.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/edbeeching-godot-rl-agents)