From 1cd13ce89c3b642772fd74c5969fcfeb6ae69ebb Mon Sep 17 00:00:00 2001 From: Max Hilbrunner Date: Tue, 18 Jul 2023 15:47:50 +0200 Subject: [PATCH] Merge pull request #7637 from Calinou/update-command-line-tutorial --- .../exporting_for_dedicated_servers.rst | 285 +++++------------- 1 file changed, 79 insertions(+), 206 deletions(-) diff --git a/tutorials/export/exporting_for_dedicated_servers.rst b/tutorials/export/exporting_for_dedicated_servers.rst index 01ad78052ae..8fe2a04b7a4 100644 --- a/tutorials/export/exporting_for_dedicated_servers.rst +++ b/tutorials/export/exporting_for_dedicated_servers.rst @@ -1,275 +1,148 @@ +: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 run Godot with the ``headless`` -display server and ``Dummy`` :ref:`audio driver `. +have a GPU or display server available, you'll need to use a server build of Godot. -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. +Platform support +---------------- -Editor versus export template ------------------------------ +- **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. + +If your project uses C#, you'll have to use a Mono-enabled server binary. -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: +"Headless" versus "server" binaries +----------------------------------- -- **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 +The `server download page `__ +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. -Export approaches ------------------ +Exporting a PCK file +-------------------- There are two ways to export a project for a server: -- 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. - -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. - -.. _doc_exporting_for_dedicated_servers_exporting_project: - -Exporting a project for a dedicated 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. -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. +Both methods should result in identical output. The text below describes the PCK +file approach. -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). +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. -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. +See :ref:`doc_exporting_projects` for more information. .. note:: - 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: + 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. -.. figure:: img/exporting_for_dedicated_servers_export_resources.webp - :align: center - :alt: Choosing resources to keep, keep with stripped visuals or remove - - Choosing resources to keep, keep with stripped visuals or remove - -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. +.. note:: -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. + 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. -- **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. + 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. -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. +Preparing the server distribution +--------------------------------- -.. tip:: +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:: - 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. + ./godot-server --main-pack my_project.pck .. warning:: - 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 + 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. 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. - -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: +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: .. tabs:: .. code-tab:: gdscript - # Note: Feature tags are case-sensitive. - if OS.has_feature("dedicated_server"): + if "--server" in OS.get_cmdline_args(): # 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 (editor or export template) with the `--headless` - # command-line argument. + # a Godot binary (headless or not) with the `--server` command-line argument. pass .. code-tab:: csharp using System.Linq; - if (OS.GetCmdlineArgs().Contains("--headless")) + if (OS.GetCmdlineArgs().Contains("--server")) { // Run your server startup code here... - // // Using this check, you can start a dedicated server by running - // a Godot binary (editor or export template) with the `--headless` - // command-line argument. + // a Godot binary (headless or not) with the `--server` command-line argument. } -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: +Alternatively, you can make the dedicated server always start up if a headless +or server binary is detected: .. tabs:: .. code-tab:: gdscript - if "--server" in OS.get_cmdline_user_args(): + # Note: Feature tags are case-sensitive! It's "server", not "Server". + if OS.has_feature("server"): # Run your server startup code here... - # - # Using this check, you can start a dedicated server by running - # a Godot binary (editor or export template) with the `--server` - # command-line argument. + # Note that using this check may break unit testing scripts when + # running them with headless or server binaries. pass .. code-tab:: csharp - using System.Linq; - - if (OS.GetCmdlineUserArgs().Contains("--server")) + // Note: Feature tags are case-sensitive! It's "server", not "Server". + if (OS.HasFeature("server")) { // Run your server startup code here... - // - // Using this check, you can start a dedicated server by running - // a Godot binary (editor or export template) with the `--server` - // command-line argument. + // Note that using this check may break unit testing scripts when + // running them with headless or server binaries. } -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.