EvoSC Users Guide

Documentation and guides for our server controller EvoSC.

Download & Installation

EvoSC is currently unstable on windows systems and may not work as intended, or at all. Install at your own risk.


The following are the system requirements you will need to install and run EvoSC.


Before starting the preparation, make sure you have all the requirements listed above.

MySQL Database

You will need a MySQL database set up for EvoSC. The following is a simple process for setting up your first database to be used with EvoSC. Make sure you remember or note down your database name and user login info as you will need this later in the setup process. This guide assume you are running EvoSC on the same machine as your MySQL server.

CREATE DATABASE evosc CHARACTER SET UTF8mb4 collate utf8mb4_unicode_ci;
CREATE USER 'evosc'@'localhost' IDENTIFIED BY 'your password';
GRANT ALL PRIVILEGES ON evosc.* TO 'evosc'@'localhost';

(Optional) Dedimania

If you are running a ManiaPlanet server, you might want to set up the Dedimania records widget.

  1. Go to this page and login with maniaplanet: http://dedimania.net/tm2stats/?do=register
  2. Click the Register your dedicated servers button.
  3. Follow the instructions to register your server and note down the DedimaniaCode it gives you.

By default Dedimania will only register any records in the top 30 only. If you want to raise this ceiling you will have to donate to Dedimania, more information can be found here

(Optional) Music Server

The music server provides EvoSC with custom music to be played on the server. For this you will need a web server, either Nginx or Apache will suffice (check requirements above).

  1. If you want to create a directory in your web files of your web server, this is the time to do it.
  2. Go to the directory you made in step1, or just the web root if not.
  3. Download the music server here and extract the zip file.
  4. Note down the URL pointing to the music server. Use this URL later in the installation process.

Installation with git

Git is currently the only way to install and update EvoSC, here is how you do it:

  1. Open the terminal and go to or create a directory where you want EvoSC to be installed.
  2. Clone the repository with git: git clone https://github.com/EvoTM/EvoSC.git
    There are currently two versions of EvoSC. You have the the master or the development branch. The master branch usually contains the most stable version, but the development branch has all the latest changes and features. If you want to use the development branch you can check it out with git checkout develop.
  3. The previous step will create a new directory EvoSC, cd into it: cd EvoSC
  4. Run the composer setup: composer i --no-dev
  5. Start EvoSC for the initial installation process: php esc run
  6. Follow the setup guide which EvoSC provides.

What's Next

To learn more about how the controller works and how you can customize it, check out Getting Started.

Updating Existing Installations

Updating with git

To update an existing installation with git do the following:

  1. Open a terminal and go to the directory of your EvoSC installation.
  2. Enter: git pull
  3. Update composer: composer install --no-dev
  4. Restart EvoSC, you can use the in-game command //restart-evosc and remember that you might have to reset your interface with /reset.

Getting Started

If you have not installed EvoSC already, you can follow this guide.

Bugs, issues or suggestions

If you found a bug or have a issue with EvoSC, please make a report in the Github issues: https://github.com/EvoTM/EvoSC/issues

If you also have a suggestion or improvement to the controller, you can post them there as well. Any other general questions can be asked in our Discord server.

The directory structure

In the EvoSC installation there are three noteworthy directories:

It may happen at times that you would find the cache folder interesting as you may need to clear or modify the cache in order to fix some problems.

Add yourself as master admin

Before you do anything, you may want to add yourself as a master admin so that you have access to all the features in-game. To do this you can run the command:

php esc add:admin YourLoginHere

If you are already on your server, you will have to rejoin for the rights to take effect.

The server configuration

You can find the server configuration in the file config/server.config.json. This file might be useful to know about to edit some the behavior of the controller and connection to the dedicated server. Here are explanation for some of options:

Option Description
login The login of your dedicated server account.
ip The host/IP address of your dedicated server.
port This is the XMLRPC port of your dedicated server.
rpc.login The super admin username of your dedicated server.
rpc.password The super admin password of your dedicated server.
default-matchsettings This is the file that will be the default MatchSettings file of your server.
map-cooldown This option controls how often a map can be played. The numnber indicates how many maps must be played before a map can be played again.
afk-timeout How long a player must stay afk for them to be forced into spectator mode.
echoes.join If enabled, the controller will show player join messages in the chat.
echoes.leave If enabled, the controller will show message of players leaving the server.


Customizing the theme

The file config/theme.config.json contains options for customizing the colors of your EvoSC installation.

All the colors are based on the HTML HEX color format. You can find a color picker that generates these HEX values here.

The colors under the chat option uses a slightly different format. The general text formatting of the Trackmania games uses a three digit hex code instead of six. You can find some colors and read more about it here.


Enabling and Disabling modules

The modules are what gives EvoSC it's features and functionality in general. Every module has a configuration file attached to them. You can find these under the config/ directory.

In a module config file there is always a option called enabled. You can enable a module by setting this to true and disable it by setting it to false.

Adding maps from Trackmania Exchange

You can find a bunch of maps from the exchange websites, there are two exchange websites in concern for this controller:

For Trackmania 2020 use https://trackmania.exchange
For Trackmania 2 use https://mx.mania-exchange.com

You can easily add maps from TMX/MX with the add command. In order to add a map, find your map on the exchange website and note down the Track ID. Then add the map with the command:

//add track-id

Where track-id is the numeric id you noted down.

EvoSC Competition Guide

A guide that shows you how to use EvoSC in competitions.

EvoSC Competition Guide

Useful Commands

Command Example Description
/help   Displays list of commands.
//setpw <password> //setpw myawesomepassword Sets the entry password for the server. Leave empty to clear.
/reset   Resets the interface if it broke.
//mute <player> //mute player Mute player.
//unmute <player> //unmute player Unmute player.
//asay <text> //asay Hello everyone! Displays a big message in the center of the screen. Leave empty to clear. This command can be very useful to gain players attention.
//mode <mode>   Change the game instantly mode.
//ban <player> //ban player Ban and blacklist a player.
//kick <player> //kick player Kick a player from the server.
//addtime <minutes> //addtime 10 Add time to the time attack timer, negative time to remove.
/maps   Open the map list.
/jukebox   Open the jukebox.
//vote <text> //vote Do you like pizza? Start a vote with a custom text.
//skip   Skip to the next map instantly.
//res   Queue the current map for replay.
//add <mx-id> //add 3425 Add a track from Trackmania Exchange.
//addpack <pack-id> //addpack 325 Add all tracks from a map pack from Trackmania Exchange.
//addpoints <points> //addpoints 50 Add points to the points limit, negative number to remove.
//msm   Open the match settings manager where you can load match configurations.
//shuffle   Randomize the current map list order.
EvoSC Competition Guide



Command Example Description
/maps   Open the map list.

Open the jukebox.

//add <tmx id> //add 2352 Add a track from Trackmania Exchange.
//addpack <pack id> //addpack 352 Add all tracks from a map pack from Trackmania Exchange.
//shuffle   Randomize the map order.

Map List