assetto-corsa-rl 0.1.5
Reinforcement Learning toolkit for Assetto Corsa and Car Racing environments
License: MIT
Requires Python: >=3.10
Keywords: reinforcement-learning, assetto-corsa, racing, SAC, VAE, deep-learning

# 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)

```bash
pip install assetto-corsa-rl
```

### From Source

```bash
git clone https://github.com/yourusername/assetto-corsa-rl.git
cd assetto-corsa-rl
pip install -e .
```

### Development Installation

```bash
pip install -e ".[dev]"
```

## Quick Start

### Assetto Corsa

#### 1. Record Racing Line

```bash
acrl ac record-line --output racing_lines.json --laps 2
```

#### 2. Train Agent

```bash
acrl ac train
```

#### 3. Test Agent

```bash
acrl ac load --ckpt models/checkpoint.pt --episodes 5
```

### Car Racing (Gym)

#### Train Agent

```bash
acrl gym train
```

#### Test Agent

```bash
acrl gym load --model pretrained.pt --episodes 5 --render
```

## CLI Reference

### Global Commands

```bash
acrl --version          # Show version
acrl --help             # Show help
```

### Assetto Corsa Commands

#### Training

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
pytest tests/
```

### Code Formatting

```bash
black src/ tests/
isort src/ tests/
```

### Type Checking

```bash
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:

```bibtex
@software{assetto_corsa_rl,
  title = {Assetto Corsa RL: Reinforcement Learning Toolkit},
  author = {Patel, Ved},
  year = {2026},
  url = {https://github.com/AssettoCorsaRL/AssettoCorsaRL}
}
```

## Acknowledgments

- Built with [TorchRL](https://github.com/pytorch/rl)
- Inspired by racing simulation research
- SAC algorithm from [Haarnoja et al. (2018)](https://arxiv.org/abs/1801.01290)