From c3a22b4364151e7de8dc5d60ac55b07678bf7b3a Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Mon, 28 Apr 2025 19:20:50 +0200 Subject: [PATCH] Add a Troubleshooting section to Exporting packs, patches and mods - Mention that the pack must be loaded early enough to have an effect. - Mention load order being important. - Mention ZIP format throughout the page, as it can be used in the same way as PCK files. - Link to Run-time resource loading and saving tutorial as an alternative. --- tutorials/export/exporting_pcks.rst | 83 +++++++++++++++++-------- tutorials/export/exporting_projects.rst | 2 + 2 files changed, 60 insertions(+), 25 deletions(-) diff --git a/tutorials/export/exporting_pcks.rst b/tutorials/export/exporting_pcks.rst index 1955d72d069..2af240a1005 100644 --- a/tutorials/export/exporting_pcks.rst +++ b/tutorials/export/exporting_pcks.rst @@ -6,7 +6,7 @@ Exporting packs, patches, and mods Use cases --------- -Oftentimes one would like to add functionality to one's game after it has been +Oftentimes, one would like to add functionality to one's game after it has been deployed. Examples of this include... @@ -18,11 +18,11 @@ Examples of this include... These tools help developers to extend their development beyond the initial release. -Overview of PCK files ---------------------- +Overview of PCK/ZIP files +------------------------- Godot enables this via a feature called **resource packs** (PCK files, -with extension ``.pck``). +with the ``.pck`` extension, or ZIP files). **Advantages:** @@ -35,9 +35,9 @@ with extension ``.pck``). The first part of using them involves exporting and delivering the project to players. Then, when one wants to add functionality or content later on, they -just deliver the updates via PCK files to the users. +just deliver the updates via PCK/ZIP files to the users. -PCK files usually contain, but are not limited to: +PCK/ZIP files usually contain, but are not limited to: - scripts - scenes @@ -48,21 +48,35 @@ PCK files usually contain, but are not limited to: - music - any other asset suitable for import into the game -The PCK files can even be an entirely different Godot project, which the +The PCK/ZIP files can even be an entirely different Godot project, which the original game loads in at runtime. +It is possible to load both PCK and ZIP files as additional packs at the same time. +See :ref:`doc_exporting_projects_pck_versus_zip` for a comparison of the two formats. + +.. seealso:: + + If you want to load loose files at runtime (not packed in a PCK or ZIP by Godot), + consider using :ref:`doc_runtime_loading_and_saving` instead. + This is useful for loading user-generated content that is not made with Godot, + without requiring users to pack their mods into a specific file format. + + The downside of this approach is that it's less transparent to the game logic, + as it will not benefit from the same resource management as PCK/ZIP files. + Generating PCK files -------------------- -In order to pack all resources of a project into a PCK file open the project -and go to Project/Export and click on "Export PCK/Zip". Also make sure to have -an export template selected while doing so. +In order to pack all resources of a project into a PCK file, open the project +and go to **Project > Export** and click on **Export PCK/ZIP**. Also, make sure +to have an export preset selected while doing so. .. image:: img/export_pck.webp -Another method would be to :ref:`export from the command line `. -If the output file ends with a PCK or ZIP file extension, then the export -process will build that type of file for the chosen platform. +Another method would be to :ref:`export from the command line ` +with ``--export-pack``. The output file must with a ``.pck`` or ``.zip`` +file extension. The export process will build that type of file for the +chosen platform. .. note:: @@ -86,19 +100,19 @@ process will build that type of file for the chosen platform. use a tool-build of the engine (for security), so it's best to keep the modding tool and game separate. -Opening PCK files at runtime ----------------------------- +Opening PCK or ZIP files at runtime +----------------------------------- -To import a PCK file, one uses the ProjectSettings singleton. The following -example expects a “mod.pck” file in the directory of the games executable. -The PCK file contains a “mod_scene.tscn” test scene in its root. +To load a PCK or ZIP file, one uses the ProjectSettings singleton. The following +example expects a ``mod.pck`` file in the directory of the game's executable. +The PCK or ZIP file contains a ``mod_scene.tscn`` test scene in its root. .. tabs:: .. code-tab:: gdscript GDScript func _your_function(): # This could fail if, for example, mod.pck cannot be found. - var success = ProjectSettings.load_resource_pack("res://mod.pck") + var success = ProjectSettings.load_resource_pack(OS.get_executable_path().get_base_dir().path_join("mod.pck")) if success: # Now one can use the assets as if they had them in the project from the start. @@ -109,7 +123,7 @@ The PCK file contains a “mod_scene.tscn” test scene in its root. private void YourFunction() { // This could fail if, for example, mod.pck cannot be found. - var success = ProjectSettings.LoadResourcePack("res://mod.pck"); + var success = ProjectSettings.LoadResourcePack(OS.get_executable_path().get_base_dir().path_join("mod.pck)); if (success) { @@ -120,20 +134,39 @@ The PCK file contains a “mod_scene.tscn” test scene in its root. .. warning:: - By default, if you import a file with the same file path/name as one you already have in your - project, the imported one will replace it. This is something to watch out for when - creating DLC or mods. You can solve this problem by using a tool that isolates mods to a specific mods subfolder. - However, it is also a way of creating patches for one's own game. A - PCK file of this kind can fix the content of a previously loaded PCK. + By default, if you import a file with the same file path/name as one you + already have in your project, the imported one will replace it. This is + something to watch out for when creating DLC or mods. You can solve this + problem by using a tool that isolates mods to a specific mods subfolder. + + However, it is also a way of creating patches for one's own game. A PCK/ZIP + file of this kind can fix the content of a previously loaded PCK/ZIP + (therefore, the order in which packs are loaded matters). To opt out of this behavior, pass ``false`` as the second argument to :ref:`ProjectSettings.load_resource_pack() `. .. note:: + For a C# project, you need to build the DLL and place it in the project directory first. Then, before loading the resource pack, you need to load its DLL as follows: ``Assembly.LoadFile("mod.dll")`` +Troubleshooting +^^^^^^^^^^^^^^^ + +If you are loading a resource pack and are not noticing any changes, it may be +due to the pack being loaded too late. This is particularly the case with menu +scenes that may preload other scenes using +:ref:`preload() `. This means that loading +a pack in the menu will not affect the other scene that was already preloaded. + +To avoid this, you need to load the pack as early as possible. +To do so, create a new :ref:`autoload ` script and +call :ref:`ProjectSettings.load_resource_pack() ` +in the autoload script's ``_init()`` function, rather than ``_enter_tree()`` +or ``_ready()``. + Summary ------- diff --git a/tutorials/export/exporting_projects.rst b/tutorials/export/exporting_projects.rst index f873e05b03b..d0d319730e7 100644 --- a/tutorials/export/exporting_projects.rst +++ b/tutorials/export/exporting_projects.rst @@ -220,6 +220,8 @@ the command: See :ref:`doc_command_line_tutorial` for more information about using Godot from the command line. +.. _doc_exporting_projects_pck_versus_zip: + PCK versus ZIP pack file formats --------------------------------