Difference between revisions of "Web API"
(fix wording, spelling, punctuation) |
m (→Basic concepts: Added "sd" and lang "xx" into Request) |
||
Line 20: | Line 20: | ||
<distro>MOLUX</distro> | <distro>MOLUX</distro> | ||
<lang>fr</lang> | <lang>fr</lang> | ||
+ | <sd>2011-02-21</sd> <!-- Only sent by server, see below --> | ||
</game> | </game> | ||
<author> | <author> | ||
Line 43: | Line 44: | ||
*** '''version''' Version of the client. | *** '''version''' Version of the client. | ||
*** '''distro''' Unknown. Set to MOLUX for TMNF or TAHOR for TMUF. | *** '''distro''' Unknown. Set to MOLUX for TMNF or TAHOR for TMUF. | ||
− | *** '''lang''' Language of the client, as ISO 639-1. | + | *** '''lang''' Language of the client, as ISO 639-1. Server sets it to "xx". |
+ | *** '''sd''' Date as YYYY-MM-DD, only sent by server. Maybe server's release date? | ||
** '''author''' ''See [[#Author]]''. | ** '''author''' ''See [[#Author]]''. | ||
** '''request''' | ** '''request''' |
Revision as of 15:34, 30 May 2019
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
- http://game.trackmaniaforever.com/online_game/request.php
- http://game2.trackmaniaforever.com/online_game/request.php
- http://nations.trackmaniaforever.com/online_game/request.php
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> <sd>2011-02-21</sd> <!-- Only sent by server, see below --> </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. Server sets it to "xx".
- sd Date as YYYY-MM-DD, only sent by server. Maybe server's release date?
- 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.
- game
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.
- r
Functions calls
GetConnectionAndGameParams
Gets a lot of information. First request sent by client.
Session required? | Parameters | Response |
---|---|---|
No (Empty) |
|
|
AddBuddy
Adds a player to the friends list.
Session required? | Parameters | Response |
---|---|---|
Yes |
|
|
List of seen error codes:
ID | Meaning |
---|---|
14 | Unknown username |
143 | You must wait before adding back a deleted friend |
CheckLogin
Checks if login is already used for account creation.
Session required? | Parameters | Response |
---|---|---|
No (Set to 1) |
|
|
MailAccount
Requests the server to send a password recovery email.
Session required? | Parameters | Response |
---|---|---|
No (Empty) |
|
Empty response |
Disconnect
Closes connection.
Session required? | Parameters | Response |
---|---|---|
Yes |
Empty parameters |
Empty response |
GetBuddies
Gets the friends list.
Session required? | Parameters | Response |
---|---|---|
Yes |
|
Left to document
|
GetManialinkInfos
Gets info about a manialink.
Session required? | Parameters | Response |
---|---|---|
Yes |
|
|
GetManialinkResource
Gets info about a maniacode.
Session required? | Parameters | Response |
---|---|---|
Yes |
|
|
GetOnlineProfile
Gets info about the player.
Session required? | Parameters | Response |
---|---|---|
Yes |
|
A lot is left to document here
|
GetLeagues
Gets the regions list.
Session required? | Parameters | Response |
---|---|---|
No (Set to 1) |
Empty parameters |
|
OpenSession
Gets a session ID.
Session required? | Parameters | Response |
---|---|---|
No (Set to 1) |
|
|
k is hard-coded in the game's binary. One value has been seen, both for United and Nations:
MIGdMA0GCSqGSIb3DQEBAQUAA4GLADCBhwKBgQCpBgX3c4ezM18RiGPlQiVKINu+JicxOd6yuHl5q30 00CdTLu53A3ceuelum2+ui+MmASL3JjmVVOoNURvK7GCt79wLUUSbtTaZPXPr73TioZBCVkPd8chAb8 EurZtlDp5QQvDCaoCfFJ4V8VJgM0IK0qVIHRP+D03tKgb2WOgK9QIBEQ==
RemoveBuddy
Removes a player from the friends list.
Session required? | Parameters | Response |
---|---|---|
Yes |
|
Empty response |
ReceiveMessages
Checks for messages.
Session required? | Parameters | Response |
---|---|---|
Yes |
|
|
RequestAllowed
Checks if a request is allowed.
Session required? | Parameters | Response |
---|---|---|
Yes |
|
|
SendMessages
Sends a message to a player.
Session required? | Parameters | Response |
---|---|---|
Yes |
|
|
Subscribe
Registers a new account. Warning: This is sent over HTTPS.
Session required? | Parameters | Response |
---|---|---|
No (Set to 1) |
|
|
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).
- k One remote call (multiple of them in the j tag)
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.