Warning
This document is out-dated and might not represent the current truth! Handle with caution.

Here below is described how the network-protocol works.

The protocol has been designed to be stable, little to no desyncs, and still fast and playable with a dialup modem. We believe we succeeded in this.

OpenTTD mostly uses TCP. It also makes use of UDP, but below you can read more about that.

OpenTTD - TCP

All main communication goes via TCP. Why not UDP, you can ask. Very simple: TCP is a packet-protocol. One packet depends on the other. We are completely sure in TCP that a client or server receives a certain packet. With UDP we are not. Of course you can build a layer on top of the UDP that does this, but then you just remade TCP.

So why do we need a packet-protocol. Let me try to explain:

Packet-protocol

Everything you build in OpenTTD, or change, is handled internally via a so called DoCommand. Instead of sending diffs of the memory every 10 ms or something to make clients and servers sync, we make use of this DoCommand. At the moment a client does a DoCommand, it does not execute it yet, but the command is sent to the server. The server picks a frame-of-execute for the DoCommand, and sends that information to all clients. When the clients hit that frame, it executes the DoCommand. This way all clients and server keeps in sync. But as you can understand, it is needed that all packets are received, in order, by both server and clients. That is why we make use of a Packet-protocol.

How does it work?

As you have read above, we send DoCommands. Now in normal conditions, the server sends out a FRAME-packet every frame. In this frame it says to what frame the client can 'walk'. Just before that, the server has sent all DoCommands for the max-frame in the FRAME-packet. This way, all clients 'walk' to the max-frame, and then execute all DoCommands. Because a client can never be beyond the max-frame, neither can the server, all DoCommands are executed on the same frame. This is very much needed, else we get massive desyncs. Sometimes it is necessary to increase the freq. of this FRAME-packet (e.g. many slow connections). Then what happens is this: the server sends out a FRAME-packet every X seconds, containing a max-frame of X+freq. Also, all DoCommands have the frame-of-execute set on X+freq. Again, this way we are sure all DoCommands are handled at the same moment (even the same order). What does this mean? Very simple: when you build a rail for example, it can take 'freq' frames before it shows up. So as you understand, this 'freq' can not be too high. Some statistics:

Network Speed per Client

Warning
NEEDS UPDATING!

net_frame_freq	Upstream	Downstream
1	1.2 kbyte/sec	1.2 kbyte/sec
2	0.8 kbyte/sec	0.8 kbyte/sec

As you can see, your connection has to be really slow to adjust the frame_freq. You can change the frame_freq in the console with: setting frame_freq <number>

What is this desync?

Desync happens when a client is out of sync with the server. How do we detect that? Pretty simple: a game can be different, when DoCommands are not handled, but even worse: when the Random is not the same. OpenTTD has a home-build Randomizer, which means that on every machine it gives the same random numbers from a certain seed. So when seed = 1, and we do a random, we get on every machine, for example, 534523 back. This is very useful. We check once in the sync_freq if the seeds on both clients and server is the same. If this is not the same, it means that the server or one of the clients did a random too much or too little. Because we cannot check which one made an error, this client is then kicked out of the server and can rejoin to resync.

In the old protocol this happened a lot, mostly because of a bad network protocol. Packets were not always sent in order, and clients could walk 100 frames in front of the server and received, on random frames, DoCommands. This was the cause of the desync's 99% of the time. This is fixed now. I can't remember someone complaining about a desync in this new protocol, simply because it is almost impossible to have a different random-seed.

By default, the seeds are checked once in the 100 frames. You can alter this with '*net_sync_freq = <number>'. Do not make this number too low, because it increases bandwidth by a lot.

Endian

The network protocol is 100% endian safe. We made that possible by creating our own endian, so to speak. We do not send packets, but we send bytes over the network. For example, when we want to send a int64, we send first byte 1, then byte 2, and so on. So the byte order is ALWAYS 1 2 3 4. This way we know for sure that every client can join every server, as far as endianness is concerned.

LAN-detection

OpenTTD has a function which can detect LAN-servers. This is done via UDP. At the moment you select LAN-mode on the server, the server also starts an UDP-listener. When a client on the same LAN presses Find Server in LAN-mode, it sends an UDP-broadcast. This is one of the best things UDP has: broadcast. The server receives it, and sends his game_info back to the client. This way the client can discover a server on the local LAN. This is the only place where UDP is used.

Joining

When a client joins, it first fetches some data from the server (game-info). Then it verifies itself, gives his name and, if needed, passwords. Then it asks for a copy of the current map. We do this, because we need a start. In the map is also saved the random-seeds, and we also send which frame the map is of. So the server makes the copy of the map, starts sending it to the client. At that moment, the server queues all new DoCommands for this client. When the client is done receiving and tells the server that it is also done loading the map, the servers dequeues all the DoCommands, and the client is given some time to get back to the frame the server is currently on (of course time passed between starting receiving and done loading. Even more on slow connections). When the client indicates it is done with the dequeue, the client is in sync and can enjoy playing.

TODO

As always, not everything is done. Some things that needs to be done:

