Merge pull request godotengine#7701 from Calinou/update-exporting-for-dedicated-servers

Author: mhilbrunner

tutorials/export/exporting_for_dedicated_servers.rst

@@ -1,148 +1,275 @@
-:article_outdated: True
-
 .. _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_macos>`.
-- **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. Note that even with the ``--no-window`` command-line argument,
-  you'll need to have OpenGL support available on the Windows machine.
+have a GPU or display server available, you'll need run Godot with the ``headless``
+display server and ``Dummy`` :ref:`audio driver <class_ProjectSettings_property_audio/driver/driver>`.
 
-If your project uses C#, you'll have to use a Mono-enabled server binary.
+Since Godot 4.0, this can be done by running a Godot binary on any platform with
+the ``--headless`` command line argument, or running a project exported as
+dedicated server. You do not need to use a specialized server binary anymore,
+unlike Godot 3.x.
 
-"Headless" versus "server" binaries
------------------------------------
+Editor versus export template
+-----------------------------
 
-The `server download page <https://godotengine.org/download/server>`__
-offers two kinds of binaries with several differences.
+It is possible to use either an editor or export template (debug or release)
+binary in headless mode. Which one you should use depends on your use case:
 
-- **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
+- **Export template:** Use this one for running dedicated servers. It does not
+  contain editor functionality, and is therefore smaller and more optimized.
+- **Editor:** 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
---------------------
+Export approaches
+-----------------
 
 There are two ways to export a project for a server:
 
-- Create a Linux/X11 export preset, define a custom Release export template
-  that points to the server binary then export the project as usual.
-- Export a PCK file only, preferably from a Linux/X11 export preset.
-
-Both methods should result in identical output. The text below describes the PCK
-file approach.
+- Create a separate export preset for the platform that will host the server, then
+  export your project as usual.
+- Export a PCK file only, preferably for the platform that matches the platform
+  that will host the server. Place this PCK file in the same folder as an export
+  template binary, rename the binary to have the same name as the PCK (minus the
+  file extension), then run the binary.
 
-Once you've downloaded a server binary, you should export a PCK file containing
-your project data. 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.
+Both methods should result in identical output. The rest of the page will focus
+on the first approach.
 
 See :ref:`doc_exporting_projects` for more information.
 
-.. note::
+.. _doc_exporting_for_dedicated_servers_exporting_project:
+
+Exporting a project for a dedicated server
+------------------------------------------
+
+If you export a project as usual when targeting a server, you will notice that
+the PCK file is just as large as for the client. This is because it includes all
+resources, including those the server doesn't need (such as texture data).
+Additionally, headless mode won't be automatically used; the user will have to
+specify ``--headless`` to make sure no window spawns.
+
+Many resources such as textures can be stripped from the PCK file to greatly
+reduce its size. Godot offers a way to do this for textures and materials in a way
+that preserves references in scene or resource files (built-in or external).
 
-    If you're exporting the project from a headless editor, call the headless
-    editor with the ``--export-pack`` option while in the project folder to export
-    only a PCK file.
+To begin doing so, make sure you have a dedicated export preset for your server,
+then select it, go to its **Resources** tab and change its export mode:
+
+.. figure:: img/exporting_for_dedicated_servers_export_mode.webp
+   :align: center
+   :alt: Choosing the **Export as dedicated server** export mode in the export preset
+
+   Choosing the **Export as dedicated server** export mode in the export preset
+
+When this export mode is chosen, the ``dedicated_server`` feature tag is
+automatically added to the exported project.
 
 .. 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.
+    If you do not wish to use this
+    export mode but still want the feature tag, you can write the name
+    ``dedicated_server`` in the **Features** tab of the export preset.
+    This will also force ``--headless`` when running the exported project.
+
+After selecting this export mode, you will be presented with a list of resources
+in the project:
+
+.. figure:: img/exporting_for_dedicated_servers_export_resources.webp
+   :align: center
+   :alt: Choosing resources to keep, keep with stripped visuals or remove
 
