Unit 0 — Setup & First Run
Time
Reading: ~20 min · Training: ~15 min GPU / ~1 h CPU
Install the Godot editor (Standard build) and Python toolchain. Run your first training session with the bundled foundations racer and confirm the Godot ↔ Python socket works.
First success (one session)
- Godot — the racer moving on its track (Play Scene while Python trains)
- Python — terminal shows rollout tables;
ep_rew_meanappears - TensorBoard (optional) —
tensorboard --logdir=logs/foundations_racershows a curve - Neural Foundations — you will build visible neurons before the RL loop
Three ways to see your AI (every unit)
Godot behavior · TensorBoard curves · what you change in AIController
Short on time?
Follow the first evening script (~2½–3 h) to finish Unit 0 and start Neural Foundations 1 in one sitting.
1 · Split architecture
Two runtimes talk over a local socket — Godot sends observations and receives actions; Python runs the training loop.
| Component | Role | Runtime |
|---|---|---|
| Godot | Physics, observations, rewards | Godot 4 Standard, GDScript |
| Addon (GDScript) | NcnnSync node, native ncnn bridge | godot-native-rl (pinned release, installed by script) |
| Python | PPO training (SB3) | Conda, Python 3.10 |
The Standard Godot build is enough
Everything on the Godot side is GDScript — no C#, no .NET SDK, no build step. Download the Standard build (4.5+) from godotengine.org; Setup has the details.
2 · Conda environment
First time here?
Full installation instructions — Miniconda, godot_env, and the Godot addon — are in Setup. Complete that page first, then return here.
Quick reminder for every new terminal:
3 · Godot project & addon
Unit 0 and the Neural Foundations units train inside the course repo's own Godot project. The godot-native-rl addon is not committed to the repo — its native libraries outweigh everything else in it — so install the pinned release first:
scripts/fetch-native-runner.sh # from the course repo root
scripts/fetch-native-runner.sh --check # shows pinned vs. installed
Then:
- Godot → Import → browse to
godot-rl-course/examples/neural_foundations/game/project.godot - Let the first import finish — nothing is compiled, so this is quick
- Project → Project Settings → Plugins → enable Godot Native RL
- Verify: Add Node → search
NcnnSync. If it appears, the addon is loaded.
Why step 3, when the nodes already work without it?
The node classes register on their own. Enabling the plugin adds the piece that matters later: it packs your ncnn model files into exported builds. Without it, an exported game starts and then fails with "cannot read model files" — a long way from here, with nothing pointing back to this checkbox. One click now.
Examples repo for later units
Units from RL Essentials onward currently use environments from the separate godot_rl_agents_examples repo (the legacy stack — migration is tracked in the course repo's issues). Clone it as a sibling of the course repo when you reach those units:
4 · First training run
In-editor
Terminal 1 — start the Python trainer (from the course repo root):
Wait for "waiting for remote GODOT connection" in the log output.
Terminal 2 optional: tensorboard --logdir=logs/foundations_racer
Godot — open unit_03_racer/racer_train.tscn, press F6 (Play Scene). The racer should connect and start stepping; SB3 prints rollout tables in Terminal 1. The default 2048 timesteps is a smoke test (a few minutes) — it proves the socket, the trainer, and the scene work together. For visible learning, re-run with --timesteps 50000.
When the run finishes, the trainer saves a checkpoint and an ONNX export under examples/neural_foundations/game/unit_03_racer/models/.
Success criteria
Racer visible in Godot; rollout tables print with ep_rew_mean; no warnings, no socket errors; TensorBoard curve optional but recommended.
5 · Training modes for this course
| Phase | Units | Default |
|---|---|---|
| Explore | 0–2 | Editor Play Scene — see physics and reward bugs |
| Scale | 3–8 | Exported binary + --headless — faster rollouts |
| Ship | 9–10 | Native ncnn inference in NcnnSync — no Python at runtime |
Native inference preview (optional)
After training, the exported ONNX can be converted to ncnn and run natively: the evaluation scene unit_03_racer/racer_eval.tscn uses NcnnSync in inference mode — the agent runs without Python. Neural Foundations 3 walks through the full export → verify → deploy pipeline. This works on macOS, Windows and Linux; it needs the native libraries installed by scripts/fetch-native-runner.sh (see Setup).
First evening script (~2½–3 hours)
One sitting: tooling works, agent learns, you change a reward. Times are guides — install steps vary by machine.
| Block | Time | Do this | Done when |
|---|---|---|---|
| 1 · Install | 45–75 min | Section 2 — install Miniconda → create godot_env → pip installSection 3 — open the course game project in Godot |
import godot_rl prints ok; game project opens and NcnnSync appears in Add Node |
| 2 · First train | 30–45 min | Section 4 — Python trainer + Godot F6 Second terminal: tensorboard --logdir=logs/foundations_racer |
Racer moves; rollout tables print; no socket errors |
| 3 · Start Foundations 1 | 45–60 min | Open Neural Foundations 1 Read Section 1 (what a neuron computes), then predict the hand calculation in Section 2 (~15 min) → run the research plot or the Godot jumper scene While exploring: read Sections 3–4 |
You can name each contribution, weighted sum, and activation output |
Minimal command cheat sheet (Block 2)
conda activate godot_env
tensorboard --logdir=logs/foundations_racer &
python scripts/train_foundations_racer.py --timesteps 2048
# Godot: unit_03_racer/racer_train.tscn → F6 (Play Scene)
End-of-evening checklist
- [ ] Godot — saw the agent act
- [ ] Python — training ran without connection errors
- [ ] TensorBoard — opened at least once (localhost:6006)
- [ ] Code — ran one neuron forward-pass test or visual example
Tomorrow: finish Foundations 1–2, then RL Essentials (BallChase reward tweak) and Unit 2 Phase A (SimpleReachGoal).
Stuck?
Most first-evening blockers: Godot older than 4.5, Godot F6 pressed before the Python trainer was waiting, or firewall blocking the localhost socket. Re-read Section 1 if the split architecture is unclear.
Stretch Goals
Inspect the exported ONNX. Open examples/neural_foundations/game/unit_03_racer/models/foundations_racer.onnx in Netron (drag the file into the browser tab — no install). Identify the input tensor shape (obs), the output tensor shape (out0), and the activation between layers. This graph is the portable form of the brain — the export → verify → deploy pipeline in Neural Foundations 3 builds on it.
Run the deterministic math tests. The game project ships headless tests for the racer's observation and reward math:
The goal isn't the tests themselves — it's to confirm your godot command-line setup from Setup works, which every later unit relies on.
What's next
Tooling works. In Neural Foundations 1 you'll build one visible neuron, then connect networks to the RL loop in later units.
Two optional refreshers sit between here and there: Math Foundations 1 covers vectors and dot products, Math Foundations 2 probability and expected value. Skip them if the arithmetic in Neural Foundations 1 feels comfortable, and come back when a later unit's notation stops making sense.