How to Add Custom Maps to a Xonotic Server (sv_curl_defaulturl)

Q: Where do custom maps go on a Xonotic server?

In the server's user data folder, the same folder as server.cfg, which is ~/.xonotic/data/ on Linux.

Q: Do players have to download custom maps manually?

No. With a working svcurldefaulturl, the game downloads missing maps when they connect.

To add a custom map to a Xonotic server, put the map's .pk3 file in the server's data folder (~/.xonotic/data/, next to server.cfg), add the map name to g_maplist, and restart. For players to get the map automatically, upload the same pk3 to any web server and point sv_curl_defaulturl at that folder (with a trailing slash). Xonotic clients then download it over HTTP when they connect. Without a download URL, players who lack the map cannot join while it is loaded.

HTTP downloads are the documented way to do this in Xonotic, and they are fast. One small setting saves every newcomer a frustrating first join.

A Xonotic map with neon lighting

Step 1: Get the map

Community maps for Xonotic are shared as .pk3 files, which are zip archives with a different extension. Use maps built for the current release. Old Nexuiz era maps may load but often have missing textures or no bot waypoints.

Open the pk3 with any zip tool to find the map name. It is the .bsp file name inside the maps folder:

map-myarena_v2.pk3
  maps/
    myarena_v2.bsp
    myarena_v2.mapinfo
    myarena_v2.waypoints

Here the name is myarena_v2. The .mapinfo file lists which game modes the map supports, and a .waypoints file means bots can play it.

Step 2: Put it in the server's data folder

Copy the pk3 into the same folder as your server.cfg, which on Linux is ~/.xonotic/data/. Not the install folder's data directory, which holds the game's own packages, and not a subfolder.

Test it from the server console:

gotomap myarena_v2

If the console reports it cannot find the map, the file is in the wrong folder or the name is off.

Step 3: Add it to the map list

g_maplist is a space separated list in one pair of quotes:

g_maplist "atelier dance erbium implosion solarium stormkeep myarena_v2"
g_maplist_shuffle 1

Maps that do not support the current gametype are skipped automatically, so it is safe to mix CTF and deathmatch maps in one list. Restart, or run gotomap to switch now. Our Xonotic server.cfg guide covers the rest of the rotation and voting settings.

Step 4: Let players download it

Xonotic's map download system works over HTTP. The game's own documentation (Docs/mapdownload.txt) recommends HTTP over FTP because it works better for firewalled players. Clients need no setup: downloads are on by default.

Option A: one download folder. Upload your pk3 files to any web host, then add to server.cfg:

sv_curl_defaulturl "https://files.example.com/xonotic/"

DarkPlaces appends the pk3 file name to that address, so the trailing slash matters when you point at a directory. A player missing map-myarena_v2.pk3 fetches https://files.example.com/xonotic/map-myarena_v2.pk3.

Option B: rules per pack with curl_urls.txt. Put a file named curl_urls.txt in the data folder, with one pattern url pair per line. The first matching pattern wins:

data*    -
map-*    https://files.example.com/maps/
*        https://files.example.com/misc/

A - means "never offer this file for download". That first line stops the server offering the game's own data packages, which every player already has.

Downloaded maps land in the player's dlcache folder and are used only until they quit, so returning players may fetch them again. That keeps clients clean, and it is one more reason to use a fast web host.

Step 5: Keep the folder tidy

Every pk3 in the data folder is loaded by the server. Two packs that contain a file with the same path can clash, and a pile of unused packs means more for players to download. Keep only the maps in your rotation, and remove packs you no longer play. Map packs that also change models or sounds can make the server impure, which shows in the server list.

Troubleshooting

Problem	Likely cause
`gotomap` says the map is unknown	pk3 not in the data folder next to `server.cfg`, or wrong name
Players disconnect while loading a custom map	No `sv_curl_defaulturl`, or the URL returns 404
Download starts but fails	Missing trailing slash, or the file name on the web host differs
Map never comes up in rotation	Map does not support the current `gametype`
Bots stand still	Map has no waypoints file

To test the download URL, paste it plus the pk3 name into a browser. If the file downloads, Xonotic can download it too.

Xonotic players fighting in an outdoor arena

On a hosted server

On a GamezServers Xonotic server, upload map pk3 files into .xonotic/data/ with the file manager or SFTP, edit g_maplist in server.cfg, and restart from the panel. You still need a web address for sv_curl_defaulturl, since the game server itself is not a web host. Any static file host works, and the live console lets you test gotomap before you advertise a new map. New to Xonotic hosting? Start with our Xonotic server setup guide.

FAQ

Where do custom maps go on a Xonotic server?

In the server's user data folder, the same folder as server.cfg, which is ~/.xonotic/data/ on Linux.

What is sv_curl_defaulturl?

The web address players download missing pk3 files from. The pk3 name is appended to it, so end directory URLs with a slash.

Do players have to download custom maps manually?

No. With a working sv_curl_defaulturl, the game downloads missing maps when they connect.

Why do players download my map again every time?

Downloaded packages go into a cache that is only used until the game closes. Players can keep a map by moving it from dlcache up into their data folder.