Host your first BattleSpades server

01What you need

A computer that stays on while people play, a network that lets UDP traffic in, and players with a compatible client.

02Option A: portable release

Open the BattleSpades releases page (opens in a new tab) and download the archive for your system: windows-x86_64, windows-arm64, linux-x86_64, linux-arm64, macos-x86_64 or macos-arm64. Each archive contains the launcher, the Python runtime, config.toml, the maps, prefabs, the plugin folder and license notices.

1. 01
   Verify

   Compare the ZIP against the release's SHA256SUMS.txt (for example certutil -hashfile file.zip SHA256 on Windows or sha256sum file.zip on Linux).

2. 02
   Extract everything

   Extract the whole folder. Do not copy only the executable: maps, native libraries and config must sit next to it.

3. 03
   Set the admin password

   Open config.toml in a text editor and set [admin] password to a unique secret of at least 12 characters (see below).

4. 04
   Run the check

   Run --check once. It validates the config, maps, native modules, prefabs and the bot worker without opening the game port.

5. 05
   Start

   Run the executable without arguments. Leave the window open; closing it stops the server.

.\BattleSpades.exe --check
.\BattleSpades.exe

./BattleSpades --check
./BattleSpades

The macOS build is unsigned and not notarized, so Gatekeeper may ask you to allow it explicitly (System Settings → Privacy & Security).

03Option B: build from source

Install Python 3.12 and a compiler first. The compiler builds the Cython physics/map/packet core and the bundled ENet networking library.

git clone https://github.com/KikoTs/BattleSpades.git
cd BattleSpades
py -3.12 -m venv venv
.\venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python setup.py build_ext --inplace
python run_server.py --check
python run_server.py

git clone https://github.com/KikoTs/BattleSpades.git
cd BattleSpades
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python setup.py build_ext --inplace
python run_server.py --check
python run_server.py

The repository also has one-step installers that do the dependency install and build for you: ./scripts/install.sh (Linux/macOS) and .\scripts\install.ps1 (Windows).

04The five settings to change first

Everything lives in config.toml next to the server. The server reads it once at startup, so restart after editing. The shipped file is a complete, commented example; you only need to touch a few keys to begin.

[server]
name = "My AoS Server"        # max 31 characters are shown
port = 27015
max_players = 24

[game]
default_mode = "ctf"           # tdm ctf cctf zom vip mh tc dia dem oc arena
default_map = "CastleWars"     # a .vxl name from maps/, without .vxl

[admin]
password = "a-long-unique-secret"  # 12+ characters, not changeme

• Name: what players see in the browser and scoreboard.
• Mode and map: see Game modes and maps for the retail map pool of each mode.
• Admin password: in-game /admin login is disabled while it is changeme, empty or shorter than 12 characters. The server still runs, but you cannot moderate.
• Bots: the sample config backfills up to 12 bots when the server is empty. See Bots to change or disable that.
• AoSPlay listing: [revival] enabled = true does nothing until you register and set a token; see Ports and public listing.

To keep personal tweaks separate, copy the file to config.local.toml and start with --config config.local.toml. --port 27020 overrides only the port for one run. Every key is explained in the configuration reference.

05Start and join

A healthy --check prints one OK line per item. A warning about the admin password means you have not changed it yet.

OK version: 0.1.0-beta.1
OK config.toml: C:\Games\BattleSpades\config.toml
OK maps: 28 VXL files; default=MayanJungle.vxl
OK native imports: 8 modules
OK Steam discovery: disabled
OK prefabs: 40 KV6 files
OK worker spawn: AI child processed full map MayanJungle.vxl ...

1. 01
   Same computer

   Start your game client and use its direct-connect option with 127.0.0.1:27015. This proves the server runs.

2. 02
   Same network

   From another device on your LAN, connect to the host's local address, e.g. 192.168.1.20:27015. This proves the OS firewall lets UDP in.

3. 03
   Internet

   Forward the port on your router and test from a different connection (a phone hotspot works). Details: Ports and public listing.

4. 04
   Become admin

   In game, open chat and type /admin your-password. Try /help to see every command you now have.

Logs are written to logs/server.log beside the server (rotated at 16 MB, 3 backups) and to the console. Crash stack traces go to logs/server.fault.log. To stop the server press Ctrl+C in its window.

06Where to go next

• Ports and public listing: firewall, router, AoSPlay and Steam listing.
• Game modes and maps: rotation, votes, match length.
• Admin and moderation: bans, anti-cheat, AFK and griefing.
• Multiple servers and updates: run many modes from one install and upgrade safely.
• Troubleshooting: when something does not work.