Merge branch 'master' into jgrpp-beta

# Conflicts:
#	src/console_cmds.cpp
#	src/debug.cpp
#	src/lang/vietnamese.txt
#	src/network/core/address.cpp
#	src/network/core/address.h
#	src/network/core/config.h
#	src/network/core/os_abstraction.cpp
#	src/network/core/os_abstraction.h
#	src/network/core/tcp_listen.h
#	src/network/core/udp.cpp
#	src/network/core/udp.h
#	src/network/network.cpp
#	src/network/network_client.cpp
#	src/network/network_gamelist.cpp
#	src/network/network_server.cpp
#	src/network/network_udp.cpp
#	src/newgrf.cpp
#	src/openttd.cpp
#	src/saveload/saveload.h
#	src/settings.cpp
#	src/settings_table.cpp
#	src/settings_type.h
#	src/table/settings/network_settings.ini

docs/game_coordinator.md

@@ -0,0 +1,64 @@
+# Game Coordinator
+
+To allow two players to play together, OpenTTD uses a Game Coordinator to
+facilitate this.
+
+When a server starts, it can register itself to the Game Coordinator. This
+happens when `server_game_type` is set to either `invite-only` or `public`.
+Upon registration, the Game Coordinator probes the network of the server, and
+assigns the server an unique code, called an `invite code`.
+
+When a client wants to join a server, it asks the Game Coordinator to help
+with this by giving it the `invite code` of the server. The Game Coordinator
+will, in this order, attempt several ways to connect the client and server
+together:
+
+## 1) Via direct IPv4 / IPv6
+
+Upon registration, the Game Coordinator probes the server to see if a
+direction connection to the server is possible based on the game port. It
+tries this over the public IPv4 and IPv6, as announced by the server.
+If either (or both) are successful, a client will always be asked to try
+these direct IPs first when it wants to connect to this server.
+
+- If the server is IPv4 only, the client is only asked to connect via IPv4.
+- If the server is IPv6 only, the client is only asked to connect via IPv6.
+- If the server is both IPv4 and IPv6, the client is asked to connect to to
+  one of those first. If that fails, it is asked to connect to the other.
+  Whether it tries IPv4 or IPv6 first, strongly depends on several network
+  infrastructure related events. The biggest influence is the network
+  latency over both protocols to the OpenTTD infrastructure.
+
+In the end, if either the server is not reachable directly from the Internet
+or the client fails to connect to either one of them, the connection attempt
+continues with the next available method.
+
+## 2) Via STUN
+
+When a client wants to join a server via STUN, both the client and server
+are asked to create a connection to the STUN server (normally
+`stun.openttd.org`) via both IPv4 and IPv6. If the client or server has no
+IPv4 or IPv6, it will not make a connection attempt via that protocol.
+
+The STUN server collects the public IPv4 and/or IPv6 of the client and server,
+together with the port the connection came in from. For most NAT gateways it
+holds true that as long as you use the same local IP + port, your public
+IP + port will remain the same, and allow for bi-directional communication.
+And this fact is used to later on pair the client and server.
+
+The STUN server reports this information directly to the Game Coordinator
+(this in contrast to most STUN implementation, where this information is
+first reported back to the peer itself, which has to relay it back to the
+coordinator. OpenTTD skips this step, as the STUN server can directly talk to
+the Game Coordinator). When the Game Coordinator sees a matching pair (in
+terms of IPv4 / IPv6), it will ask both the client and server to connect to
+their peer based on this public IP + port.
+
+As the NAT gateway forwards the traffic on the public IP + port to the local
+port, this creates a bi-directional socket between client and server. The
+connection to the STUN server can now safely be closed, and the client and
+server can continue to talk to each other.
+
+Some NAT gateways do not allow this method; for those this attempt will fail,
+and this also means that it is not possible to create a connection between
+the client and server.

docs/multiplayer.md

@@ -48,6 +48,10 @@ Last updated:    2011-02-16
     - click add server
     - type in the ip address or hostname
     - if you want to add a port use :<port>
+ - If you want to play and you have the invite code of the game server you
+   want connect to.
+    - click add server
+    - type in the invite code
  - Now you can select a company and press: "Join company", to help that company
     - Or you can press "Spectate game", to spectate the game
     - Or you can press "New company", and start your own company (if there are
@@ -110,9 +114,10 @@ Last updated:    2011-02-16
  - You can let your server automatically restart a map when, let's say, year 2030
    is reached. See 'set restart_game_date' for detail.
 
- - If you want to be on the server-list, enable Advertising. To do this, select
-   'Internet (advertise)' in the Start Server menu, or type in console:
-   'set server_advertise 1'.
+ - If you want to be on the server-list, make your server public. You can do
+   this either from the Start Server GUI, via the in-game Online Players GUI,
+   or by typing in the console:
+   'set server_game_type public'.
 
  - You can protect your server with a password via the console: 'set server_pw',
    or via the Start Server menu.