Merge pull request #3557 from Calinou/add-exporting-for-servers

Add documentation about exporting for dedicated servers

development/compiling/compiling_for_linuxbsd.rst

@@ -92,7 +92,7 @@ Start a terminal, go to the root dir of the engine source code and type:
 
 ::
 
-    user@host:~/godot$ scons -j8 platform=linuxbsd
+    scons -j8 platform=linuxbsd
 
 A good rule of thumb for the ``-j`` (*jobs*) flag, is to have at least as many
 threads compiling Godot as you have cores in your CPU, if not one or two more.
@@ -109,7 +109,7 @@ manager.
 
     ::
 
-        user@host:~/godot$ scons platform=linuxbsd use_llvm=yes
+        scons platform=linuxbsd use_llvm=yes
 
     Using Clang appears to be a requirement for OpenBSD, otherwise fonts
     would not build.
@@ -128,6 +128,19 @@ manager.
           :ref:`doc_data_paths_self_contained_mode` by creating a file called
           ``._sc_`` or ``_sc_`` in the ``bin/`` folder.
 
+Compiling a headless/server build
+---------------------------------
+
+To compile a *headless* build which provides editor functionality to export
+projects in an automated manner, use::
+
+    scons -j8 platform=server tools=yes target=release_debug
+
+To compile a *server* build which is optimized to run dedicated game servers,
+use::
+
+    scons -j8 platform=server tools=no target=release
+
 Building export templates
 -------------------------
 
@@ -146,15 +159,15 @@ following parameters:
 
 ::
 
-    user@host:~/godot$ scons platform=linuxbsd tools=no target=release bits=32
-    user@host:~/godot$ scons platform=linuxbsd tools=no target=release_debug bits=32
+    scons platform=linuxbsd tools=no target=release bits=32
+    scons platform=linuxbsd tools=no target=release_debug bits=32
 
 -  (64 bits)
 
 ::
 
-    user@host:~/godot$ scons platform=linuxbsd tools=no target=release bits=64
-    user@host:~/godot$ scons platform=linuxbsd tools=no target=release_debug bits=64
+    scons platform=linuxbsd tools=no target=release bits=64
+    scons platform=linuxbsd tools=no target=release_debug bits=64
 
 Note that cross-compiling for the opposite bits (64/32) as your host
 platform is not always straight-forward and might need a chroot environment.
@@ -197,7 +210,7 @@ the default GCC + GNU ld setup:
 To do so, install Clang and the ``lld`` package from your distribution's package manager
 then use the following SCons command::
 
-    user@host:~/godot$ scons platform=linuxbsd use_llvm=yes use_lld=yes
+    scons platform=linuxbsd use_llvm=yes use_lld=yes
 
 It's still recommended to use GCC for production builds as they can be compiled using
 link-time optimization, making the resulting binaries smaller and faster.

development/compiling/compiling_for_osx.rst

@@ -51,10 +51,23 @@ To create an ``.app`` bundle like in the official builds, you need to use the
 template located in ``misc/dist/osx_tools.app``. Typically, for an optimized
 editor binary built with ``scons p=osx target=release_debug``::
 
-    user@host:~/godot$ cp -r misc/dist/osx_tools.app ./Godot.app
-    user@host:~/godot$ mkdir -p Godot.app/Contents/MacOS
-    user@host:~/godot$ cp bin/godot.osx.tools.64 Godot.app/Contents/MacOS/Godot
-    user@host:~/godot$ chmod +x Godot.app/Contents/MacOS/Godot
+    cp -r misc/dist/osx_tools.app ./Godot.app
+    mkdir -p Godot.app/Contents/MacOS
+    cp bin/godot.osx.tools.64 Godot.app/Contents/MacOS/Godot
+    chmod +x Godot.app/Contents/MacOS/Godot
+
+Compiling a headless/server build
+---------------------------------
+
+To compile a *headless* build which provides editor functionality to export
+projects in an automated manner, use::
+
+    scons platform=server tools=yes target=release_debug --jobs=$(sysctl -n hw.logicalcpu)
+
+To compile a *server* build which is optimized to run dedicated game servers,
+use::
+
+    scons platform=server tools=no target=release --jobs=$(sysctl -n hw.logicalcpu)
 
 Cross-compiling for macOS from Linux
 ------------------------------------
@@ -68,7 +81,7 @@ Clone the `OSXCross repository <https://github.com/tpoechtrager/osxcross>`__
 somewhere on your machine (or download a ZIP file and extract it somewhere),
 e.g.::
 
