docs/game_coordinator.md

   1 # Game Coordinator
   2
   3 To allow two players to play together, OpenTTD uses a Game Coordinator to
   4 facilitate this.
   5
   6 When a server starts, it can register itself to the Game Coordinator. This
   7 happens when `server_game_type` is set to either `invite-only` or `public`.
   8 Upon registration, the Game Coordinator probes the network of the server, and
   9 assigns the server an unique code, called an `invite code`.
  10
  11 When a client wants to join a server, it asks the Game Coordinator to help
  12 with this by giving it the `invite code` of the server. The Game Coordinator
  13 will, in this order, attempt several ways to connect the client and server
  14 together:
  15
  16 ## 1) Via direct IPv4 / IPv6
  17
  18 Upon registration, the Game Coordinator probes the server to see if a
  19 direction connection to the server is possible based on the game port. It
  20 tries this over the public IPv4 and IPv6, as announced by the server.
  21 If either (or both) are successful, a client will always be asked to try
  22 these direct IPs first when it wants to connect to this server.
  23
  24 - If the server is IPv4 only, the client is only asked to connect via IPv4.
  25 - If the server is IPv6 only, the client is only asked to connect via IPv6.
  26 - If the server is both IPv4 and IPv6, the client is asked to connect to to
  27   one of those first. If that fails, it is asked to connect to the other.
  28   Whether it tries IPv4 or IPv6 first, strongly depends on several network
  29   infrastructure related events. The biggest influence is the network
  30   latency over both protocols to the OpenTTD infrastructure.
  31
  32 In the end, if either the server is not reachable directly from the Internet
  33 or the client fails to connect to either one of them, the connection attempt
  34 continues with the next available method.
  35
  36 ## 2) Via STUN
  37
  38 When a client wants to join a server via STUN, both the client and server
  39 are asked to create a connection to the STUN server (normally
  40 `stun.openttd.org`) via both IPv4 and IPv6. If the client or server has no
  41 IPv4 or IPv6, it will not make a connection attempt via that protocol.
  42
  43 The STUN server collects the public IPv4 and/or IPv6 of the client and server,
  44 together with the port the connection came in from. For most NAT gateways it
  45 holds true that as long as you use the same local IP + port, your public
  46 IP + port will remain the same, and allow for bi-directional communication.
  47 And this fact is used to later on pair the client and server.
  48
  49 The STUN server reports this information directly to the Game Coordinator
  50 (this in contrast to most STUN implementation, where this information is
  51 first reported back to the peer itself, which has to relay it back to the
  52 coordinator. OpenTTD skips this step, as the STUN server can directly talk to
  53 the Game Coordinator). When the Game Coordinator sees a matching pair (in
  54 terms of IPv4 / IPv6), it will ask both the client and server to connect to
  55 their peer based on this public IP + port.
  56
  57 As the NAT gateway forwards the traffic on the public IP + port to the local
  58 port, this creates a bi-directional socket between client and server. The
  59 connection to the STUN server can now safely be closed, and the client and
  60 server can continue to talk to each other.
  61
  62 Some NAT gateways do not allow this method; for those this attempt will fail,
  63 and this also means that it is not possible to create a connection between
  64 the client and server.
  65
  66 ## 3) Via TURN
  67
  68 As a last resort, the Game Coordinator can decide to connect the client and
  69 server together via TURN. TURN is a relay service, relaying the messages
  70 between client and server.
  71
  72 As the client and server can already connect to the Game Coordinator, it is
  73 very likely this is successful.
  74
  75 It is important to note that a relay service has full view of the traffic
  76 send between client and server, and as such it is important that you trust
  77 the relay service used.
  78 For official binaries, this relay service is hosted by openttd.org. The relay
  79 service as hosted by openttd.org only validates it is relaying valid OpenTTD
  80 packets and does no further inspection of the payload itself.
  81 Although in our experience most patch-packs also use the services as offered
  82 by openttd.org, it is possible they use different services. Please be mindful
  83 about this.