diff --git a/tutorials/export/exporting_for_dedicated_servers.rst b/tutorials/export/exporting_for_dedicated_servers.rst index 8fe2a04b7a4..01ad78052ae 100644 --- a/tutorials/export/exporting_for_dedicated_servers.rst +++ b/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 `__. - 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 `. -- **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 `. -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 `__ -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 ` +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. diff --git a/tutorials/export/img/exporting_for_dedicated_servers_export_mode.webp b/tutorials/export/img/exporting_for_dedicated_servers_export_mode.webp new file mode 100644 index 00000000000..7beffe1e615 Binary files /dev/null and b/tutorials/export/img/exporting_for_dedicated_servers_export_mode.webp differ diff --git a/tutorials/export/img/exporting_for_dedicated_servers_export_resources.webp b/tutorials/export/img/exporting_for_dedicated_servers_export_resources.webp new file mode 100644 index 00000000000..cc55abc562e Binary files /dev/null and b/tutorials/export/img/exporting_for_dedicated_servers_export_resources.webp differ