Revenant

Revenant

An AI that teaches itself TrackMania Nations Forever. No recorded runs, no rules about corners. It drives every official level thousands of times and keeps whatever made it faster.

Download Revenant Read the code
  • Free and open source
  • Windows 10 or 11
  • NVIDIA graphics card

Where it's got to

After 93 hours of training on one ordinary gaming PC, an i7-4770 with a GTX 1060, Revenant has finished 40 of the 65 official levels and beaten the author time on 3. Every time below is its own lap.

40of 65 levels finished

3author times beaten

93hours of practice

31.6Msteps driven

Trained offline only. Revenant never plays online, so none of this touches the real leaderboards.

The car

The Stadium car from the game in Revenant's own skin, drawn live in your browser. Drag to turn it, scroll or pinch to zoom. The dashboard installs the skin on a local Revenant profile, so this is what you'll see in game too.

How it learns

It's reinforcement learning: try something, get a score, do more of what scored well. Revenant is built on Linesight and talks to the game through TMInterface.

Twenty times a second the game pauses and Revenant gets a small grey picture of the screen, its speed, which wheels are touching the ground, and where the racing line goes next. It picks one of twelve key combinations. That's all it ever sees or does.

It's rewarded for getting further along the line in less time, and nudged away from walls. At first it drives into the first barrier over and over. A few hours later it's finishing the easy levels, and then it starts shaving off tenths.

  1. Games

    Two copies of TrackMania run at once through TMLoader and TMInterface, which lets Python pause them, read the car and press keys.

  2. Collectors

    One per game. They drive with the newest network and send every finished run back.

  3. Learner

    Keeps recent runs in a replay memory and trains on them on the graphics card. Saves every 5 minutes.

  4. Level loop

    Works through all 65 levels in order, with a separate brain for each one.

What it sees, every 50 ms

  • A 160×120 greyscale picture of the screen
  • Speed, rotation and how fast it's turning
  • Each wheel: on the ground, sliding, and what surface
  • Gear and engine revs
  • Its last 5 key presses
  • The next 400 m of the racing line, as 40 points

What it's scored on

Every metre further along the line+0.01
Every 50 ms that passes−0.06
Every 50 ms touching a wall−0.3
Flipping the steering left to right−0.02
A good speedslide+0.01
Passing a real checkpoint+3

So the way to score the most is to finish as fast as possible without scraping walls. Progress can't go past a checkpoint until the game itself counts it, after it learned to cut past a ring on A01.

One level at a time

Revenant aims for the author time on every level. It stays on a level until it has finished it at least 10 times, had its 150k steps, and then either beaten author or stopped improving for 100k steps. A level it can't finish gives up after 600k steps and gets another go next time round.

Every 5 runs it replays one of its own best laps, and every 20 one from another level, so it doesn't forget how it got fast.

The Levels window: every official level with author medals in teal, gaps to author on finished ones, and levels not reached yet

When it gets stuck

D02 has a hairpin that Revenant hit the wall on for five hours straight. Practising from the start every time meant it barely got any tries at the corner itself.

Lap follower
A spare game builds a lap out of Revenant's own controls, following the record line one 50 ms step at a time and replaying from the start to check every step plays back exactly.
Demo starts
Play that lap up to a random point, then hand Revenant the wheel, so it practises the hard part from a good approach. It finished D02 minutes after these were turned on.
Bruteforce
Randomly tweaks a few inputs of a finished lap and keeps anything faster. It took A07 from 26.52 to 26.51.
The Run tab in Revenant's controls, with demo starts, the lap follower and bruteforce

The full write-up, with every setting, is in HOW_IT_WORKS.md

What it can do

Everything it took to get Revenant this far comes with it.

Learning

  • Works through every official level in order, aiming for author on each
  • A separate brain per level, so coming back carries on where it stopped
  • Focus on one level until it beats a time you choose
  • Wall penalties, a speedslide reward and checkpoint gates tuned for Trackmania
  • Replays its best laps so it doesn't forget them

Getting unstuck

  • Lap follower that builds exact, replayable laps from the record line
  • Demo starts from any point along that lap
  • Bruteforce to shave time off a finished lap
  • Turns any lap into a video and a TMInterface .inputs file

