TrackMania Server - readme

# TrackMania Dedicated Server

    (PATH)\TrackManiaServer.exe
                            [/dedicated_cfg=config_file]
                            [/game_settings=settings_file]
                            [/internet]

## Notice

You'll find many useful tools and tutorials on TM-FORUM.

## 1.INSTALLATION:

Decompress the zip file in a directory to install TrackMania Dedicated Server.
It can be installed either in the same directory of TMUnited game, or in another directory.

Note: In order to run, you need,
- the server exe
- the GameData/DedicatedTrackMania.TrackMania.gbx file
- any challenges / matchsettings you want to play in the GameData/Tracks directory
- a dedicated_cfg.txt file to set some parameters.

## 2.LAUNCH:

The dedicated server can be run from a windows shortcut or from a command line prompt.

The format of the command line is:

    "{PATH}\TrackManiaServer.exe" [/dedicated_cfg=config_file] [/game_settings=settings_file] [/internet]

If you use a windows shortcut, you can modify its properties to configure the launch of the server on the same way.
The target of the shortcut properties (first field) shares the same format of the command line.
So it will eventually have to look like this:

    TrackManiaServer.exe /internet /dedicated_cfg=dedicated_cfg.txt /game_settings=MatchSettings/settings.txt

The working directory of the shortcut must also be set to the right directory.
It must correspond to the directory where TrackManiaServer.exe has been installed.

The dedicated server can be launched with or without a configuration file.
To pass the name of the configuration file to the dedicated server, the parameter '/dedicated_cfg=' must be specified followed by the name of the file.
This filename can be defined either by an absolute path or by a relative path to the '(PATH)\GameData\Config' directory.
The configuration file is an xml file which defines some basic parameters for the dedicated server.
See below for further details on configuration file.

A file containing game settings can also be specified to the dedicated server.
To do that the parameter '/game_settings=' must be defined followed by the name of the file.
This filename can be defined either by an absolute path or by a relative path to the '(PATH)\GameData\Tracks' directory.
The game settings file is an xml file which defines the match settings and a playlist of challenge that will be loaded.
See below for further details on game settings file.

If the server has been launched with a valid configuration file and a valid game settings file, it will directly start a new server on lan,
or on Internet if the option '/internet' is specified.

TrackManiaServer can be launched at the same time that the retail version of TMUnited, but they cannot share TCP and UDP ports.
That's why it is recommended to launch the dedicated server before the game, so the dedicated server can use the default ports.

Other options that can be specified to the dedicated server, are:

/dedicated_cfg=config_file | Specify a configuration file to use.
/game_settings=settings_file | Specify a game settings file to use.
/internet | Specify to the server that it must connect to the master server, in order to be an Internet server.
/verbose_rpc | Display the XmlRpc requests the dedicated server receives. The server will only display the name of the XmlRpc command and some parameters.
/verbose_rpc_full | Display the whole contents of the XmlRpc requests the dedicated server receives.
/nodaemon | (linux) Doesn't detach the process.
/nologs | disable the creation of "GameLog.txt" and "ConsoleLog.txt"
/login=xxx | Masterserver account (overrides the value from the config_file)
/password=xxx | Masterserver account (overrides the value from the config_file)
/servername=xxx | name of the server to create. (overrides the value from the config_file)
/serverpassword=xxx | password to join the server. (overrides the value from the config_file)
/loadcache | loads the "checksum.txt" instead of recomputing it. *DO NOT USE* if you run several servers in the same directory!
/forceip=xxx(:xx) | Forces the public ip address to this value (overrides the value force_ip_address from the config_file)
/bindip=xxx(:xx) | Choses the ip to bind to, and sets the public ip to this value. (you still can use /forceip to chose a different public ip)
/autoquit | If the server is not "live" (with a map loaded and ready to receive player), exit. Most notably, if there is a configuration error that prevent the server to be successfully launched, quit instead of staying in the "waiting for rpc commands" state.

## 3.CONTROL:

After being launched (with or without configuration files), the server can be also configured and controlled by rpc calls. (rpc= remote procedure call)
An external application can use any xmlrpc library to communicate with the dedicated server.

Some calls are only permitted to certain authorization level. There are three authorization levels (User, Admin and SuperAdmin),
each one having an associated password (by default the same as the level name).
The 'Authenticate' method can be used to switch to a specified level.

The list of methods that can be called by xmlrpc can be found in the ListMethods.html file.

Some samples are available in the RemoteControlExamples/ directory:

Please note that the examples provided are rather outdated.
More up to date and actually useful applications to control the TrackMania Server, can be found on http://www.tm-forum.com/ .

