From ec77f48d5e59aa4f63f3da025e36966aaed9a8bd Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Mon, 18 May 2020 17:57:34 +0200 Subject: [PATCH] Add documentation about exporting for dedicated servers This also documents how to build dedicated server binaries. The part about compiling will need to be updated for Godot 4.0 once the server platform is usable again. This also removes prompts before commands so that they can be copy-pasted by triple-clicking without selecting the prompt. --- .../compiling/compiling_for_linuxbsd.rst | 27 ++++-- development/compiling/compiling_for_osx.rst | 29 +++++-- .../compiling/compiling_for_windows.rst | 4 +- .../introduction_to_the_buildsystem.rst | 8 +- development/cpp/custom_modules_in_cpp.rst | 6 +- .../editor/command_line_tutorial.rst | 36 ++++---- .../exporting_for_dedicated_servers.rst | 83 +++++++++++++++++++ getting_started/workflow/export/index.rst | 1 + .../networking/high_level_multiplayer.rst | 22 ++++- 9 files changed, 170 insertions(+), 46 deletions(-) create mode 100644 getting_started/workflow/export/exporting_for_dedicated_servers.rst diff --git a/development/compiling/compiling_for_linuxbsd.rst b/development/compiling/compiling_for_linuxbsd.rst index 665cdfd64..5bcce792f 100644 --- a/development/compiling/compiling_for_linuxbsd.rst +++ b/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. diff --git a/development/compiling/compiling_for_osx.rst b/development/compiling/compiling_for_osx.rst index 149328907..6f4e77f1e 100644 --- a/development/compiling/compiling_for_osx.rst +++ b/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 `__ 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 diff --git a/development/compiling/compiling_for_windows.rst b/development/compiling/compiling_for_windows.rst index 17dea2f41..922700332 100644 --- a/development/compiling/compiling_for_windows.rst +++ b/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 ~~~~~~~~~~~~~~~ diff --git a/development/compiling/introduction_to_the_buildsystem.rst b/development/compiling/introduction_to_the_buildsystem.rst index 91049d1d5..b7f893209 100644 --- a/development/compiling/introduction_to_the_buildsystem.rst +++ b/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 `` 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 diff --git a/development/cpp/custom_modules_in_cpp.rst b/development/cpp/custom_modules_in_cpp.rst index dfbe81ff5..66e3dd7b7 100644 --- a/development/cpp/custom_modules_in_cpp.rst +++ b/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 ---------------------------- diff --git a/getting_started/editor/command_line_tutorial.rst b/getting_started/editor/command_line_tutorial.rst index 43a69e686..5a014c762 100644 --- a/getting_started/editor/command_line_tutorial.rst +++ b/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). diff --git a/getting_started/workflow/export/exporting_for_dedicated_servers.rst b/getting_started/workflow/export/exporting_for_dedicated_servers.rst new file mode 100644 index 000000000..23c8acebc --- /dev/null +++ b/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 `__. + 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. + +If your project uses C#, you'll have to use a Mono-enabled server binary. + +"Headless" versus "server" binaries +----------------------------------- + +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. + +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 `__. +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 `__ container. This way, +it can be used more easily in an automatic scaling setup (which is outside the +scope of this tutorial). diff --git a/getting_started/workflow/export/index.rst b/getting_started/workflow/export/index.rst index b54c280c4..b19140079 100644 --- a/getting_started/workflow/export/index.rst +++ b/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 diff --git a/tutorials/networking/high_level_multiplayer.rst b/tutorials/networking/high_level_multiplayer.rst index 440f1bc75..4aa85c463 100644 --- a/tutorials/networking/high_level_multiplayer.rst +++ b/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 `. -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 in this page aren't designed to run from 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.