Setup

One-time installation for every unit in this course. Do this before Unit 0.

You can read the course online

The course is published at godot-rl.onlinekurs.training and needs no installation to read. Everything below is for running the code: the units execute Python and Godot scenes from the repository, so you still clone it and still create the godot_env environment.

Course repo — clone first

Everything in this course — requirements-course.txt, the examples/ code used in Neural Foundations, helper scripts — lives in the course repository. Clone it and work from its root:

git clone https://github.com/minigraphx/godot-rl-course.git
cd godot-rl-course

No git? Use Code → Download ZIP on github.com/minigraphx/godot-rl-course, unpack it, and cd into the unpacked folder instead.

Run all course commands from the repo root

Unless a unit says otherwise, every pip, python -m examples.…, and godot --headless command in this course assumes your terminal is in the course repo root — the folder containing requirements-course.txt.

Godot 4 — Standard build

Download the Standard build of Godot 4 from godotengine.org. The course's native runner requires Godot 4.5 or newer.

No .NET SDK, no C# — the Standard build is all you need

Earlier revisions of this course used a C# plugin that required the .NET/Mono edition of Godot plus the .NET SDK. The course now uses godot-native-rl, an addon you install into the course repo with one command (below), so the Standard build suffices. If you already installed the .NET edition, it works fine too; there is just no longer any reason to install it.

Godot on the command line

Several units run Godot from the terminal (godot --headless …). Downloading the editor does not put a godot command on your PATH — set that up once:

macOS — the binary lives inside the app bundle. Add an alias to your shell profile (~/.zshrc):

alias godot="/Applications/Godot.app/Contents/MacOS/Godot"

Windows — add the folder containing Godot_*.exe to your PATH (Settings → System → About → Advanced system settings → Environment Variables), or call the executable by its full path. Forward slashes work in every shell:

C:/Tools/Godot/Godot_v4.5-stable_win64.exe --version

Linux — make the downloaded binary executable and link it onto your PATH:

chmod +x Godot_v4.5-stable_linux.x86_64
sudo ln -s "$PWD/Godot_v4.5-stable_linux.x86_64" /usr/local/bin/godot

Verify

Open a new terminal and run godot --version — it should print a 4.x version string.

Python — Conda environment

Why Conda? It lets you pin Python 3.10 in an isolated folder so the ML packages don't clash with other projects. godot-rl and Stable-Baselines3 are most reliable on Python 3.10; newer versions often break package wheels.

Install Miniconda (skip if you already have conda):

Download from docs.conda.io/en/latest/miniconda.html for your OS. After installation open a new terminal and verify:

conda --version

Create the environment (one-time):

conda create --name godot_env python=3.10 -y

Every new terminal — activate before any training command:

conda activate godot_env
pip install -r requirements-course.txt

requirements-course.txt is at the root of the course repo you cloned above — run the command from there. It pins every package to a known-good version — see the compatibility table below.

What gets installed

godot-rl — Python ↔ Godot socket bridge and Stable-Baselines3 wrappers. It also installs a gdrl command, which upstream has deprecated and which this course does not use — see Reference
stable-baselines3 — PPO, SAC, and other algorithms
torch — PyTorch backend for training
tensorboard — training-curve visualisation
matplotlib, onnx, onnxruntime, ncnn, opencv-python — Neural Foundations plots, model export, and parity checks

Verify: python -c "import godot_rl; print('ok')"

Native inference runs on every desktop platform

Training speaks a local socket and is pure GDScript. Native ncnn inference — running a trained brain inside Godot without Python, used in Neural Foundations 3 and the Ship phase — ships prebuilt libraries for macOS Apple Silicon, Windows x86_64 and Linux x86_64 (plus iOS, Android and Web). All three desktop platforms in the compatibility table are covered.

macOS / Linux first run

The installer may ask you to run conda init — follow the prompt, then open a new terminal.

Windows first run

See Windows first run below for PowerShell / cmd / Git Bash activation notes and Windows-specific gotchas.

Compatibility table

The table below shows the package versions that ship in requirements-course.txt and the Godot version they were tested with.

Course tag	Godot	godot-native-rl	godot-rl (Python bridge)	stable-baselines3	PyTorch	Python
2026-05	4.5+ (Standard)	`v0.4.0` (fetched)	0.8.2	2.3.2	2.6.0	3.10

Do not upgrade packages mid-course

godot-rl, SB3, and PyTorch have broken APIs across releases. Stick to the pinned versions in requirements-course.txt for the duration of the course. After the course, feel free to experiment with newer releases — just create a fresh conda environment.

Windows first run

The steps above work on Windows with minor differences. Read this section before your first conda activate.

Shell choice

Shell	Notes
Anaconda Prompt	Easiest — `conda activate godot_env` works out of the box.
PowerShell	Run `conda init powershell` once (as administrator), restart PowerShell, then `conda activate godot_env`.
cmd	Run `conda init cmd.exe` once, restart cmd, then `conda activate godot_env`.
Git Bash	Run `conda init bash` once (from Anaconda Prompt), restart Git Bash, then `conda activate godot_env`.

`--env_path` with Windows paths

