> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/autorope/donkeycar/llms.txt
> Use this file to discover all available pages before exploring further.

# Donkey Gym Simulator

> Train and race in virtual environments using the Donkey Gym simulator

The Donkey Gym simulator allows you to train and test your autonomous models in virtual environments without risking your physical car. Built on Unity and OpenAI Gym, it provides realistic physics and multiple track environments.

## Overview

Donkey Gym enables:

* **Virtual racing** on generated tracks and real-world courses
* **Safe training** without hardware wear
* **Rapid iteration** with instant resets
* **Latency simulation** to test real-world conditions
* **Multi-environment support** including warehouse and AVC tracks

## Installation

Download the simulator binary for your platform:

```bash theme={null}
# Linux
wget https://github.com/tawnkramer/donkey_gym/releases/download/v18.9/DonkeySimLinux.zip
unzip DonkeySimLinux.zip
```

Install the Python gym environment:

```bash theme={null}
pip install gym-donkeycar
```

## Configuration

Edit your `myconfig.py` to enable the simulator:

```python theme={null}
# Enable Donkey Gym
DONKEY_GYM = True

# Path to simulator executable
DONKEY_SIM_PATH = "/path/to/donkey_sim.x86_64"
# Use "remote" to connect to running sim
# Use "remote" when racing on virtual-race-league

# Choose environment
DONKEY_GYM_ENV_NAME = "donkey-generated-track-v0"
# Options:
# - donkey-generated-track-v0 (procedural tracks)
# - donkey-generated-roads-v0 (road networks)
# - donkey-warehouse-v0 (indoor warehouse)
# - donkey-avc-sparkfun-v0 (AVC course)

# Gym configuration
GYM_CONF = {
    "img_h": 120,
    "img_w": 160,
    "body_style": "donkey",  # donkey|bare|car01
    "body_rgb": (128, 128, 128),
    "car_name": "car",
    "font_size": 100,
    "racer_name": "Your Name",
    "country": "Place",
    "bio": "I race robots."
}

# Network settings
SIM_HOST = "127.0.0.1"
# Use "trainmydonkey.com" for virtual-race-league

# Artificial latency (milliseconds)
SIM_ARTIFICIAL_LATENCY = 0
# Try 100-400ms to simulate network delay
```

## DonkeyGymEnv Part

The `DonkeyGymEnv` part connects your vehicle to the simulator:

```python theme={null}
from donkeycar.parts.dgym import DonkeyGymEnv

# Create gym environment
cam = DonkeyGymEnv(
    cfg.DONKEY_SIM_PATH,
    host=cfg.SIM_HOST,
    env_name=cfg.DONKEY_GYM_ENV_NAME,
    conf=cfg.GYM_CONF,
    delay=cfg.SIM_ARTIFICIAL_LATENCY
)

# Add to vehicle
V.add(cam, 
      inputs=['angle', 'throttle', 'brake'],
      outputs=['cam/image_array'],
      threaded=True)
```

From `donkeycar/parts/dgym.py:67-71`:

```python theme={null}
cam = DonkeyGymEnv(cfg.DONKEY_SIM_PATH, 
                   host=cfg.SIM_HOST, 
                   env_name=cfg.DONKEY_GYM_ENV_NAME, 
                   conf=cfg.GYM_CONF, 
                   delay=cfg.SIM_ARTIFICIAL_LATENCY)
```

## Recording Telemetry

Capture additional telemetry from the simulator:

```python theme={null}
# Enable telemetry recording
SIM_RECORD_LOCATION = True    # x, y, z position and speed
SIM_RECORD_GYROACCEL = True   # gyroscope and accelerometer
SIM_RECORD_VELOCITY = True    # velocity vector
SIM_RECORD_LIDAR = False      # lidar data (if enabled)
```

When enabled, the simulator outputs include:

```python theme={null}
cam = DonkeyGymEnv(
    cfg.DONKEY_SIM_PATH,
    host=cfg.SIM_HOST,
    env_name=cfg.DONKEY_GYM_ENV_NAME,
    conf=cfg.GYM_CONF,
    record_location=cfg.SIM_RECORD_LOCATION,
    record_gyroaccel=cfg.SIM_RECORD_GYROACCEL,
    record_velocity=cfg.SIM_RECORD_VELOCITY,
    record_lidar=cfg.SIM_RECORD_LIDAR
)

# Outputs: image, pos_x, pos_y, pos_z, speed, cte, 
#          gyro_x, gyro_y, gyro_z, accel_x, accel_y, accel_z
```

## Latency Simulation

The simulator supports artificial latency to test control algorithms under realistic network conditions:

```python theme={null}
# Add 150ms delay (typical network latency)
SIM_ARTIFICIAL_LATENCY = 150
```

The delay buffer implementation from `donkeycar/parts/dgym.py:47-62`:

```python theme={null}
def delay_buffer(self, frame, info):
    now = time.time()
    buffer_tuple = (now, frame, info)
    self.buffer.append(buffer_tuple)

    # go through the buffer
    num_to_remove = 0
    for buf in self.buffer:
        if now - buf[0] >= self.delay:
            num_to_remove += 1
            self.frame = buf[1]
        else:
            break

    # clear the buffer
    del self.buffer[:num_to_remove]
```

## Running the Simulator

### Local Mode

Start your car in simulator mode:

```bash theme={null}
python manage.py drive --js
```

The simulator will launch automatically and connect.

### Remote Mode

Start the simulator manually, then connect:

```python theme={null}
DONKEY_SIM_PATH = "remote"
```

```bash theme={null}
python manage.py drive --js
```

### Training

Train models using simulator data:

```bash theme={null}
# Record training data in simulator
python manage.py drive

# Train model
python train.py --tub data/ --model models/sim_pilot.h5

# Test in autopilot mode
python manage.py drive --model models/sim_pilot.h5
```

## Virtual Race League

Race against others online:

```python theme={null}
SIM_HOST = "trainmydonkey.com"
DONKEY_SIM_PATH = "remote"
```

Configure your racer profile:

```python theme={null}
GYM_CONF["racer_name"] = "SpeedDemon"
GYM_CONF["country"] = "USA"
GYM_CONF["bio"] = "Testing autonomous racing algorithms"
```

## Resource Management

The simulator uses GPU resources. To avoid conflicts:

```python theme={null}
import os
if cfg.DONKEY_GYM:
    # Disable CUDA for model to free GPU for simulator
    os.environ["CUDA_VISIBLE_DEVICES"] = "-1"
```

From `donkeycar/templates/simulator.py:47-50`.

## Troubleshooting

### Connection Issues

```python theme={null}
# Check simulator is running
# Verify SIM_HOST and port (default 9091)
SIM_HOST = "127.0.0.1"
```

### Performance

* Lower image resolution in GYM\_CONF
* Disable unnecessary telemetry recording
* Close other GPU-intensive applications

### Path Not Found

```bash theme={null}
# Verify simulator path
ls -l /path/to/donkey_sim.x86_64

# Make executable
chmod +x /path/to/donkey_sim.x86_64
```

## Best Practices

1. **Start with generated tracks** - Test algorithms on varied terrain
2. **Use artificial latency** - Prepare for real-world network delays
3. **Record telemetry** - Analyze car behavior and track position
4. **Transfer learning** - Fine-tune simulator models with real-world data
5. **Test edge cases** - Use simulator to safely test failure scenarios

## Next Steps

* Configure [telemetry](/advanced/telemetry) to monitor performance
* Add [path following](/advanced/path-following) for waypoint navigation
* Explore [kinematics models](/advanced/kinematics) for physics simulation