-    user@host:~$ git clone --depth=1 https://github.com/tpoechtrager/osxcross.git "$HOME/osxcross"
+    git clone --depth=1 https://github.com/tpoechtrager/osxcross.git "$HOME/osxcross"
 
 1. Follow the instructions to package the SDK:
    https://github.com/tpoechtrager/osxcross#packaging-the-sdk
@@ -79,12 +92,12 @@ After that, you will need to define the ``OSXCROSS_ROOT`` as the path to
 the OSXCross installation (the same place where you cloned the
 repository/extracted the zip), e.g.::
 
-    user@host:~$ export OSXCROSS_ROOT="$HOME/osxcross"
+    export OSXCROSS_ROOT="$HOME/osxcross"
 
 Now you can compile with SCons like you normally would::
 
-    user@host:~/godot$ scons platform=osx
+    scons platform=osx
 
 If you have an OSXCross SDK version different from the one expected by the SCons buildsystem, you can specify a custom one with the ``osxcross_sdk`` argument::
 
-    user@host:~/godot$ scons platform=osx osxcross_sdk=darwin15
+    scons platform=osx osxcross_sdk=darwin15

development/compiling/compiling_for_windows.rst

@@ -219,8 +219,8 @@ To make sure you are doing things correctly, executing the following in
 the shell should result in a working compiler (the version output may
 differ based on your system)::
 
-    user@host:~$ ${MINGW32_PREFIX}gcc --version
-    i686-w64-mingw32-gcc (GCC) 6.1.0 20160427 (Mageia MinGW 6.1.0-1.mga6)
+    ${MINGW32_PREFIX}gcc --version
+    # i686-w64-mingw32-gcc (GCC) 6.1.0 20160427 (Mageia MinGW 6.1.0-1.mga6)
 
 Troubleshooting
 ~~~~~~~~~~~~~~~

development/compiling/introduction_to_the_buildsystem.rst

@@ -62,7 +62,7 @@ It will then start building for the target platform right away.
 
 To list the available target platforms, use ``scons platform=list``::
 
-    user@host:~/godot$ scons platform=list
+    scons platform=list
     scons: Reading SConscript files ...
     The following platforms are available:
 
@@ -79,7 +79,7 @@ To build for a platform (for example, ``linuxbsd``), run with the ``platform=``
 
 ::
 
-    user@host:~/godot$ scons platform=linuxbsd
+    scons platform=linuxbsd
 
 This will start the build process, which will take a while. If you want
 SCons to build faster, use the ``-j <cores>`` parameter to specify how many
@@ -90,7 +90,7 @@ Example for using 4 cores:
 
 ::
 
-    user@host:~/godot$ scons platform=linuxbsd -j 4
+    scons platform=linuxbsd -j 4
 
 Resulting binary
 ----------------
@@ -102,7 +102,7 @@ generally with this naming convention::
 
 For the previous build attempt, the result would look like this::
 