- In RemoteControlExamples/PhpRemote/
there is a basic.php script file that allows basic control of the dedicated server.
To use it, a web server must be installed on the same computer as the Trackmania server.
Any web server supporting PHP can be used, as the free web server Apache (www.apache.org) or EasyPHP a software package including Apache, PHP and MySQL (www.easyphp.org).

- In RemoteControlExamples/GameController.Net/
This is aimed at developers. It contains a slightly modified version (that supports connecting to TrackMania) of the Xml-RPC.Net library, from http://www.xml-rpc.net

- In RemoteControlExamples/c/xmlrpc-c
This is aimed at developers, it is the XmlRPC-c v1.03.11 library modified to support connecting to TrackMania. (from http://xmlrpc-c.sourceforge.net/ )
It also includes examples/xmlrpc_sample_trackmania.c : a small example of how to use the library, including a simple version and a more complete example with callbacks from the game.

## 4.CONFIGURATION FILE:

The configuration file is an xml file which defines some parameters like the system configuration of server (IP address, ports...), passwords for the three authorization levels,
The master server account parameters that can be used for the launch of the dedicated server on Internet, and other server parameters (name, comment, password, max players/spectators...).

You can find an example of configuration file (dedicated_cfg.txt) in the TrackManiaServer root directory.
Here is what it contains by default:

    <?xml version="1.0" encoding="utf-8" ?>
    <dedicated>
        <authorization_levels>
            <level>
                <name>SuperAdmin</name>
                <password>SuperAdmin</password>
            </level>
            <level>
                <name>Admin</name>
                <password>Admin</password>
            </level>
            <level>
                <name>User</name>
                <password>User</password>
            </level>
        </authorization_levels>

        <masterserver_account>
            <login></login>
            <password></password>
        </masterserver_account>

        <server_options>
            <name></name>
            <comment></comment>

            <max_players>32</max_players>
            <password></password>

            <max_spectators>32</max_spectators>
            <password_spectator></password_spectator>

            <ladder_mode>forced</ladder_mode>     <!-- value between 'inactive', 'forced' (or '0', '1') -->

            <enable_p2p_upload>True</enable_p2p_upload>
            <enable_p2p_download>True</enable_p2p_download>

            <callvote_timeout>60000</callvote_timeout>
            <callvote_ratio>0.5</callvote_ratio>

            <allow_challenge_download>True</allow_challenge_download>
            <autosave_replays>False</autosave_replays>
        </server_options>

        <system_config>
            <connection_uploadrate>512</connection_uploadrate>	<!-- KBps -->
            <connection_donwloadrate>8192</connection_donwloadrate>	<!-- KBps -->

            <force_ip_address></force_ip_address>
            <server_port>2350</server_port>
            <server_p2p_port>3450</server_p2p_port>
            <client_port>0</client_port>
            <bind_ip_address></bind_ip_address>
            <use_nat_upnp></use_nat_upnp>

            <xmlrpc_port>5000</xmlrpc_port>
            <xmlrpc_allowremote>False</xmlrpc_allowremote>	<!-- If you specify an ip adress here, it'll be the only accepted adress. this will improve security. -->

            <blacklist_url></blacklist_url>
            <guestlist_filename></guestlist_filename>
            <blacklist_filename></blacklist_filename>

            <use_proxy>False</use_proxy>
            <proxy_login></proxy_login>
            <proxy_password></proxy_password>
        </system_config>
    </dedicated>

The first block of parameters (<authorization_levels>...</authorization_levels>) allows to define passwords for the three authorization levels.

- SuperAdmin has all rights on the dedicated server. It can call any request, start and stop server, quit the application.
  It is recommended to change this password, and to not give it to any other person.

- Admin can be used to manage a launched server, but cannot neither stop or start server, nor quit the application. Admin password can be given to a group of users to facilitate the remote management of a dedicated server.

- User can only access to 'get' requests, so it is not necessary to change this password.

The second block of parameters (<masterserver_account>...</masterserver_account>) is used for the connection to master server of the dedicated server.
To allow the server to connect to master server, a login and password, that identify the dedicated server, must be specified.

This account has to be created beforehand.
To do that, visit: https://www.trackmania.com/tmu-dedicated/

There you must enter your multiplayer key to connect to the account creation site.

After that, you can create/modify accounts for dedicated server.

Game player accounts and dedicated server accounts are distinct.

The login and password of a game player account can also be used in the 'masterserver_account' block, instead of parameters from a dedicated server account.
But in this case the player cannot connect to Internet with his game, because his account is already used by the dedicated server.

The third block of parameters (<server_options>...</server_options>) defines the main parameters that will be used by the dedicated server.
The settings are :

name | name of the dedicated server (must be specified for the game to launch)
comment | comment of the dedicated server
password | password needed at the connection to the dedicated server as player
password_spectator | password needed at the connection to the dedicated server as spectator
max_players | maximum number of clients that can join the server as player
max_spectators | maximum number of clients that can join the server as spectator
ladder_mode | ladder mode. The mode can be defined between these values : 'inactive' (0), and 'forced' (1)
enable_p2p_upload | value indicating if the server can upload custom data for P2P (0=False, 1=True)
enable_p2p_download | value indicating if the server can download custom data for P2P (0=False, 1=True)
callvote_timeout | timeout for waiting for votes (value in milliseconds)
callvote_ratio | ratio for accepting callvote. The value must lie between 0 and 1 (0=0%, 1=100%)
allow_challenge_download | value indicating if the server allows clients to download challenge (0=False, 1=True)
autosave_replays | value indicating if the server should save all the races replays with all players. (the replays are quite low quality, though)

The fourth block of parameters (<system_config>...</system_config>) defines the system configuration of the server.
For example it allows to define the type of network connection used, the different ports used by the dedicated server, or an IP that will be published on the master server.
The settings are :

connection_uploadrate / connection_downloadrate | type of network connection used. It defines the network limitations of bandwidth in KBps that can be used by the dedicated server,
server_port | port number used by the server to listen the game connections
server_p2p_port | port number used by the server to listen the peer-to-peer connections
xmlrpc_port | port number used by the server to listen xmlrpc calls
xmlrpc_allowremote | should remote connections be accepted? You can either set it to True or False, or specify an ip (or a symbolic name): in that case, only connections from that ip and localhost will be accepted. (note: security on this channel isn't very strong and hasn't been thoroughly tested)
force_ip_address | if an IP address is defined in this parameter, the dedicated server will publish it as its public address instead of autodetecting it.
bind_ip_address | if an IP address is defined in this parameter, the dedicated server will bind to this ip and publish it as public ip, expect if force_ip_address is also specified.
blacklist_url | if an url is specified here, the dedicated server will check if there is an xml file that can be downloaded, and in this case if it's a blacklist file. If it is the case this blacklist will automatically loaded for this server

## 5.GAME SETTINGS FILE:

A game settings file is an xml file which defines the match settings like chat time, game mode, mode parameters, and a playlist of challenges that will be loaded.

You can find examples of game settings files in the (PATH)\GameData\Tracks\MatchSettings\ directory, and you can save one from within the game, “save settings” button.

Here is what it contains:

    <?xml version="1.0" encoding="utf-8" ?>
    <playlist>
        <gameinfos>
            <game_mode>1</game_mode>
            <chat_time>10000</chat_time>
            <finishtimeout>1</finishtimeout>
            <rounds_pointslimit>50</rounds_pointslimit>
            <rounds_usenewrules>0</rounds_usenewrules>
            <rounds_forcedlaps>0</rounds_forcedlaps>
            <timeattack_limit>300000</timeattack_limit>
            <timeattack_synchstartperiod>0</timeattack_synchstartperiod>
            <team_pointslimit>5</team_pointslimit>
            <team_maxpoints>6</team_maxpoints>
            <team_usenewrules>0</team_usenewrules>
            <laps_nblaps>5</laps_nblaps>
            <laps_timelimit>0</laps_timelimit>
        </gameinfos>
        <filter>
            <random_map_order>0</random_map_order>
        </filter>

        <challenge>
            <file>Campaigns\Nadeo\Sunrise\Race\Holidays\CarPark.Challenge.Gbx</file>
        </challenge>
        <challenge>
            <file>Campaigns\Nadeo\Sunrise\Race\Holidays\GoodMorning.Challenge.Gbx</file>
        </challenge>
          .
          .
          .
        <challenge>
            <file>Campaigns\Nadeo\Sunrise\Race\Pointbreak\HappyBay.Challenge.Gbx</file>
        </challenge>
    </playlist>

The first block of parameters (<gameinfos>...</gameinfos>) defines the match settings that will be used by the dedicated server.
The settings are :

game_mode | game mode used between Rounds (0), TimeAttack (1), Team (2), Laps (3) and Stunts (4)
chat_time | chat time value in milliseconds
rounds_pointslimit | points limit for rounds mode
rounds_usenewrules | value indicating if new rules are used for rounds mode (0=False, 1=True)
timeattack_limit | time limit in milliseconds for time attack mode
team_pointslimit | points limit for team mode
team_maxpoints | number of maximum points per round for team mode
team_usenewrules | value indicating if new rules are used for team mode (0=False, 1=True)
laps_nblaps | number of laps for laps mode
laps_timelimit | time limit in milliseconds for laps mode
finish_timeout | new finish timeout (for rounds/laps mode) value in milliseconds. 0 means default. 1 means adaptative to the duration of the challenge
rounds_forcedlaps | number of laps for rounds mode (0 = default, use the number of laps from the challenges, otherwise forces the number of rounds for multilaps challenges)
timeattack_synchstartperiod | synchronised start period for time attack mode

<random_map_order>..</random_map_order> : shuffle the list of challenges when the playlist is loaded. if not set, keep the playlist in the specified order.

Other blocks (<challenge>...</challenge>) describe all the challenges that will be loaded by the dedicated server.
Each block specifies the filename of a challenge.
Filenames can be defined either by an absolute path or by a relative path to the '(PATH)\GameData\Tracks' directory.

Any other elements in the file are ignored by the dedicated server.

Game settings file can be saved by the game with the 'save match settings' button in the server creation menu, after having selected the maps.
The files saved by the game are in the '(PATH)\GameData\Tracks\MatchSettings' directory.
So the relative designation for a such file is 'MatchSettings/settings_file.txt', where 'settings_file.txt' is the name of the saved file.

As a general rule, the challenges and matchsettings must always be in the directory "GameData/Tracks", and any relative name is interpreted using the "GameData/Tracks" as root.

## 6.GUESTLIST FILE:

A guestlist file "guestlist.txt" can be created in the GameData repertory, and will be automatically loaded by the game or server.
A player on the guest list is allowed to enter into the server in any case, even if there is no player slot left, and without needing to specify the password.

The guestlist file is an xml file as follows :

    <?xml version="1.0" encoding="utf-8" ?>
    <guestlist>
        <player>
            <login>Login1</login>
        </player>
        .
        .
        .
        <player>
            <login>LoginN</login>
        </player>
    </guestlist>

## 7.BLACKLIST FILE:

A blacklist file "blacklist.txt" can be created in the GameData repertory, and will be automatically loaded by the game or server.
A player on the black list will never be able to enter onto the server.

The blacklist file is an xml file as follows :

    <?xml version="1.0" encoding="utf-8" ?>
    <blacklist>
        <player>
            <login>Login1</login>
        </player>
        .
        .
        .
        <player>
            <login>LoginN</login>
        </player>
    </blacklist>

## 8. KNOWN ISSUES

- On the command you can't use names with ' ' in them, since the options are separated on whitespace, and no escaping (neither '\ ' nor '"') is supported...
- (linux only) the server expects the file names to be utf-8 encoded. So pay attention if you're using non-ascii characters.

## 9.CHANGELOG

2007-02-23:
- bugfix: no longer autoban players in timeattack with multilaps...
- bugfix: repaired the stunts mode scores.
- bugfix: the replays produced by the server are no longer broken.

2007-02-20:
- The server now reattemps to connect to the master server when the connection is broken. (should fix the problem where the server was runnning and wasn't in the list for the players.)
- Detection of incoherence in the players time and race -> automatic ban of the player.
- New callback TrackMania.PlayerIncoherence(PlayerUid, PlayerLogin) for this event
- Modification of ForceScores(): new parameter SilentMode (only available for SuperAdmin), allowing an external controller to do it's custom score counting.

2007-01-09:
- GetVersion() now returns "TmUnited" instead of "TmUnited."
- GetSystemInfo() call, returns IP, ports, and server login
- fixed a crash
- AllowChallengeDownload() is now applied during the game.
- faster launchtime (the "loading..." step was doing useless work)
- When removing a challenge and inserting it back again, it is now read afresh from disk.
- When saving a matchsetting, the filter::random_map_order is remembered.

2006-12-21:
- setting, in order to save all replays occuring on the server. (albeit in low quality.)
- GetCoppers() call
- bugfixes (crash, Pay() return code, ...)

2006-12-07:
- Billing system, to make copper transactions with players. (=> SendBill(), Pay(), GetBillState() )
- ChatSendToLanguage(), ChatSendServerMessageToLanguage()
- ForceSpectator(), ForceSpectatorId()
- ForcePlayerTeam(), ForcePlayerTeamId()
- BlackListId(), AddGuestId(), RemoveGuestId()
- DisplayManialinkPage: you can now add a parent <ManiaLinks> element in order to have several <ManiaLink> with their positions.
- Sending Chat to a player also displayed the chat to the spectators looking at him.
- GetManialinkPageAnswers() no longer crashes.
- You can now display ManialinkPages to each players, and get all the answers..
- Sometimes the name of the challenge was incorrect.
- the server can now act as a P2P relay, if the peers don't accept incomming connections.