- Ban players GUI
- MOTD

The protocol

Below is described which packets are sent (for the real ID of a packet, check network_data.h (enum PacketType)) to or from the server. Also is added which data is expected to be in there.

The client can get the server info without authorization. But before it gets the map, it needs authorization. After it received the map, it starts playing, and also the player is announced to the other clients.

Below first the packets the client can send to the server. After that, the packets the server can send to the client.

Some information:

• An uintX is X bits that together makes an unsigned something. So an uint8 is just a byte, and uint32 is four bytes in the order 1 2 3 4 that together makes an unsigned int32.
• A string are multiple chars behind eachother. You must read it till you reach a zero. There is no length info attached.

 <none>

 - String: OpenTTD revision of the client (norev000 if no revision)
 - String[40]: Playername
 - Uint8: Playas (between 1 and MAX_PLAYERS)
 - Uint8: LanguageID

 - Uint8: Type of password (Game-Password (0) or Company-Password (1))
 - String[20]: Password

 <none>

 <none>

 - Uint32: _frame_counter of the client

 - Uint8: PlayerID (0..MAX_PLAYERS-1)
 - Uint32: CommandID (see command.h)
 - Uint32: P1 (free variables used in DoCommand)
 - Uint32: P2
 - Uint32: Tile (tile of DoCommand)
 - Uint32: decode_params
 < 10 times the last one (lengthof(cp->dp)) >
 - Uint8: CallBackID (see callback_table.c)

 - Uint8: ActionID (see network_data.h, NetworkAction)
 - Uint8: Destination Type (see network_data.h, DestType);
 - Uint8: Destination Player (1..MAX_PLAYERS)
 - String[MAX_TEXT_MSG_LEN]: Message

 - Uint8: ErrorID (see network_data.h, NetworkErrorCode)

 - String[20]: Password

 - String[100]: Leave message

 - Uint8: The index of the client (always unique on a server. 1 = server)
 - Uint8: As which player the client is playing
 - String[40]: The name of the client

 - Uint8: Version of this GAME_INFO packet (current version is 4)
   From version 4:
 - Uint8: Number of active newgrfs (let number be NG)
 - NG x (Uint32, Int256): GrfID and MD5sum of active newgrf.  NOTE - these have opposite endianness!  THey are big-endian numbers.
   From version 3:
 - Uint32: Current game date
 - Uint32: Start date
   From version 2:
 - Uint8: Maximum number of companies
 - Uint8: Current number of companies
 - Uint8: Maximum number of spectators
   From version 1:
 - String: The servername
 - String: The revision of the server (norev000 if not supported)
 - Uint8: The LangaugeID of the server
 - Uint8: If the server is using a password
 - Uint8: Max allowed clients on the server
 - Uint8: Current clients
 - Uint8: Current spectators
 - Uint16: Current game-date of the server (pre-version 3 only)
 - Uint16: Start date of the game (pre-version 3 only)
 - String: Name of the current map (Random is random)
 - Uint16: Width of the map
 - Uint16: Height of the map
 - Uint8: Set of the map (0..3)
 - Uint8: Set if the server is dedicated

 - Uint8: ErrorID (see network_data.h, NetworkErrorCode)

 - Uint8: Type of password (game-password (0) or company-password (1))

 - Uint8: own ClientID (unique number per server session)

 - Uint8: Clients awaiting map

 - uint8: packet-type (MAP_PACKET_START, MAP_PACKET_NORMAL and MAP_PACKET_END)
  if MAP_PACKET_START:
   - uint32: The current FrameCounter
  if MAP_PACKET_NORMAL:
   - uint8[SEND_MTU]: piece of the map (till max-size of packet)
  if MAP_PACKET_END:
   - uint32: seed0 of player
   - uint32: seed1 of player
   < last 2 are repeated MAX_PLAYERS time >

 - Uint8: ClientID

 - Uint32: Frame Counter
 - Uint32: Frame Counter Max (how far may the client walk?)
 - [Uint32: general-seed-1]
 - [Uint32: general-seed-2]
   (last two depends on compile-settings, and are not default settings)  

 - Uint32: Frame Counter
 - Uint32: General-seed-1
 - [Uint32: general-seed-2]
   (last one depends on compile-settings, and are not default settings)

 - Uint8: PlayerID (0..MAX_PLAYERS-1)
 - Uint32: CommandID (see command.h)
 - Uint32: P1 (free variables used in DoCommand)
 - Uint32: P2
 - Uint32: Tile (tile of DoCommand)
 - Uint32: decode_params
 < 10 times the last one (lengthof(cp->dp)) >
 - Uint8: CallBackID (see callback_table.c)
 - Uint32: Frame of execution

 - Uint8: ActionID (see network_data.h, NetworkAction)
 - Uint8: ClientID
 - String[MAX_TEXT_MSG_LEN]: Message

 - Uint8: ClientID
 - Uint8: ErrorID (see network_data.h, NetworkErrorCode)

 - Uint8: ClientID
 - String: Leave message

 <none>

 <none>