Ladder Server Setup

Ladder Server Setup

A ladder-enabled server reports every finished match to the Q3Rally Ladder, so its players show up on the leaderboards.

1. Get an API key

1. Open ladder.q3rally.com/register.php.
2. Enter your server name exactly as in sv_hostname, plus your name and e-mail.
3. After you submit, your API key is shown once. Copy it right away, because it can't be displayed again. If you lose it, contact the ladder admin.
4. The key starts as pending. Matches are accepted once an admin approves it.

2. Configure the server

seta sv_ladderEnabled 1
seta sv_ladderUrl "https://ladder.q3rally.com/index.php/matches"
seta sv_ladderApiKey "your-key-here"

Cvar	Default	Description
sv_ladderEnabled	0	1 enables the match reporter
sv_ladderUrl	—	The ladder's match endpoint. It must end in /matches.
sv_ladderApiKey	—	Your key, sent as a bearer token. It's a protected cvar: never shown in status or logs, and mods can't read it.

🔒 Don't put your API key in a config you share publicly. Keep it in a separate, private config and exec that one.

How reporting works

1. Match ends. At intermission the server builds a JSON report: map, mode, timestamps, and for every player the position, lap times, kills, damage, captures and so on.
2. Upload. The report is sent in the background, so the server doesn't stall.
3. Retry. If the ladder can't be reached, or answers with an error 5xx, the report is queued on disk and retried with growing delays (5 s up to 5 min). Nothing is lost when the ladder is briefly down.
4. No duplicates. Each match has a unique ID. Sending the same match twice does no harm.

Ghost Race 🧪 matches are not reported. In the development build, the server also uploads drivers' best laps as ghosts (g_ghostUpload) and downloads ladder ghosts for Ghost Race (g_ghostDownload). Both use the same URL and key.

Running your own ladder

The ladder software is part of the repository, in two flavours:

• PHP webservice (ladder_service/php_webservice/). Runs on ordinary PHP 8 web hosting with no database. Upload the folder, make data/ writable, done. This is what ladder.q3rally.com runs on.
• Python service (ladder_service/). A FastAPI service with SQLite, mainly used for development and testing.

The exact report format is documented in docs/ladder_payload_semantics.md.