Web API

The TrackMania Forever game client uses a XML-RPC based web API to communicate with the master server. This article attempts to document the API with the potential goal of eventually having a fully functional custom master server.

Basic concepts

TrackMania uses a XML-RPC based API to authenticate players, load server lists, load rankings, etc. Below is some documentation about what has been reversed engineered. A lot is still left to be documented, as logged on the Progress page.

The game sends HTTP(s) POST requests to

to communicate with the API, using the headers: User-Agent: GameBox and Accept: */*

Request

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <game>
    <name>TmForever</name>
    <version>2.11.16</version>
    <distro>MOLUX</distro>
    <lang>fr</lang>
  </game>
  <author>
    [...]
  </author>
  <request>
    <name>[...]</name>
    <params>
      [...]
    </params>
  </request>
  <auth>
    <value>[...]</value>
  </auth>
</root>

Here is a description of the xml:

root
- game
  - name The client you are using. Known values: TmForever
  - version Version of the client.
  - distro Unknown. Set to MOLUX for TMNF or TAHOR for TMUF.
  - lang Language of the client, as ISO 639-1.
- author See #Author.
- request
  - name Name of the requested function.
  - param Parameters for the call.
- auth Optional. Only seen on Connect and Disconnect.
  - value Looks like an auth ticket.

Author

The author tag identifies the user sending the request. In this documentation, three cases are possible for the author tag:

The method doesn't require authentication (denoted as "No (Empty)"), the author tag is filled with following content:
```
<login/>
<session/>
```
The method requires user name (denoted as "No (Set to 1)"), the author tag is filled with following content:
```
<login>the user's name</login>
<session>1</session>
```
The method requires authentication (denoted as "Yes"), the author tag is filled with following content:
```
<login>the user's name</login>
<session>the session's id</session>
```

Response

<?xml version="1.0" encoding="UTF-8"?>
<r>
  <r>
    <n>[...]</n>
    <c>
      [...]
    </c>
  </r>
  <e>execution time : 0.0010 s</e>
</r>

Here is a description of the returned xml:

r
- r
  - n The name of the called function.
  - c The returned data.
- e A string giving the execution time.

Functions calls

GetConnectionAndGameParams

Gets a lot of information. First request sent by client.

Session required?	Parameters	Response
No (Empty)	dedicated Set to 0 with TMF. Purpose is unknown. Maybe for servers. download Max P2P download speed, as set in game config, in B/s. upload Max P2P upload speed, as set in game config, in B/s.	a Same as a from #RedirectOnMasterServer.

CheckLogin

Checks if login is already used for account creation.

Session required?	Parameters	Response
No (Set to 1)	l Player login.	e Set to 1 if login is used, otherwise 0. p ?. Set to 0.

MailAccount

Requests the server to send a password recovery email.

Session required?	Parameters	Response
No (Empty)	login Player login.	Empty response

Disconnect

Closes connection.

Session required?	Parameters	Response
Yes	Empty parameters	Empty response

GetLeagues

Gets the regions list.

Session required?	Parameters	Response
No (Set to 1)	Empty parameters	l Multiple of them, one per region a Region name. b Parent regions (separated with "\|", eg. "France\|Alsace"). i An URL pointing to the region's flag (dds).

OpenSession

Gets a session ID.

Session required?	Parameters	Response
No (Set to 1)	cr 8 characters random hex value.	i Session ID. s ?. Seems Hexadecimal. k ?. Base64 encoded.

Subscribe

Registers a new account. Warning: This is sent over HTTPS.

Session required?	Parameters	Response
No (Set to 1)	pw Password for the account. ik ?. Seems caps hexadecimal. email Supplied email. cp ?. Empty np Region. an If the user accepts to receive Nadeo news on his email address.	s Game key associated with the account.

RedirectOnMasterServer

This response happens sometimes. It tells the client to switch auth server. When received, the client sends same request it just sent, but to the other server specified.

Here is a description of the response:

a
- b Name of the game.
- c New server address to use.
- d Endpoint (generally online_game).
- e HTTPS port.
- f HTTP port.
- g Base region (World).
- h ?. Set to 1
- i ?. Set to 1
- j (Maybe) List of authorized/available remote methods (described below), or permissions.
  - k One remote call (multiple of them in the j tag)
    - l Method/Permission name.
    - q Might be if authorized/available or not (seems always 1).

Here is a list of the methods that have been seen in k:

AddCustomChallenge
AddResults
CheckServerPassword
Connect
ConvertAccount
CreateGroup
Disconnect
GetChallenge
GetChallengeFromUId
GetManialinkResource
GetReplay
MoveFromLeague
PayCoppersTransaction
SLiveUpdate
SendMessages
ShareChallenge
StartOfficialRecord
StopOfficialRecord
Subscribe
SubscribeToGroup
UnsubscribeFromGroup
UpdateOnlineProfile
UploadOfficialRecord
ValidateSoloAccount

How to help

Use a packet analyzer to see the game's communication while experimenting with client features, and describe requests and responses in as much detail as possible.