Aqua IV 0.11
Documentation Editor Engine API
Documentation /Editor / Tutorials

Host a dedicated server

A dedicated server runs one match of your map by itself, with no one's game window attached. Players connect to it, send orders, and the server sends back what each player is allowed to see. It is the same simulation the engine uses, so a map that works in the engine works on the server.

This tutorial starts a server on your own computer, looks at what it does, and then shows what changes for a server other people can reach. It is an alpha: the server is for testing, and the game window's own "join" screen is still being built, so you check the server with the tools in this page.

What you need

  • A packed map (.a4m) or a map folder. Any map from Getting started works. It needs a unit with an owner (a player) to make a seat.
  • The server program, w4-dedicated. It is part of the W4 sources (server/dedicated) and is built with Rust: cargo build --profile fast in that folder. The first build takes a few minutes. It is not in the editor or engine download yet.

1. Start it for yourself

w4-dedicated --map "C:\Users\you\Documents\W4 Maps\battle" --lobby

The server listens on 127.0.0.1:7777 and says so:

w4-dedicated: map 'battle', players [1, 2], listening on 127.0.0.1:7777, 30 steps a second, sign-in OFF (any name; development only)

Three things to read in that line:

  • players [1, 2] are the seats the map has. A map with two player slots has two seats; that is also how many people can join.
  • 30 steps a second: the simulation. Players see snapshots ten times a second.
  • sign-in OFF: with no --online option any name is accepted, but only from this computer. A server that is not signed in refuses everybody else on purpose.

--lobby opens a pre-game lobby: players pick a team and press ready, and the first one to join (the host) starts the game. Without it the game starts as soon as enough players have connected and loaded.

2. Look at it

The quickest check is the test client in the sources:

powershell -ExecutionPolicy Bypass -File server\dedicated\try-client.ps1 -Name Tester

It connects, prints the server's welcome, shows how many units you can see, orders one of them to walk and shows it moved. If it prints a snapshot line with units, the server works.

For the protocol itself (what a game window has to say and what it hears) read server/dedicated/WIRE.md in the sources. It has full example sessions.

3. Useful options

Option What it does
--listen 127.0.0.1:7777 where to listen. The default keeps a test server on your computer and avoids the Windows firewall question.
--start-when 1 start for one player as soon as they are ready, instead of waiting for every seat
--lobby, --lobby-lock-teams a lobby; with the second option players cannot change team themselves
--max-game-minutes 120 a game that lasts longer ends as a timeout
--postgame-minutes 10 how long players stay in the room after a game; they can vote to play again
--seat-grace-minutes 10 how long a seat is kept for a player who is away, before the match has started
--max-bytes-per-sec 250000 the byte budget per player for the compact binary format

4. A server other people can use

A server on the internet needs three more things.

  1. Sign-in. Run the W4 online service (server/online) or use the official one, and start the server with --online http://127.0.0.1:5179. Every player then connects with a game token from the account page, and the server accepts connections from anywhere. Add --allow-guests to let people without an account play as Name (local). Without --online, nobody but you can connect.
  2. An address. Listen on a public address: --listen 0.0.0.0:7777 (your firewall asks once on Windows), forward the port on your router (TCP 7777; UDP too if you add --quic-listen), and give players the address with --address your.name:7777.
  3. Encryption. Add --tls-cert cert.pem --tls-key key.pem so tokens do not travel in the clear. The certificate must cover the name players type. The server re-reads the files when they change, so a renewed certificate needs no restart.

With a host key (--host-key or the AQUA4_HOST_KEY variable, the secret of the online service) the server lists itself on the Lobbies page, with its title (--title), and keeps itself listed. Without it the server works but is not listed.

The official server is nebel.sh:7777. It runs exactly this program with these options.

5. If something is wrong

You see It means
development mode accepts local connections only the server has no --online; connect from the same computer or add sign-in
this server speaks protocol 1 the client is a different version
the game is full every seat is taken
the server is busy, try again in a moment the server's connection limit (256 in all, 8 per address) was reached
nothing happens for a minute, then the connection closes a connection must say hello within 60 seconds

The full list is the error table in WIRE.md. A server does not stop when a player's line breaks: the player's seat is kept and they can connect again with the same name, see You can always come back.

6. What it costs

On the official machine (2 cores) the server uses about 20 MB of memory and 0.2 percent of a core while idle. A test with 8 scripted players for 30 minutes stayed at 24 to 26 MB and kept 30 steps a second. To try your own server with many scripted players, see Run a bot load test.