Running it

  • Benchmarks your PC and picks settings to suit it
  • Stops safely, it waits for a save so nothing's lost
  • Plays as its own local Revenant profile, no online account
  • Clicks new games past the profile screen so long runs carry on without you
  • Every training setting editable while it runs

One window runs all of it

The dashboard sets everything up, starts and stops training, shows every lap as it happens, and draws the fastest one on the map, coloured by speed.

The Revenant dashboard showing lap times, finish rate, wall touches and the fastest lap on the D02 map

The controls

The Setup tab with a checklist of everything Revenant needs

Checks the game, TMLoader, the TMInterface plugin, the official maps, the trained models, the Revenant profile, network ports and the benchmark. Anything missing gets a button, and Fix everything I can does the ones that don't need you.

Run it yourself

You need Windows 10 or 11, an NVIDIA card with 4 GB or more, and TrackMania Nations Forever, which is free on Steam.

  1. Download

    Grab the code from GitHub. Out of the box it learns from nothing. For the trained Revenant, also get the zips from the latest release.

  2. Open Revenant.bat

    The first time, it installs Python 3.11 if you need it and the AI's libraries, about 3 GB. After that it opens straight to the dashboard.

  3. Follow the Setup tab

    It checks the game, the mod loader, the maps and your PC, with a button next to anything missing. Then press Start on the Run tab.

Download Revenant Source zip

Fresh or pretrained

The code has no trained data in it, so a fresh copy learns every level from scratch, the same way Revenant did. That takes days before it's finishing levels. Everything Revenant has learned is on the v1.0 release.

FileWhat's in itSize
revenant_core.zipThe main brain and its training progress49 MB
revenant_levels_A.zip to D.zipOne brain per level it's trained on1.15 GB
revenant_laps.zipThe D02 demo lap and the bruteforced A07 lap1 KB

Put them in a models folder next to Revenant.bat and press Install next to Trained models on the Setup tab. It carries on from exactly where Revenant is.

What you need

MinimumRevenant's PC
GraphicsNVIDIA, 4 GB, GTX 10 series or newerGTX 1060 6GB
CPU4 threadsi7-4770
RAM8 GB12 GB
Disk10 GB free
SystemWindows 10 or 11Windows 11

RTX 50 series cards need a newer PyTorch than the AI is pinned to, so they won't work yet. AMD and Intel graphics can't run it, it needs CUDA.

If something goes wrong

Start with the Setup tab, most problems show up there with a button next to them. These are the others that came up.

My antivirus deleted or blocked TMLoader

TMLoader injects into the game, which looks suspicious to antivirus programs, but it's a false positive. Add %LocalAppData%\TMLoader as an exception.

Revenant.bat closes straight away

Run powershell -ExecutionPolicy Bypass -File .\setup.ps1 so you can read the error. It's usually no internet (it downloads about 3 GB) or winget missing on old Windows 10, in which case install Python 3.11 from python.org yourself.

Training stops with "CUDA error: out of memory"

Something else used the graphics memory, usually Discord, the Xbox Game Bar, a browser or a game. Close them and start again, or lower the batch size or number of games on the Machine tab.

The games stay on "Select your Profile"

The clicker presses the Revenant row about 25 seconds after a game opens. Check the Profile tab says Now driving as: Revenant, delete profiles you don't use if the list scrolls, and look at logs/auto_click.log.

The games open fullscreen

Run TmForeverLauncher.exe in the game folder once, choose windowed mode and save.

The dashboard says "Stalled"

The training log hasn't changed for 10 minutes, usually a frozen game or one stuck on a dialog. Use Stop now, close any games still open and start again. It carries on from the last save.

It's stuck at the same point on a level for hours

Start the lap follower on that level, then demo starts with a step range a bit before the hard part, and set focus to that level so the loop stays there.

Does it play online?

No. It trains offline on its own local profile, so none of its times touch the real leaderboards.

Everything else is in TROUBLESHOOTING.md

Why it exists

Me and a friend wanted to see if it was possible to build a Trackmania AI that teaches itself to beat author times, with Claude Opus 5.5 doing the coding, debugging and testing while I steered it. It turns out it is.

Thanks to

  • Unnamed477, for his own runs of the levels, which Revenant learned its best lines from.
  • The Linesight team, whose AI Revenant is built on.
  • donadigo for TMInterface and Tomashu for TMLoader.
  • TMX for the record replays.