godot-rl accepts forward slashes on Windows — prefer them over backslashes to avoid shell escaping issues:

# Recommended — forward slashes work everywhere, including PowerShell and cmd
python stable_baselines3_example.py --env_path=C:/Users/YourName/Projects/my_game/my_game.exe

# Also valid — backslashes, but must escape or quote
python stable_baselines3_example.py --env_path="C:\Users\YourName\Projects\my_game\my_game.exe"

Windows Defender / antivirus socket issue

Windows Defender (and many third-party antivirus programs) sometimes silently block the local TCP port that godot-rl uses to communicate between Python and Godot (default: port 11008). Symptoms: training appears to start but Godot never connects; Python hangs waiting for the first observation.

Fix:

Open Windows Security → Firewall & network protection → Allow an app through firewall.
Add an exception for python.exe (your conda env's Python) and for the Godot executable.
Changing the port is not a command-line flag on the Python side — GodotEnv takes port= in code, while the Godot side reads --port=… from its own command line. The firewall exception above is the simpler fix.

If you use a third-party antivirus, add the conda environment folder (e.g. C:\Users\YourName\miniconda3\envs\godot_env\) and your Godot project folder to the exclusion list.

`chmod +x` is not needed on Windows

The macOS/Linux commands chmod +x godot_binary do not apply on Windows. Godot .exe files are already executable by the OS.

WSL2 vs native Windows

Approach	Pros	Cons
Native Windows	Simplest setup, no translation layer, Direct3D GPU	Antivirus/firewall friction; paths use backslashes
WSL2 (Ubuntu)	Full Linux toolchain, easier GPU setup via CUDA	GPU passthrough (CUDA in WSL2) requires Windows 11 + WSL2 kernel ≥ 5.15; Godot GUI cannot render inside WSL2 without an X server or WSLg

Recommendation for this course: use native Windows unless you already have a working WSL2 + GPU setup. Godot must run on the Windows host side (or WSLg) regardless; mixing Godot on Windows with Python in WSL2 requires extra port-forwarding steps that are not covered in this course.

Godot addon — godot-native-rl

The Godot-side bridge is godot-native-rl. Its native libraries are larger than the whole course repository, so they are not committed — one command installs the pinned release:

scripts/fetch-native-runner.sh

It downloads the version pinned in examples/neural_foundations/game/GODOT_NATIVE_RL_VERSION, verifies its checksum, and unpacks it into the game project. Run scripts/fetch-native-runner.sh --check any time to see what is installed. There is nothing to build.

Training: the NcnnSync node speaks the same local-socket protocol as the gdrl Python side. Pure GDScript — works on every platform.
Inference: an ncnn GDExtension runs trained brains natively in Godot, with prebuilt libraries for macOS, Windows and Linux. Training does not need them.

The addon's node classes (NcnnSync, NcnnAIController2D, NcnnAIController3D, sensor nodes) auto-register when the project opens, so scenes work before you touch anything. Still, enable the plugin once under Project → Project Settings → Plugins → Godot Native RL. It adds three things the classes alone do not:

it packs your ncnn model files into exported builds — without it an exported game starts and then fails with "cannot read model files"
it reports a clear error when the native inference library is missing for your platform, instead of failing silently
it installs the NcnnAIController script templates into the project

Only the first one bites, and it bites late — in the Ship phase, far from this page.

Two different things

godot-rl is the Python package (installed by requirements-course.txt) that runs the training server. godot-native-rl is the Godot addon installed by scripts/fetch-native-runner.sh. They talk to each other over a local socket.

Verify

Open examples/neural_foundations/game/project.godot in Godot, then Add Node → search NcnnSync and NcnnAIController3D. If they appear, the addon is working.

Using the addon in your own project: copy addons/godot_native_rl/ into your project's addons/ folder. For native inference, also copy ncnn_runner.gdextension and the bin/ folder.

Legacy plugin — godot-rl-agents (units awaiting migration)

Units from RL Essentials onward still use example environments built on the older C# plugin. Skip this section until you reach those units — Unit 0 and Neural Foundations need none of it.

The legacy stack additionally requires the .NET/Mono edition of Godot and the .NET SDK. Then:

Clone or download github.com/edbeeching/godot_rl_agents_plugin
Copy the addons/godot_rl_agents folder into the example project's addons/ folder (the official example projects ship with it already)
Project → Project Settings → Plugins → Godot RL Agents → Enabled; wait for MSBuild to finish
If Godot reports a C# build error on first open, close and reopen the project — the assemblies build correctly on the second open
Verify: Add Node → search Sync and AIController2D

These units are being migrated to the native stack one by one; this section disappears when the migration completes.

Setup

Course repo — clone first

Godot 4 — Standard build

Godot on the command line

Python — Conda environment

Compatibility table

Windows first run

Shell choice

--env_path with Windows paths

Windows Defender / antivirus socket issue

chmod +x is not needed on Windows

WSL2 vs native Windows

Godot addon — godot-native-rl

Legacy plugin — godot-rl-agents (units awaiting migration)

`--env_path` with Windows paths

`chmod +x` is not needed on Windows