Game modes, maps and rotation

01The modes

Use the short code in [game] default_mode, /mode and [modes.<code>]. The aliases are accepted everywhere and stored as the short code; an unknown name stops the server at startup with the list of valid names.

• TDM, CTF, Classic CTF, Zombie and VIP are fully playable.
• Multi-Hill, Territory Control, Diamond Mine, Demolition and Occupation have complete objective state machines (hills, territories, diamond cash-in, destructible bases, bombs) and tests; exact retail parity is still being confirmed in live matches.
• Classic CTF locks both teams to the classic Deuce class and uses the seven classic maps. VIP and Territory Control use the mafia maps Alcatraz and CityOfChicago.
• Arena is a BattleSpades extension (rounds instead of a clock), not a retail Match Lobby row.

02Startup mode, map and clock

[game]
default_mode = "tdm"
default_map = "ArcticBase"   # file maps/ArcticBase.vxl

[lobby]
# One clock for every mode; only 5,10,15,...,60 or 90 are accepted.
match_length_minutes = 20

[modes.ctf]
time_limit = 1800            # seconds; beats match_length_minutes for CTF

Clock precedence: [modes.<code>] time_limit (seconds, 0 = no clock) → [lobby] match_length_minutes → the mode's retail clock from the table above. Score targets come from the mode's [game_rules] rule (for example RULE_TDM_SCORE_TARGET = 200, RULE_CTF_SCORE_TARGET = 5) or a score_limit override. Every per-mode key is listed in the configuration reference.

03Map rotation

[lobby] map_rotation is the list of maps offered in the end-of-round vote.

• Empty (`[]`, the default): the mode's retail playlist from the table above, filtered exactly like retail (maps marked invalid for the mode are skipped). If none of those maps is installed, every .vxl in the maps folder is used.
• A list: exactly these maps. Names are .vxl file names without extension; missing files are logged and skipped, and stock maps retail marks invalid for the running mode (such as GreatWall in Demolition) are dropped with a warning.
• map_rotation_shuffle = true shuffles the list once at startup, as the retail lobby did; false keeps your order.

[lobby]
map_rotation = ["CastleWars", "TokyoNeon", "Atlantis", "BlockNess"]
map_rotation_shuffle = false

Maps shipped with the server:

20thCenturyTownAlcatrazAncientEgyptArcticBaseAtlantisBlockNessBranCastleCastleWarsCityOfChicagoClassicCrossroadsDoubleDragonDragonIslandFrontierGreatWallHiesvilleInvasionLondonLunarBaseMayanJungleSpookyMansionTheColosseumToTheBridgeTokyoNeonTrainingTrenchesWW1WinterValley

04End-of-round vote and presentation

When a round ends, players vote for the next map from candidates drawn from the rotation (never the current map). The candidates are ordered to suit the lobby:

• With map_vote_size_fit on, maps whose playable area fits the player count come first: the ideal area is players × map_vote_area_per_player (8000 columns), never below map_vote_min_area (24000). Bots count as map_vote_bot_weight of a player.
• The last map_vote_recent_exclude (2) played maps are offered last.
• With map_vote_retail_max_players, maps whose retail player cap is below the human count (DragonIsland 16, London and LunarBase 20, BlockNess and SpookyMansion 24) are offered after maps that fit.
• map_size_overrides pins a map's size when its bot-navigation cache is missing or misleading: { WW1 = "large", DragonIsland = 27000 } (small, medium, large).

After the vote the scores screen stays up for end_screen_seconds (12 s), then every client reloads into the next map. end_round_scoreboard holds the scoreboard open at round end and end_round_headline shows the retail result headline (“Blue wins!”, “Draw!”).

Admin controls

05Custom maps

1. 01
   Format

   Maps are Ace of Spades .vxl files of 512 × 512 × 240 voxels.

2. 02
   Install

   Copy MyMap.vxl into the maps/ folder (or your [world] maps_path).

3. 03
   Metadata (optional)

   Spawns, bases, objectives, crates, fog and skybox come from a sidecar next to the map: MyMap.json, or the .txt/.ugc pair written by the BattleSpades Map Creator. Without one the server derives team sides and spawns from the terrain and team-coloured markers, and uses [world] default_skybox and fog_color_rgb.

4. 04
   Use it

   Set default_map = "MyMap", add it to map_rotation, or switch live with /map MyMap.

Bots work on custom maps without preparation; the bot worker builds its navigation data from the map on load. Shipped maps include a precomputed .botnav cache to start faster; a source checkout can build one for your map with py -3 scripts/build_bot_navigation.py --map MyMap.

The Map Creator (run_map_creator.py / BattleSpadesMapCreator) is a separate program for building maps with the retail editor UI; it requires your own retail game assets and is configured through [map_creator].

06Retail-style presets

The ten profiles in configs/ are complete examples of retail-faithful setups (rotation, clock, bots). Copy one next to your config.toml and start it with --config, or run them all with the fleet launcher; see Multiple servers and updates.