Skip to content

Commit d2a2eae

Browse files
skyace65skyace65
authored
Merge pull request #11706 from skyace65/Patching
Document Patch PCK files
1 parent 3fbed6f commit d2a2eae

1 file changed

Lines changed: 121 additions & 31 deletions

File tree

‎tutorials/export/exporting_pcks.rst‎

Lines changed: 121 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -64,12 +64,37 @@ See :ref:`doc_exporting_projects_pck_versus_zip` for a comparison of the two for
6464
The downside of this approach is that it's less transparent to the game logic,
6565
as it will not benefit from the same resource management as PCK/ZIP files.
6666

67+
Security concerns
68+
-----------------
69+
70+
It is important to note that loading PCK files for patches, mods, or extra content
71+
like expansions, will require you to code a system to automatically load files based
72+
on their location, and possibly name. This is a security vulnerability in three
73+
scenarios. One, a user downloads a mod with malicious code. Two, a malicious program
74+
already exists on an end user's PC and has replaced the PCK file with a malicious
75+
copy. Three, you are distributing patch PCK files through a game launcher and the
76+
system has become compromised.
77+
78+
Take this into consideration when determining how to use PCK files in a project.
79+
For situations where you have a patching system via a launcher, consider using
80+
asymmetric cryptography. You could store the public key in the main PCK, and sign
81+
patch or expansion PCK files with the private key. See the :ref:`class_Crypto` class
82+
for more information.
83+
84+
Copyright concerns
85+
------------------
86+
87+
If you want to use PCK files to distribute extra paid content, such as expansions,
88+
keep in mind that Godot provides no out-of-the-box way to prevent someone from
89+
copying the PCK file, and putting it on another person's computer. Any kind of DRM
90+
system is your responsibility to implement if that's what you want.
91+
6792
Generating PCK files
6893
--------------------
6994

7095
In order to pack all resources of a project into a PCK file, open the project
71-
and go to **Project > Export** and click on **Export PCK/ZIP**. Also, make sure
72-
to have an export preset selected while doing so.
96+
and go to :menu:`Project > Export`, select an export preset, and click on
97+
:button:`Export PCK/ZIP`.
7398

7499
.. image:: img/export_pck.webp
75100

@@ -78,27 +103,78 @@ with ``--export-pack``. The output file must with a ``.pck`` or ``.zip``
78103
file extension. The export process will build that type of file for the
79104
chosen platform.
80105

81-
.. note::
106+
Patch PCK files
107+
---------------
108+
109+
Generating Patch PCK files
110+
~~~~~~~~~~~~~~~~~~~~~~~~~~
111+
112+
To create a PCK file that only contains resources not present in the original
113+
release of a project, you would create a patch PCK file. This could be used for
114+
patches, mods, or expansions. For this to work you'll first need to have a PCK file
115+
for your project at the point of its initial release.
116+
117+
To generate a patch PCK file, within the export menu, and with your desired preset
118+
selected, click on the :Button:`Patching` tab. At the bottom is the :ui:`Base Packs`
119+
section. Click on the :Button:`Add Pack` button, then navigate to the PCK file you
120+
exported that contains everything in your project for its initial release.
121+
122+
Now, when you go to export a PCK file of your project again, if you have the
123+
:Button:`Export as Patch` button selected, only resources that have changed
124+
will be exported in the PCK file.
125+
126+
You can also add any patches you export to your base packs for future use. For
127+
example, adding ``patch.pck`` will ensure that ``patch2.pck`` will not include any
128+
resources from that first patch.
129+
130+
Delta encoding
131+
~~~~~~~~~~~~~~
132+
133+
Patch PCK files can be made smaller through the use of delta encoding. This makes it
134+
so that only the parts of a file that have been changed are updated. This does have a
135+
drawback of longer load times for the resources that are updated, and each patch for
136+
a resource cumulatively increases its load time.
137+
138+
There are two settings for delta encoding in addition to the filters:
82139

