SuperTuxKartSuperTuxKart Server config.xml Explained (All Key Options)
What each key SuperTuxKart server config.xml option does: server-mode numbers, difficulty, players, password, voting, owner-less, ranked and MOTD.
Updated Oct 7, 2026 · 8 min read
On this page
A SuperTuxKart server keeps its settings in the XML file passed with --server-config (often config.xml or server_config.xml), a <server-config version="6"> file with one <option value="..."/> line per setting. The options that shape a lobby most are server-mode, server-difficulty, server-max-players, private-server-password, track-voting, owner-less and motd. Edit values only while the server is stopped, keep the XML valid, and remember that command line options such as --mode or --max-players override the file at every start.
This walk through uses the file format from SuperTuxKart 1.5 as documented in the official NETWORKING.md.
Before you edit: two ways to lose your changes
Broken XML gets replaced. If the server cannot parse the file, it logs Could not read server config file '...'. A new file will be created. and writes a fresh one with defaults over yours. A missing quote or a stray < is enough. Keep a copy before editing.
Old versions get replaced too. If the version attribute is outside what the binary accepts, it logs Your config file was not compatible, so it was deleted and a new one will be created. Version 6 is current for the 1.x releases.
The command line wins. The server loads the XML first, then applies --lan-server, --wan-server, --mode, --difficulty, --max-players, --motd, --port and the other flags on top. If a value in the file seems ignored, check the start command.
Identity and connection
<server-name value="STK Server" />
<server-port value="0" />
<wan-server value="true" />
<private-server-password value="" />
<motd value="" />
server-name: the lobby name players see.--lan-server=Nameor--wan-server=Namereplaces it. Encode non ASCII characters as XML entities.server-port: 0 means the default from the game data, which is UDP 2759. If the port cannot be bound, STK switches to a random port on its own.wan-server: true registers the server with the online list and needs a saved STK account.--lan-serverforces it to false.private-server-password: empty means public. Players are asked for it when they join.motd: message in the lobby. It accepts text or the name of a .txt file, which is handy for a list of rules.
server-mode numbers
This is the setting that trips people up, because the XML numbers differ from the --mode numbers on the command line.
server-mode (XML) |
Mode | --mode (command line) |
|---|---|---|
| 0 | Normal race, grand prix | use --network-gp |
| 1 | Time trial, grand prix | use --network-gp |
| 3 | Normal race | 0 |
| 4 | Time trial | 1 |
| 6 | Soccer | 3 |
| 7 | Free for all (battle) | 2 |
| 8 | Capture the flag | 5 |
Follow the Leader is --mode=4 on the command line, but it has no server-mode value, so starting a server with it leaves server-mode at whatever the XML says (normal race by default). Grand prix servers do not let new players join and wait for the running game, which is why most public servers use mode 3.
Related options:
| Option | Default | What it does |
|---|---|---|
server-difficulty |
0 | 0 Beginner, 1 Intermediate, 2 Expert, 3 SuperTux |
gp-track-count |
3 | Tracks per grand prix |
soccer-goal-target |
false | true = first to a goal count, false = time limit |
server-configurable |
false | Lets the lobby owner change mode and difficulty in the lobby GUI; not for owner-less or GP servers, and changes are not saved to the file |
Players and lobby control
| Option | Default | What it does |
|---|---|---|
server-max-players |
8 | Player limit; the file warns more than 8 can hurt performance |
owner-less |
false | No owner: games start on a timer and nobody can kick |
start-game-counter |
60 | Seconds before an owner-less server moves to kart selection |
min-start-game-players |
2 | Players needed before that countdown starts |
team-choosing |
true | Players pick red or blue in soccer and CTF |
live-spectate |
true | Join or spectate a game in progress (FFA, CTF, soccer only) |
strict-players |
false | Blocks duplicate online IDs and split screen players |
kick-idle-player-seconds |
60 | Kick players idle mid race; always off on LAN servers |
chat |
true | false ignores all chat |
chat-consecutive-interval |
8 | Basic chat spam limit, negative turns it off |
For a group of friends, keep an owner so someone can start races and kick. For a server that runs while you sleep, set owner-less to true so it never waits on one person.
Track voting and game length
| Option | Default | What it does |
|---|---|---|
track-voting |
true | Players vote for the track; false picks one at random |
voting-timeout |
30 | Seconds for kart selection and track voting |
auto-end |
false | Ends a race some time after the first player finishes |
auto-game-time-ratio |
-1 | Scales laps and soccer length from the track default; -1 = off |
official-karts-threshold |
1 | Share of official karts a client must have |
official-tracks-threshold |
0.7 | Share of official tracks a client must have |
The two thresholds decide who gets in. A client with fewer official tracks than the server times the threshold is refused with Connection refused: Game data is incompatible. The Android build ships without some official tracks, so raising official-tracks-threshold toward 1 locks Android players out. Add-on tracks are a separate matter: a track can only be voted if the server has it installed, and each player needs it from the add-ons menu.
Battle and capture the flag limits
| Option | Default | Mode |
|---|---|---|
hit-limit |
20 | Free for all, 0 = no limit |
time-limit-ffa |
360 | Free for all, seconds |
capture-limit |
5 | CTF, 0 = no limit |
time-limit-ctf |
600 | CTF, seconds |
flag-return-timeout |
20 | Seconds before a dropped flag returns home |
flag-deactivated-time |
3 | Seconds a flag is inactive after a capture or return |
Validation, ranked play and network
| Option | Default | What it does |
|---|---|---|
validating-player |
true | WAN servers check players against the STK online service; LAN never does |
validation-timeout |
20 | Seconds allowed for that check |
ranked |
false | Submits ranking for race games; needs permission from the STK team and forces validation, auto-end, strict-players and owner-less on |
firewalled-server |
true | STUN code for servers behind a router; false saves resources on a server with an open port |
ipv6-connection |
true | Dual stack if the server has a public IPv6 address |
max-ping |
300 | Ping limit in ms |
jitter-tolerance |
100 | Allowed jitter in ms |
kick-high-ping-players |
false | Kick anyone over max-ping |
high-ping-workaround |
true | Keeps high ping players playable; disables the kick above |
state-frequency |
10 | Updates sent per second; leave the default |
enable-console |
false | Network console, same as --network-console |
Leave ranked alone unless the SuperTuxKart team has approved your server. A WAN server with ranked on and no permission stops at startup with You don't have permission to host a ranked server.
Database options
sql-management, database-file, the *-ban-table options and the geolocation tables only matter if the server was built with SQLite and you created the tables described in NETWORKING.md. With them you get persistent IP and online ID bans, player reports and play time stats. Without SQLite, keep sql-management false and use kickban in the network console for quick bans.
A sample friends lobby
<server-mode value="6" />
<server-difficulty value="2" />
<server-max-players value="10" />
<private-server-password value="tuxnight" />
<motd value="Soccer every Friday. Be nice." />
<owner-less value="false" />
<track-voting value="true" />
<soccer-goal-target value="true" />
On a GamezServers server
On a SuperTuxKart server from GamezServers, the panel's Server Name, Mode, Difficulty, Max Players and Message of the Day are passed on the command line, so they override the same lines in the XML; change those in the panel. The panel Mode uses the command line numbers, 0 to 5, and as explained above Follow the Leader (4) leaves server-mode as the XML has it. The Config File Name setting picks which XML file loads, and the file itself is in the file manager for the password, voting, limits and everything else above. The server runs in LAN mode, so wan-server is always off and players join with Enter server address. Stop the server, edit, save, start, and check the live console for the "new file will be created" line in case the XML broke.
Still setting up? Start with how to host a SuperTuxKart server, or see why a server may not appear in the online list.
FAQ
Where is the SuperTuxKart server config file?
Wherever --server-config points. A plain file name is created in the folder the server was started from. Logs go to the STK config folder as <name>.log.
How do I add a password to my SuperTuxKart server?
Set private-server-password in the XML or start with --server-password=secret. Leave it empty for a public server.
Why did my config.xml reset to defaults?
The XML was invalid or had an unsupported version, so the server replaced it. Check the log for "A new file will be created" and fix the syntax in your backup.
How many players can a SuperTuxKart server hold?
You set it with server-max-players. The default is 8, and the file itself warns that going higher can affect performance on weaker hardware.
What is an owner-less server?
A lobby with no owner: games start automatically after start-game-counter once enough players are in, and nobody can kick. It suits always on public servers.
Skip the setup. Your own SuperTuxKart server.
Then $2.99/mo. Just trying it? $0.75 for 3 days
Minecraft