godot_rl_agents

Godot RL Agents is a fully open-source package that bridges the Godot Engine and Python-based machine learning algorithms, allowing game developers, AI researchers, and hobbyists to train complex behaviors for non-player characters (NPCs) or agents. The repository provides: - An interface between games created in the Godot Engine and machine learning algorithms running in Python. - Wrappers for four well-known RL frameworks: StableBaselines3, Sample Factory, Ray RLLib, and CleanRL. - Support for memory-based agents using LSTM or attention-based interfaces. - Support for both 2D and 3D games. - A suite of AI sensors to enhance an agent's ability to observe the game world. - Godot and Godot RL Agents are completely free and open source under the permissive MIT license. The project is detailed in a AAAI-2022 Workshop paper (arXiv:2112.03636). ## Quickstart Guide The quickstart guide gets users up and running with the StableBaselines3 backend, which supports Windows, Mac, and Linux. A video tutorial is also available. ### Installation and first training 1. Install the library: `pip install godot-rl` 2. Download example environments from the hub, e.g., `gdrl.env_from_hub -r edbeeching/godot_rl_JumperHard` 3. Add run permissions to the game executable if needed. 4. Train and visualize using the Stable Baselines 3 example script: ```bash python examples/stable_baselines3_example.py --env_path=examples/godot_rl_JumperHard/bin/JumperHard.x86_64 --experiment_name=Experiment_01 --viz ``` ### In-editor interactive training Users can also train agents directly in the Godot editor without exporting the game executable. Steps include downloading the Godot 4 .NET version, importing the example project, and running the training script. ### Tutorials - Custom environment tutorial - Simple environment tutorial using new sensors - Cross the road mini-game tutorial - Imitation learning tutorial ### Exporting and loading trained agents in ONNX format The latest version provides experimental support for ONNX models with Stable Baselines 3, RLLib, and CleanRL. Users can export a trained model and load it in the Godot editor using the mono version and the plugin. ## Advanced Usage Godot RL Agents supports four different RL training frameworks, each with detailed guides: - StableBaselines3 (Windows, Mac, Linux) - SampleFactory (Mac, Linux) - CleanRL (Windows, Mac, Linux) - Ray RLLib (Windows, Mac, Linux) ## Contributing Contributions are welcome, including new environments, readme improvements, and Python codebase additions. The process involves forking the repo, cloning, creating a virtual environment, and performing an editable installation. Tests can be run with `make test`, and code formatting with `make style` and `make quality`. ## FAQ - **Why develop Godot RL Agents?** To provide a free and open-source tool for Deep RL research and game development, enable unique NPC behaviors, and allow automated gameplay testing. - **How to contribute?** Try it out, find bugs, raise issues, or submit pull requests. - **Mac support?** Should now be working. - **Similarity to Unity ML Agents?** Inspired by Unity ML Agents but aims to be more compact, concise, and hackable with less abstraction. - **Periodic freezing during training?** Normal with the default SB3 script while the model updates; exporting to ONNX allows faster inference. ## License Godot RL Agents is MIT licensed. The "Cartoon Plane" asset is under Creative Commons Attribution. ## Citing A BibTeX entry is provided for citing the paper. ## Acknowledgments Thanks to the Godot Engine authors, the developers of Sample Factory, CleanRL, Ray, and Stable Baselines, and the creators of Unity ML Agents Toolkit for inspiration.