How to host a BattleSpades server

Choose a portable or source build

Portable 0.0.2 alpha archives are the shortest route to a running host. They include the launcher, Python and native runtime, configuration, VXL maps, KV6 prefabs, plugin directory, and notices. Select the archive for Windows, Linux, or macOS and for x86-64 or ARM64.

A source build supports Python 3.10 through 3.12, with Python 3.12 as the primary development target. You also need a C/C++ toolchain because Cython extensions and the pinned ENet transport are compiled locally.

Start a portable server

Extract the entire archive rather than copying only the executable. Maps, native libraries, configuration, plugins, and notices are part of the runtime. Run the built-in check first so missing files or an invalid configuration fail before players arrive.

The first macOS alpha is unsigned and not notarized, so the host may need an explicit local Gatekeeper override. That is an operator decision; the release does not claim Apple notarization.

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

Linux or macOS
./BattleSpades --check
./BattleSpades

Build from source

Use a virtual environment so compiled dependencies stay isolated from other Python projects. The platform install scripts clone dependencies, build the extensions, and leave the normal Python entry point available for development.

Stop the server before rebuilding Cython extensions. A running Windows process locks the loaded native modules, and rebuilding over them will fail.

Linux or macOS
 git clone https://github.com/KikoTs/BattleSpades.git
 cd BattleSpades
 ./scripts/install.sh
 python run_server.py

Windows PowerShell
 git clone https://github.com/KikoTs/BattleSpades.git
 cd BattleSpades
 .\scripts\install.ps1
 python run_server.py

Configure the match before opening the port

The editable config.toml file controls identity, networking budgets, maps, modes, bots, game rules, classes, equipment, weapons, administration, and plugins. Start with a small, predictable setup and change one category at a time.

The simulation tick rate should remain 60 unless you are actively developing and validating client parity. It is not a generic performance knob: client behavior is calibrated around the current fixed rate.

• Set a recognizable server name and choose the default VXL map
• Choose tdm, ctf, classic_ctf, arena, vip, or zombie as the default mode
• Keep the default 24 slots for a first public test, then measure before raising it
• Set bot_count to populate an empty server or test objectives
• Review friendly fire, fall damage, block damage, respawn, class, and equipment rules
• Set strong administrative credentials and remove values you do not use

Network and firewall checklist

BattleSpades listens on UDP port 27015 by default. A host behind a home router normally needs a UDP port-forward from the public address to the machine running the server. The operating-system firewall must allow the same inbound UDP port.

Test locally first, then from another device on the local network, and finally from outside the network. A local connection proves the server is running; it does not prove the router, carrier, cloud security group, or upstream network permits public traffic.

1. 01
   Local

   Connect a compatible client to 127.0.0.1:27015 on the host machine.

2. 02
   LAN

   Connect from a second device using the host’s private network address.

3. 03
   Public

   Forward UDP 27015 and test from a different internet connection.

4. 04
   Observe

   Watch logs, tick timing, packet backlog, map transitions, and reconnect behavior during a real match.

Publish a verified community listing

Once the server is reachable from the public internet, send its game and query ports to POST /api/master/servers/register on the revival website. The service uses the source address it observes instead of trusting a caller-supplied IP address, then imports the server name, map, mode, region, version, and population from a verified UDP A2S_INFO response.

A successful probe creates a community listing and returns a server-scoped token once. Store that token as a secret and use it for heartbeats from that server only. A timed-out or invalid probe remains pending and is never silently published; fix the firewall, forwarding, or server response and request verification again.

• Expose the configured game port over UDP before registering
• Send only the public game and query ports; live match metadata comes from A2S
• Keep the returned aos_srv token private and rotate it by registering again if it is exposed
• Use the scoped token for that server's heartbeat rather than the internal master write token
• Keep direct-connect instructions available so discovery outages never stop independent play

Operate it like a small service

Back up configuration, custom maps, prefabs, plugins, and moderation data before upgrades. Validate a new archive or source revision on a separate port before replacing a working public instance.

For ongoing hosting, use a service manager appropriate to the operating system, capture logs with bounded retention, and document who can restart or administer the process. The repository runbook contains the deeper capacity, parity, bot, map, mode, and release validation gates used by the project.