assetto-corsa-rl 0.1.0

Reinforcement Learning toolkit for Assetto Corsa and Car Racing environments

Assetto Corsa RL

A comprehensive reinforcement learning toolkit for training agents in Assetto Corsa and Car Racing environments using Soft Actor-Critic (SAC) with optional VAE-based vision encoding.

Features

• 🏎️ Assetto Corsa Integration: Full telemetry and control integration with Assetto Corsa
• 🎮 Car Racing Support: OpenAI Gym Car Racing environment compatibility
• 🧠 SAC Implementation: State-of-the-art Soft Actor-Critic algorithm
• 👁️ Vision-Based Learning: VAE encoder for image-based observations
• 📊 Behavioral Cloning: Pretrain agents from human demonstrations
• 🛠️ Complete CLI: Unified command-line interface for all operations
• 📈 WandB Integration: Experiment tracking and visualization

Installation

From PyPI (Recommended)

pip install assetto-corsa-rl

From Source

git clone https://github.com/yourusername/assetto-corsa-rl.git
cd assetto-corsa-rl
pip install -e .

Development Installation

pip install -e ".[dev]"

Quick Start

Assetto Corsa

1. Record Racing Line

acrl ac record-line --output racing_lines.json --laps 2

2. Train Agent

acrl ac train

3. Test Agent

acrl ac load --ckpt models/checkpoint.pt --episodes 5

Car Racing (Gym)

Train Agent

acrl gym train

Test Agent

acrl gym load --model pretrained.pt --episodes 5 --render

CLI Reference

Global Commands

acrl --version          # Show version
acrl --help             # Show help

Assetto Corsa Commands

Training

# Train SAC agent
acrl ac train

# Pretrain with behavioral cloning
acrl ac pretrain --data-dir datasets/demonstrations --epochs 50

# Train VAE encoder
acrl ac train-vae --input-dir datasets/ac_images --epochs 100

Testing

# Load and test trained agent
acrl ac load --ckpt models/checkpoint.pt --episodes 5 --deterministic

# Visualize VAE reconstructions
acrl ac load-vae --ckpt vae.ckpt --env ac

Data Collection

# Record racing line
acrl ac record-line --output racing_lines.json --laps 2 --track monza

# Record demonstrations
acrl ac record-demo --output-dir datasets/demonstrations --duration 300

# Save image dataset
acrl ac save-images --output-dir datasets/ac_images --frame-stack 4

Visualization

# Visualize racing line
acrl ac vis-line --input racing_lines.json --lap 0

# Visualize image dataset
acrl ac vis-images --input-dir datasets/ac_images

Car Racing Commands

# Train agent
acrl gym train

# Test agent
acrl gym load --model checkpoint.pt --episodes 5 --render

# Train VAE
acrl gym train-vae --epochs 10 --batch-size 128

# Visualize VAE
acrl gym load-vae --model vae.ckpt --frames 4

Project Structure

assetto-corsa-rl/
├── src/
│   └── assetto_corsa_rl/
│       ├── ac_env.py           # Assetto Corsa environment
│       ├── cli.py              # Command-line interface
│       ├── model/
│       │   ├── sac.py          # SAC implementation
│       │   └── vae.py          # VAE encoder
│       └── train/
│           └── train_core.py   # Training loop
├── scripts/
│   ├── ac/                     # Assetto Corsa scripts
│   └── car-racing/             # Car Racing scripts
├── configs/                    # Configuration files
├── tests/                      # Unit tests
└── pyproject.toml             # Package configuration

Configuration

The toolkit uses YAML configuration files in the configs/ directory:

• configs/ac/env_config.yaml - Environment settings
• configs/ac/model_config.yaml - Model architecture
• configs/ac/train_config.yaml - Training hyperparameters

Requirements

• Python >= 3.9
• PyTorch >= 2.0.0
• TorchRL >= 0.2.0
• Gymnasium >= 0.29.0
• OpenCV >= 4.8.0
• Click >= 8.1.0

See requirements.txt for full list.

Development

Running Tests

pytest tests/

Code Formatting

black src/ tests/
isort src/ tests/

Type Checking

mypy src/

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details

Citation

If you use this toolkit in your research, please cite:

@software{assetto_corsa_rl,
  title = {Assetto Corsa RL: Reinforcement Learning Toolkit},
  author = {Contributors},
  year = {2026},
  url = {https://github.com/yourusername/assetto-corsa-rl}
}

Acknowledgments

• Built with TorchRL
• Inspired by racing simulation research
• SAC algorithm from Haarnoja et al. (2018)