Skip to content

Commit

Permalink
Merge pull request godotengine#7637 from Calinou/update-command-line-…
Browse files Browse the repository at this point in the history 
…tutorial
  • Loading branch information
@mhilbrunner
mhilbrunner authored and Nathan Hunt committed Sep 25, 2023
1 parent 02fa159 commit 1cd13ce
Showing 1 changed file with 79 additions and 206 deletions.
285 changes: 79 additions & 206 deletions tutorials/export/exporting_for_dedicated_servers.rst
View file
Original file line number Diff line number Diff line change
@@ -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 <class_ProjectSettings_property_audio/driver/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 <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.

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 <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.

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 <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:
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.
Expand Down

0 comments on commit 1cd13ce

Please sign in to comment.