83-
If one wishes to support mods for their game, they will need their users to
84-
create similarly exported files. Assuming the original game expects a
85-
certain structure for the PCK's resources and/or a certain interface for
86-
its scripts, then either...
87-
88-
1. The developer must publicize documentation of these expected structures/
89-
interfaces, expect modders to install Godot Engine, and then also expect
90-
those modders to conform to the documentation's defined API when building
91-
mod content for the game (so that it will work). Users would then use
92-
Godot's built in exporting tools to create a PCK file, as detailed
93-
above.
94-
2. The developer uses Godot to build a GUI tool for adding their exact API
95-
content to a project. This Godot tool must either run on a tools-enabled
96-
build of the engine or have access to one (distributed alongside or
97-
perhaps in the original game's files). The tool can then use the Godot
98-
executable to export a PCK file from the command line with
99-
:ref:`OS.execute() <class_OS_method_execute>`. The game itself shouldn't
100-
use a tool-build of the engine (for security), so it's best to keep
101-
the modding tool and game separate.
140+
- **Delta Encoding Compression Level:** Controls how much compression is applied to
141+
the files. We do not recommend any more than the default of 19. Beyond that more
142+
memory is needed for export and import for significantly fewer gains. Any positive
143+
values will have the same decompression speed, however export will take
144+
longer the higher the number is. Negative values enable fast mode, which
145+
means larger files, but the decompression speed is higher.
146+
147+
- **Delta Encoding Minimum Size Reduction:** Controls how much size has to be saved
148+
at minimum for compression to be used on an individual file. For example, at a
149+
level of 10%, if the file size can only be reduced by 5%, then the file won't use
150+
delta encoding.
151+
152+
The default compression level, 19, is the highest recommended level.
153+
154+
For the smallest patch size possible we recommend turning off compression for any
155+
resources you want to patch. Even if your base PCK files were compressed that
156+
shouldn't cause an issue.
157+
158+
There are several places compression can be disabled for different resources:
159+
160+
- Import settings related to compression on individually imported resources, such as
161+
translation or 3D model files
162+
- :ui:`Compress Binary Resources` in the editor settings
163+
- :ui:`GDScript Export Mode` in the :button:`Scripts` tab of an export preset
164+
165+
.. Note::
166+
167+
After disabling :ui:`Compress Binary Resources` you must delete the contents of
168+
your projects ``.godot/imported/`` folder, then closing and open the project
169+
again to re-generate it.
170+
171+
It's important to note that when you export a delta encoded patch on top of previous
172+
patches, the packs you list under :ui:`Base Packs` in the :Button:`Patching` tab
173+
must be the exact same files that are loaded by the game at runtime, in the exact
174+
order they are loaded in. Re-exporting previous versions may end up being slightly
175+
different, due to non-determinism in Godot's export process, which can cause the
176+
patching to fail. This only applies to delta encoded patches, regular ones don't
177+
have this issue.
102178

103179
Opening PCK or ZIP files at runtime
104180
-----------------------------------
@@ -153,7 +229,7 @@ The PCK or ZIP file contains a ``mod_scene.tscn`` test scene in its root.
153229
``Assembly.LoadFile("mod.dll")``
154230

155231
Troubleshooting
156-
^^^^^^^^^^^^^^^
232+
~~~~~~~~~~~~~~~
157233

158234
If you are loading a resource pack and are not noticing any changes, it may be
159235
due to the pack being loaded too late. This is particularly the case with menu
@@ -167,11 +243,25 @@ call :ref:`ProjectSettings.load_resource_pack() <class_ProjectSettings_method_lo
167243
in the autoload script's ``_init()`` function, rather than ``_enter_tree()``
168244
or ``_ready()``.
169245

170-
Summary
171-
-------
172-
173-
This tutorial explains how to add mods, patches, or DLC to a game.
174-
The most important thing is to identify how one plans to distribute future
175-
content for their game and develop a workflow that is customized for that
176-
purpose. Godot should make that process smooth regardless of which route a
177-
developer pursues.
246+
Modding considerations
247+
----------------------
248+
249+
If one wishes to support mods for their game, they will need their users to
250+
create similarly exported files. Assuming the original game expects a
251+
certain structure for the PCK's resources, and/or a certain interface for
252+
its scripts, then one of two things has to be done.
253+
254+
1. The developer must document these expected structures/
255+
interfaces, expect modders to install Godot Engine, and then also expect
256+
those modders to conform to the documentation's defined API when building
257+
mod content for the game (so that it will work). Users would then use
258+
Godot's built in exporting tools to create a PCK file, as detailed
259+
above.
260+
2. The developer uses Godot to build a GUI tool for adding their exact API
261+
content to a project. This Godot tool must either run on a tools-enabled
262+
build of the engine or have access to one (distributed alongside or
263+
perhaps in the original game's files). The tool can then use the Godot
264+
executable to export a PCK file from the command line with
265+
:ref:`OS.execute() <class_OS_method_execute>`. The game itself shouldn't
266+
use a tool-build of the engine (for security), so it's best to keep
267+
the modding tool and game separate.

0 commit comments

Comments
 (0)