Train an AI agent to play Noita — the physics-based roguelike — using reinforcement learning (PPO).
🎯 Goal: Teach an agent to navigate, fight, and survive in Noita's procedurally generated world using only pixel observations and game state data.
- PPO Training — Proximal Policy Optimization with custom reward shaping
- Lua-Python Bridge — Real-time communication between Noita's Lua mod and Python training loop via
pollnet.dll - Custom Environment — Gym-compatible wrapper with pixel observations, health, mana, and inventory state
- Episode Tracking — Automatic logging of rewards, deaths, and progression metrics
- CI/CD — Automated tests on every push
┌─────────────────┐ pollnet.dll ┌──────────────────┐
│ Noita Game │ ◄─────────────────────────► │ Python Trainer │
│ (Lua Mod) │ TCP / Shared │ (PPO Agent) │
│ │ Memory │ │
└─────────────────┘ └──────────────────┘
│ │
▼ ▼
Game State Neural Network
- Pixel buffer - CNN encoder
- HP / Mana - Policy head
- Inventory - Value head
- Position - Reward shaping
- Python 3.10+
- Noita (Steam) — must be installed and launched at least once
- Windows (for
pollnet.dllintegration)
# Clone the repository
git clone https://github.com/yava-code/noitarl.git
cd noitarl
# Install dependencies
pip install -r requirements.txt
# Copy and configure environment
cp .env.example .env
# Edit .env with your Noita path and training settings# Start training
python train.py
# Evaluate a trained model
python eval.py --checkpoint checkpoints/latest.ptKey settings in config.py:
| Parameter | Default | Description |
|---|---|---|
NOITA_PATH |
Auto-detect | Path to Noita installation |
LEARNING_RATE |
3e-4 | PPO learning rate |
GAMMA |
0.99 | Discount factor |
BATCH_SIZE |
256 | Training batch size |
MAX_STEPS |
10_000_000 | Total training steps |
| Metric | Value |
|---|---|
| Episodes logged | See data/episode_history.csv |
| Best reward | Tracked in training logs |
| Checkpoints | Saved to checkpoints/ |
noitarl/
├── train.py # Main training script
├── eval.py # Evaluation script
├── config.py # Configuration parameters
├── callbacks.py # Training callbacks & logging
├── init.lua # Noita Lua mod (game-side)
├── bin/
│ └── pollnet.dll # Lua-Python communication library
├── data/
│ ├── episode_history.csv # Episode metrics
│ └── schemas/ # Game state XML schemas
├── docs/
│ ├── lua_api_documentation.txt
│ ├── component_documentation.txt
│ └── Noita-ModdingAgreement-v100.rtf
├── .github/workflows/
│ └── tests.yml # CI pipeline
└── ROADMAP.md # Development roadmap
See ROADMAP.md for the full development plan.
Current priorities:
- Improve reward shaping for exploration
- Add multi-objective training (survival + progression)
- Implement curriculum learning
- Add wandb integration for experiment tracking
Contributions are welcome! See CONTRIBUTING.md for guidelines.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License — see the LICENSE file for details.
- Noita by Nolla Games — incredible game with amazing modding support
- Stable Baselines3 — RL framework
- pollnet — Lua-Python communication library
Made with ❤️ and a lot of dead agents