Troubleshooting

Common Issues

Game stuck on login screen:

The TMNF account must be an online account. If your account is offline:

  • Start the game without TMInterface and create an online account

  • Set your USERNAME in the .env file to that online account

FileNotFoundError: Python_Link.as

The plugin wasn’t copied to the correct location. Run:

# Windows
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\Documents\TMInterface\Plugins"
Copy-Item "trackmania_rl\tmi_interaction\Python_Link.as" "$env:USERPROFILE\Documents\TMInterface\Plugins\"

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

CUDA not available

  1. Ensure NVIDIA driver 525+ is installed: nvidia-smi

  2. Check PyTorch installation: python -c "import torch; print(torch.cuda.is_available())"

  3. Reinstall PyTorch: uv sync --reinstall or follow PyTorch installation guide

TorchRL warning about C++ binaries

Ensure you’re using PyTorch 2.7+ with matching TorchRL version. The uv sync command installs compatible versions automatically.

Map not loading

  • Ensure map files are NOT in OneDrive or cloud storage directories

  • Verify map path in the map_cycle.entries section of your config YAML matches actual location

  • Check that map file exists in ~/Documents/TrackMania/Tracks/Challenges/

Low FPS / Slow training

  • Increase gpu_collectors_count in the performance section of the config YAML

  • Increase running_speed (up to 200x real-time)

  • Lower game graphics settings and resolution

  • Close unnecessary background applications

Memory issues

  • Reduce memory_size_schedule in the memory section

  • Reduce gpu_collectors_count in the performance section

  • Reduce batch_size in the training section

  • Check RAM usage with Task Manager / htop

Agent gets stuck or doesn’t progress

  • Verify virtual checkpoint file (.npy) is correctly generated

  • Check cutoff_rollout_if_no_vcp_passed_within_duration_ms timeout

  • Increase exploration (higher epsilon in the exploration section)

  • Verify reference line covers the entire track

Cars stop moving during training (Window Focus Issue) 🆕

Symptoms: Cars “twitch” at start but don’t move forward. Clicking on a window makes it work again.

Cause: TMInterface requires window focus to process inputs, even with unfocused_fps_limit false.

Solution: This is now automatically fixed in the code. The game window receives focus once per map load, which is sufficient. No manual intervention needed.

Technical details:

  • Window focus is set automatically when loading a new map

  • For multiple instances (8+), focus is managed to avoid “focus war”

  • Minimal performance impact (<0.01%)

  • Works correctly with map cycling

If issue persists:

  1. Check that windows are not minimized (game pauses when minimized)

  2. Verify force_window_focus_on_input: false in the performance section of the config YAML

  3. With multiple maps, ensure smooth transitions between maps in logs

Game crashes on startup

  • Check TMLoader profile is correctly configured

  • Verify TMInterface 2.1.0 is installed

  • Try launching game manually first to verify it works

  • Check Windows firewall isn’t blocking TMLoader/TMInterface

Linux-specific:

Linux installation checklist: This list is not exhaustive. It contains the main setup steps the authors use on their machine. It may need to be adapted for your own machine.

  1. Update winehq-staging

  2. Download Steam. Install TMNF from Steam

  3. Check that the game can be launched with wine TmForever.exe from the installation directory

  4. Download the ModLoader zip file, made available on Tomashu’s website for linux setups

  5. wine TMLoader.exe to configure the default profile

  6. Check that the game runs with: wine ~/path/to/TMLoader-win32/TMLoader.exe run TmForever “default” /configstring=”set custom_port 8483”

  7. Modify launch_game_pb.sh in the repository with the path to ModLoader on your system

  8. Install winetricks. Apply winetricks dxvk for performance.

Missing OpenAL32.dll

Install OpenAL with wine.