Adding custom maps to an S&Box server

Introduction

In S&Box, maps follow the same logic as gamemodes: they are packages distributed on sbox.game, identified by org.name. A map can be loaded as the second argument of +game, or it's embedded in the gamemode package (in which case you don't have to do anything).

Prerequisites

• An operational S&Box server at VeryCloud
• The ident of the target map (e.g. garry.scenemap)
• The gamemode must support the map (not all maps work with all gamemodes)

Step 1: Find a map on sbox.game

Go to https://sbox.game/ and filter by Map type. Each map has its org.name ident visible in the URL.

Examples:

garry.scenemap         # default scene map
facepunch.flatgrass    # GMod reference
facepunch.construct    # GMod reference

Step 2: Load a map at startup

Change your GAME_MAP variable (or equivalent in Wisp Startup):

GAME_PACKAGE = facepunch.sandbox
GAME_MAP     = garry.scenemap

The generated command line will be:

sbox-server.exe +game facepunch.sandbox garry.scenemap +hostname "..." ...

Save and restart. The map package downloads automatically from sbox.game (just like a gamemode).

Step 3: Hot-swap maps

Many gamemodes expose a command to change maps without restarting the server. It depends on the gamemode (S&Box doesn't provide a standardized command like Source 1's changelevel).

Examples (verify in package docs):

# Sandbox Facepunch
map garry.scenemap

# Walker
map facepunch.flatgrass

If the command doesn't exist, just restart the server after changing GAME_MAP.

Step 4: Preload multiple maps

To reduce load times when switching maps, you can force-download several map packages at boot via a gamemode-specific command (implementation-dependent). Otherwise, load each map once manually: the local cache keeps the downloaded package.

Step 5: Custom maps (created by you)

If you're building your own map in S&Box's Hammer editor:

1. Publish it on sbox.game (public or private via your Facepunch account)
2. Reference the yourorg.yourmap ident in GAME_MAP
3. Restart

Private / dev case: if you don't want to publish the map, upload the full .sbproj (gamemode + map) locally on the server via SFTP and point +game at the .sbproj. See the gamemode installation tutorial for details.

Step 6: List available server-side maps

Maps are cached in a folder under cloud/packages/. You can list via SFTP or the Files tab what's been downloaded already. Purely informational: the server downloads on-demand, you don't need to manage this folder manually.

Troubleshooting

Map not found at startup

• Strict org.name format, lowercase
• Does the map actually exist on sbox.game?
• Compatible with your gamemode?

Map loads but gameplay is broken

• Incompatibility between map and gamemode (expected entities missing)
• Check the gamemode's docs for officially supported maps

Slow download

• Load the map once during off-peak hours, then it's in local cache

+map ignored

• In S&Box, the map isn't +map but the 2nd argument of +game
• Verify your Wisp variable: GAME_MAP or equivalent must be wired up correctly

Useful commands

# Status after map change
status

# Clear a specific map cache (SFTP)
rm -rf /home/container/cloud/packages/garry.scenemap

# Force reload from panel
# -> STOP then START (not RESTART, which doesn't always purge cache)

Conclusion

Adding S&Box maps is as simple as editing a startup variable. The cloud package system makes the operation much cleaner than in GMod days where you had to manually manage BSP files, workshop addons and FastDL.

Going further: build your own maps with Hammer S&Box, manage map rotation via gamemode, optimize initial download.

Resources

• sbox.game — Maps
• S&Box Docs — Maps
• S&Box Docs — Dedicated Servers
• Facepunch Hammer Documentation