Installation

Prerequisites

TrackMania RL requires:

This project is compatible with Windows and Linux. The authors primarily use Nvidia GPUs with CUDA support.

Python project setup

We recommend using uv (fast Python package manager) for installation.

Using pip (Alternative)

If not using uv, you can install with standard pip:

git clone https://github.com/ArtyomZemlyak/rulka.git
cd rulka
python -m venv .venv

# Activate environment
# Windows: .\.venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate

# Install PyTorch (check https://pytorch.org for your system)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# Install the project
pip install -e .

Verify Installation

python -c "import torch; print(f'PyTorch: {torch.__version__}'); print(f'CUDA: {torch.cuda.is_available()}')"
python -c "import torchrl; print(f'TorchRL: {torchrl.__version__}')"
python -c "import trackmania_rl; print('Installation OK')"

Linux-specific instructions

In the folder /scripts/, create a bash script that takes an integer port as its single argument. The script should start the game configured to listen on port port for TMInterface communications. The scripts /scripts/launch_game_pb.sh and /scripts/launch_game_agade.sh are working examples on the authors’ systems.

Note

The authors have experienced improved FPS when executing TMNF within wine with the following setup:

sudo apt install winetricks
winetricks dxvk

and launching the game with exec gamemoderun wine (...) (see /scripts/launch_game_pb.sh for example).

Game configuration

1. Configure TrackMania Nations Forever

The game must be configured (via TmForeverLauncher.exe in the game’s installation directory) to run in windowed mode. We recommend adjusting game settings to run at the lowest resolution available with low graphics quality.

Create an online account in TrackMania (offline accounts are not supported by TMInterface).

Note

There is a compromise to be made between training speed which increases with FPS and trained performance which increases with image quality. Users can experiment with their setup.

2. Configure TMLoader

  • Launch TMLoader

  • Create a profile named default (or use a custom name - set WINDOWS_TMLOADER_PROFILE_NAME in .env accordingly)

  • Enable TMInterface in the profile

3. Copy Python_Link.as plugin

The Python_Link.as plugin enables communication between Python and TMInterface.

On Windows (PowerShell):

# Create directory if it doesn't exist
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\Documents\TMInterface\Plugins"

# Copy the plugin
Copy-Item "trackmania_rl\tmi_interaction\Python_Link.as" "$env:USERPROFILE\Documents\TMInterface\Plugins\"

On Linux:

mkdir -p ~/Documents/TMInterface/Plugins
cp trackmania_rl/tmi_interaction/Python_Link.as ~/Documents/TMInterface/Plugins/

User config

Create a .env file in the project root with machine-specific settings. The file is not tracked in git. Example:

# Username of your ONLINE TMNF account (required)
USERNAME=tmnf_account_username

# Optional overrides (defaults shown):
# BASE_TMI_PORT=8478
# TRACKMANIA_BASE_PATH=%USERPROFILE%/Documents/TrackMania
# TARGET_PYTHON_LINK_PATH=%USERPROFILE%/Documents/TMInterface/Plugins/Python_Link.as
# WINDOWS_TMLOADER_PATH=%LOCALAPPDATA%/TMLoader/TMLoader.exe
# WINDOWS_TMLOADER_PROFILE_NAME=default
# Linux only: LINUX_LAUNCH_GAME_PATH=path_to_be_filled_only_if_on_linux

Warning

Important: Map files and replay files must NOT be stored in OneDrive or other cloud storage directories. Cloud synchronization interferes with the map loading mechanism.