-    user@host:~/godot$ ls bin
+    ls bin
     bin/godot.linuxbsd.tools.64
 
 This means that the binary is for Linux *or* \*BSD (*not* both), is not optimized, has tools (the

development/cpp/custom_modules_in_cpp.rst

@@ -387,8 +387,8 @@ during runtime with the ``LD_LIBRARY_PATH`` environ variable:
 
 .. code-block:: shell
 
-    user@host:~/godot$ export LD_LIBRARY_PATH=`pwd`/bin/
-    user@host:~/godot$ ./bin/godot*
+    export LD_LIBRARY_PATH=`pwd`/bin/
+    ./bin/godot*
 
 **note**: Pay attention you have to ``export`` the environ variable otherwise
 you won't be able to play your project from within the editor.
@@ -433,7 +433,7 @@ shared module as target in the SCons command:
 
 .. code-block:: shell
 
-    user@host:~/godot$ scons summator_shared=yes platform=linuxbsd bin/libsummator.linuxbsd.tools.64.so
+    scons summator_shared=yes platform=linuxbsd bin/libsummator.linuxbsd.tools.64.so
 
 Writing custom documentation
 ----------------------------

getting_started/editor/command_line_tutorial.rst

@@ -158,19 +158,19 @@ of your project as either the first argument, like this:
 
 ::
 
-    user@host:~$ godot path_to_your_project/project.godot [other] [commands] [and] [args]
+    godot path_to_your_project/project.godot [other] [commands] [and] [args]
 
 Or by using the ``--path`` argument:
 
 ::
 
-    user@host:~$ godot --path path_to_your_project [other] [commands] [and] [args]
+    godot --path path_to_your_project [other] [commands] [and] [args]
 
 For example, the full command for exporting your game (as explained below) might look like this:
 
 ::
 
-    user@host:~$ godot --path path_to_your_project --export my_export_preset_name game.exe
+    godot --path path_to_your_project --export my_export_preset_name game.exe
 
 Creating a project
 ------------------
@@ -182,9 +182,9 @@ shell to the desired place and making a project.godot file.
 
 ::
 
-    user@host:~$ mkdir newgame
-    user@host:~$ cd newgame
-    user@host:~/newgame$ touch project.godot
+    mkdir newgame
+    cd newgame
+    touch project.godot
 
 
 The project can now be opened with Godot.
@@ -199,14 +199,14 @@ otherwise the command is ignored and the project manager appears.
 
 ::
 
-    user@host:~/newgame$ godot -e
+    godot -e
 
 If a scene has been created and saved, it can be edited later by running
 the same code with that scene as argument.
 
 ::
 
-    user@host:~/newgame$ godot -e scene.tscn
+    godot -e scene.tscn
 
 Erasing a scene
 ---------------
@@ -217,7 +217,7 @@ references that scene or else an error will be thrown upon opening.
 
 ::
 
-    user@host:~/newgame$ rm scene.tscn
+    rm scene.tscn
 
 Running the game
 ----------------
@@ -227,14 +227,14 @@ subdirectory.
 
 ::
 
-    user@host:~/newgame$ godot
+    godot
 
 When a specific scene needs to be tested, pass that scene to the command
 line.
 
 ::
 
-    user@host:~/newgame$ godot scene.tscn
+    godot scene.tscn
 
 Debugging
 ---------
@@ -245,11 +245,11 @@ just fly by. For this, a command line debugger is provided by adding
 
 ::
 
-    user@host:~/newgame$ godot -d
+    godot -d
 
 ::
 
-    user@host:~/newgame$ godot -d scene.tscn
+    godot -d scene.tscn
 
 .. _doc_command_line_tutorial_exporting:
 
@@ -262,8 +262,8 @@ that is headless (server build, no video) is ideal for this.
 
 ::
 
-    user@host:~/newgame$ godot --export "Linux/X11" /var/builds/project
-    user@host:~/newgame$ godot --export Android /var/builds/project.apk
+    godot --export "Linux/X11" /var/builds/project
+    godot --export Android /var/builds/project.apk
 
 The platform names recognized by the ``--export`` switch are the same as
 displayed in the export wizard of the editor. To get a list of supported
@@ -287,7 +287,7 @@ Here is a simple example of how it works:
 
 .. code-block:: python
 
-    #sayhello.gd
+    # sayhello.gd
     extends SceneTree
 
     func _init():
@@ -298,8 +298,8 @@ And how to run it:
 
 ::
 
-    user@host:~/newgame$ godot -s sayhello.gd
-    Hello!
+    # Prints "Hello!" to standard output.
+    godot -s sayhello.gd
 
 If no project.godot exists at the path, current path is assumed to be the
 current working directory (unless ``-path`` is specified).

getting_started/workflow/export/exporting_for_dedicated_servers.rst

@@ -0,0 +1,83 @@
+.. _doc_exporting_for_dedicated_servers:
+
+Exporting for dedicated servers
+===============================
+
+If you want to run a dedicated server for your project on a machine that doesn't
+have a GPU or display server available, you'll need to use a server build of Godot.
+
+Platform support
+----------------
+
+- **Linux:** `Download an official Linux server binary <https://godotengine.org/download/server>`__.
+  To compile a server binary from source, follow instructions in
+  :ref:`doc_compiling_for_linuxbsd`.
+- **macOS:** :ref:`Compile a server binary from source for macOS <doc_compiling_for_osx>`.
+- **Windows:** There is no dedicated server build for Windows yet. As an alternative,
+  you can use the ``--no-window`` command-line argument to prevent Godot from
+  spawning a window.
+
+If your project uses C#, you'll have to use a Mono-enabled server binary.
+
+"Headless" versus "server" binaries
+-----------------------------------
+
+The `server download page <https://godotengine.org/download/server>`__
+offers two kinds of binaries with several differences.
+
+- **Server:** Use this one for running dedicated servers. It does not contain
+  editor functionality, and is therefore smaller and more
+  optimized.
+- **Headless:** This binary contains editor functionality and is intended to be
+  used for exporting projects. This binary *can* be used to run dedicated
+  servers, but it's not recommended as it's larger and less optimized.
+
+Exporting a PCK file
+--------------------
+
+Once you've downloaded a server binary, you should export a PCK file containing
+your project data. It's recommended to create a Linux export preset for this
+purpose. After creating the export preset, click **Export PCK/ZIP** at the
+bottom of the Export dialog then choose a destination path.
+
+The **Export With Debug** checkbox in the file dialog has no bearing on the
+final PCK file, so you can leave it as-is.
+
+See :ref:`doc_exporting_projects` for more information.
+
+.. note::
+
+    The PCK file will include resources not normally needed by the server, such
+    as textures and sounds. This means the PCK file will be larger than it could
+    possibly be. Support for stripping unneeded resources from a PCK for server
+    usage is planned in a future Godot release.
+
+    On the bright side, this allows the same PCK file to be used both by a
+    client and dedicated server build. This can be useful if you want to ship a
+    single archive that can be used both as a client and dedicated server.
+
+Preparing the server distribution
+---------------------------------
+
+After downloading or compiling a server binary, you should now place it in the
+same folder as the PCK file you've exported. The server binary should have the
+same name as the PCK (excluding the extension). This lets Godot detect and use
+the PCK file automatically. If you want to start a server with a PCK that has a
+different name, you can specify the path to the PCK file using the
+``--main-pack`` command-line argument::
+
+    ./godot-server --main-pack my_project.pck
+
+Next steps
+----------
+
+On Linux, to make your dedicated server restart after a crash or system reboot,
+you can
+`create a systemd service <https://medium.com/@benmorel/creating-a-linux-service-with-systemd-611b5c8b91d6>`__.
+This also lets you view server logs in a more convenient fashion, with automatic
+log rotation provided by systemd.
+
+If you have experience with containers, you could also look into wrapping your
+dedicated server in a `Docker <https://www.docker.com/>`__ container. This way,
+it can be used more easily in an automatic scaling setup (which is outside the
+scope of this tutorial).

getting_started/workflow/export/index.rst

@@ -14,6 +14,7 @@ Export
    exporting_for_uwp
    exporting_for_android
    exporting_for_web
+   exporting_for_dedicated_servers
    one-click_deploy
    android_custom_build
    changing_application_icon_for_windows

tutorials/networking/high_level_multiplayer.rst

@@ -1,9 +1,9 @@
 .. _doc_high_level_multiplayer:
 
-High level multiplayer
+High-level multiplayer
 ======================
 
-High level vs low level API
+High-level vs low-level API
 ---------------------------
 
 The following explains the differences of high- and low-level networking in Godot as well as some fundamentals. If you want to jump in head-first and add networking to your first nodes, skip to `Initializing the network`_ below. But make sure to read the rest later on!
@@ -75,7 +75,7 @@ Initializing the network
 
 The object that controls networking in Godot is the same one that controls everything tree-related: :ref:`SceneTree <class_SceneTree>`.
 
-To initialize high level networking, the SceneTree must be provided a NetworkedMultiplayerPeer object.
+To initialize high-level networking, the SceneTree must be provided a NetworkedMultiplayerPeer object.
 
 To create that object, it first has to be initialized as a server or client.
 
@@ -336,7 +336,7 @@ In most games, the goal of multiplayer networking is that the game runs synchron
 Besides supplying an RPC and remote member variable set implementation, Godot adds the concept of network masters.
 
 Network master
-^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^
 
 The network master of a node is the peer that has the ultimate authority over it.
 
@@ -420,3 +420,17 @@ This may not make much sense for an area-of-effect case like the bomb, but in ot
 ::
 
     rpc_id(TARGET_PEER_ID, "stun") # Only stun the target peer
+
+Exporting for dedicated servers
+-------------------------------
+
+Once you've made a multiplayer game, you may want to export it to run it on
+a dedicated server with no GPU available. See
+:ref:`doc_exporting_for_dedicated_servers` for more information.
+
+.. note::
+
+    The code samples on this page aren't designed to run on a dedicated
+    server. You'll have to modify them so the server isn't considered to be a
+    player. You'll also have to modify the game starting mechanism so that the
+    first player who joins can start the game.