TrackmaniaRL 1.3.0

TrackmaniaRL is a Python library for building and training reinforcement-learning agents in Trackmania 2020. Compose your own models, feature pipelines, replay samplers and learners, then use the same configuration from Python or the CLI.

• Composable models: encoders, temporal cores, value heads and actor-critic models.
• Training workflows: online RL, demonstrations, behavior cloning and checkpoint resume.
• Game integration: telemetry, camera observations, map geometry and control.
• Repeatable evaluation: complete trial records, finish rates and timing metrics.

The Python package and game integration support Windows and desktop Linux. On Linux, Trackmania runs through Proton and is not officially supported by Ubisoft Nadeo, so the game setup is experimental. WSL is not a supported game host. TrackmaniaRL 1.2.x requires Python 3.12 and uses RunSpec 2.0 and checkpoint schema 2.0.

Installation

Add the library to your Python 3.12 project:

pip install trackmaniarl

Optional integrations are available as extras, for example pip install "trackmaniarl[vision,wandb,distributed]". See platform and PyTorch setup for CPU and GPU installation details.

Train across computers

For off-policy algorithms such as IQN and SAC, multiple Trackmania actors on separate computers can send rollouts asynchronously to one learner that trains the model and publishes policy updates. Follow the multi-computer setup guide for installation, matching assets, authentication, encrypted tunneling and commands; PPO training remains local.

Use from Python

Given a run.yaml with an environment and learner configured:

from pathlib import Path

from trackmaniarl import RunSpec, Trainer, resolve_run

config = Path("run.yaml").resolve()
run = resolve_run(RunSpec.from_yaml(config), base_dir=config.parent)
try:
    result = Trainer(run).train()
    print(f"Collected {result.transitions} transitions; ran {result.updates} updates")
finally:
    run.logger.close()

Trainer runs local training. The CLI also provides the distributed actor/learner workflow. Start with the Python quickstart for a complete example that needs no game, GPU, map assets or tracking account.

Train in Trackmania

Create a separate project for your maps, models, configurations and training data:

trackmaniarl init my-agent --template trackmania
cd my-agent
uv sync

Follow the game quickstart to install Openplanet, connect the game, build map geometry and run training and evaluation. The generated project includes configurations for IQN, SAC, REDQ, TQC, discrete SAC, PPO and camera-based variants.

For the separately qualified Linux native backend, see the native headless environment and QR reference profile. It requires caller-supplied native assets and source references and runs without the Windows game client. See the guide for its strict clock and map limits.

Neural inference in motion

This full drive shows a selected evaluation lap from the contributor's strongest checkpoint for this map. The contributor reports approximately 12 wall-clock hours of training before the recording; capturing and rendering the film did not update its weights. The panel is an architecture showcase: it follows map-relative road geometry, a 60-value car/physics vector and 29 engineered driving-context values through the model to action scores and selected controls. The changing activation colours show real tensor values, but they are not feature attribution and individual cells are not intended to explain a decision by themselves. This selected lap uses the map-specific neighbors action filter. It is neither an unassisted-policy benchmark nor evidence of generalization. See the model and recording explanation for provenance, the five-attempt film series and GIF reproduction.

Documentation

Start at the documentation index.

Development and research

uv sync --group dev
uv run ruff format --check .
uv run ruff check .
uv run mypy --strict trackmaniarl
uv run pytest
uv build
uv run python scripts/check_distribution.py

See contributing and the development guide for the full checks. The repository layout separates the published package, examples, tests and local experiment data.

TrackmaniaRL is released under the MIT license. It originated from TMRL. Attribution is in NOTICE. It is not affiliated with Ubisoft or Nadeo.