-    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.
+   Choosing resources to keep, keep with stripped visuals or remove
 
-Preparing the server distribution
----------------------------------
+Ticking a box allows you to override options for the specified file or folder.
+Checking boxes does **not** affect which files are exported; this is done by the
+options selected for each checkbox instead.
 
-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::
+Files within a checked folder will automatically use the parent's option by
+default, which is indicated by the **(Inherited)** suffix for the option name
+(and the option name being grayed out). To change the option for a file whose
+option is currently inherited, you must tick the box next to it first.
 
-    ./godot-server --main-pack my_project.pck
+- **Strip Visuals:** Export this resource, with visual files (textures and materials)
+  replaced by placeholder classes. Placeholder classes store the image size
+  (as it's sometimes used to position elements in a 2D scene), but nothing else.
+- **Keep:** Export this resource as usual, with visual files interact.
+- **Remove:** The file is not included in the PCK. This is useful to ignore
+  scenes and resources that only the client needs. If you do so, make sure the
+  server doesn't reference these client-only scenes and resources in any way.
+
+The general recommendation is to use **Strip Visuals** whenever possible, unless
+the server needs to access image data such as pixels' colors. For example, if
+your server generates collision data based on an image's contents, you need to
+use **Keep** for that particular image.
+
+.. tip::
+
+    To check the file structure of your exported PCK, use the **Export
+    PCK/ZIP...** button with a ``.zip`` file extension, then open the resulting
+    ZIP file in a file manager.
 
 .. warning::
 
-    Make sure the aforementioned ``godot-server`` has the executable permission
-    defined by running ``chmod +x godot-server`` (if the binary is called
-    ``godot-server``). Otherwise, you may get a "command not found" or
-    "permission denied" error message when trying to run the Godot server
-    binary.
+    Be careful when using the **Remove** mode, as scenes/resources that reference
+    a removed file will no longer be able to load successfully.
+
+    If you wish to remove specific resources but make the scenes still be able
+    to load without them, you'll have to remove the reference in the scene file
+    and load the files to the nodes' properties using ``load()`` in a script.
+    This approach can be used to strip resources that Godot doesn't support
+    replacing with placeholders yet, such as audio.
+
+    Removing textures is often what makes the greatest impact on the PCK size,
+    so it is recommended to stick with **Strip Visuals** at first.
+
+With the above options used, a PCK for the client (which exports all resources
+normally) will look as follows:
+
+.. highlight:: none
+
+::
+
+    .
+    ├── .godot
+    │   ├── exported
+    │   │   └── 133200997
+    │   │       └── export-78c237d4bfdb4e1d02e0b5f38ddfd8bd-scene.scn
+    │   ├── global_script_class_cache.cfg
+    │   ├── imported
+    │   │   ├── map_data.png-ce840618f399a990343bfc7298195a13.ctex
+    │   │   ├── music.ogg-fa883da45ae49695a3d022f64e60aee2.oggvorbisstr
+    │   │   └── sprite.png-7958af25f91bb9dbae43f35388f8e840.ctex
+    │   └── uid_cache.bin
+    ├── client
+    │   ├── music.ogg.import
+    │   └── sprite.png.import
+    ├── server
+    │   └── map_data.png.import
+    ├── test
+    │   └── scene.gd
+    └── unused
+    │   └── development_test.gd
+    ├── project.binary
+    ├── scene.gd
+    ├── scene.tscn.remap
+
+The PCK's file structure for the server will look as follows:
+
+.. highlight:: none
+
+::
+
+    .
+    ├── .godot
+    │   ├── exported
+    │   │   └── 3400186661
+    │   │       ├── export-78c237d4bfdb4e1d02e0b5f38ddfd8bd-scene.scn
+    │   │       ├── export-7958af25f91bb9dbae43f35388f8e840-sprite.res  # Placeholder texture
+    │   │       └── export-fa883da45ae49695a3d022f64e60aee2-music.res
+    │   ├── global_script_class_cache.cfg
+    │   ├── imported
+    │   │   └── map_data.png-ce840618f399a990343bfc7298195a13.ctex
+    │   └── uid_cache.bin
+    ├── client
+    │   ├── music.ogg.import
+    │   └── sprite.png.import  # Points to placeholder texture
+    └── server
+    │   └── map_data.png.import
+    ├── project.binary
+    ├── scene.gd
+    ├── scene.tscn.remap
 
 Starting the dedicated server
 -----------------------------
 
 If both your client and server are part of the same Godot project, you will have
-to add a way to start the server directly using a command-line argument. This
-can be done by adding the following code snippet in your main scene (or a
-singleton)'s ``_ready()`` method:
+to add a way to start the server directly using a command-line argument.
+
+If you :ref:`exported the project <doc_exporting_for_dedicated_servers_exporting_project>`
+using the **Export as dedicated server** export mode (or have added
+``dedicated_server`` as a custom feature tag), you can use the ``dedicated_server``
+feature tag to detect whether a dedicated server PCK is being used:
 
 .. tabs::
  .. code-tab:: gdscript
 
-    if "--server" in OS.get_cmdline_args():
+    # Note: Feature tags are case-sensitive.
+    if OS.has_feature("dedicated_server"):
         # Run your server startup code here...
+        pass
+
+ .. code-tab:: csharp
+
+    // Note: Feature tags are case-sensitive.
+    if (OS.HasFeature("dedicated_server"))
+    {
+        // Run your server startup code here...
+    }
+
+If you also wish to host a server when using the built-in ``--headless`` command
+line argument, this can be done by adding the following code snippet in your
+main scene (or an autoload)'s ``_ready()`` method:
+
+.. tabs::
+ .. code-tab:: gdscript
+
+    if "--headless" in OS.get_cmdline_args():
+        # Run your server startup code here...
+        #
         # Using this check, you can start a dedicated server by running
-        # a Godot binary (headless or not) with the `--server` command-line argument.
+        # a Godot binary (editor or export template) with the `--headless`
+        # command-line argument.
         pass
 
  .. code-tab:: csharp
 
     using System.Linq;
 
-    if (OS.GetCmdlineArgs().Contains("--server"))
+    if (OS.GetCmdlineArgs().Contains("--headless"))
     {
         // Run your server startup code here...
+        //
         // Using this check, you can start a dedicated server by running
-        // a Godot binary (headless or not) with the `--server` command-line argument.
+        // a Godot binary (editor or export template) with the `--headless`
+        // command-line argument.
     }
 
-Alternatively, you can make the dedicated server always start up if a headless
-or server binary is detected:
+If you wish to use a custom command line argument, this can be done by adding
+the following code snippet in your main scene (or an autoload)'s ``_ready()``
+method:
 
 .. tabs::
  .. code-tab:: gdscript
 
-    # Note: Feature tags are case-sensitive! It's "server", not "Server".
-    if OS.has_feature("server"):
+    if "--server" in OS.get_cmdline_user_args():
         # Run your server startup code here...
-        # Note that using this check may break unit testing scripts when
-        # running them with headless or server binaries.
+        #
+        # Using this check, you can start a dedicated server by running
+        # a Godot binary (editor or export template) with the `--server`
+        # command-line argument.
         pass
 
  .. code-tab:: csharp
 
-    // Note: Feature tags are case-sensitive! It's "server", not "Server".
-    if (OS.HasFeature("server"))
+    using System.Linq;
+
+    if (OS.GetCmdlineUserArgs().Contains("--server"))
     {
         // Run your server startup code here...
-        // Note that using this check may break unit testing scripts when
-        // running them with headless or server binaries.
+        //
+        // Using this check, you can start a dedicated server by running
+        // a Godot binary (editor or export template) with the `--server`
+        // command-line argument.
     }
 
+It's a good idea to add at least one of the above command-line arguments to
+start a server, as it can be used to test server functionality from the command
+line without having to export the project.
+
 If your client and server are separate Godot projects, your server should most
 likely be configured in a way where running the main scene starts a server
 automatically.