Merge pull request #1895 from willnationsdev/mod-tut

Add .pck creation tutorial

getting_started/workflow/export/exporting_pcks.rst

@@ -0,0 +1,129 @@
+.. _doc_exporting_pcks:
+
+Exporting packs, patches, and mods
+==================================
+
+Use cases
+---------
+
+Oftentimes one would like to add functionality to one's game after it has been
+deployed.
+
+Examples of this include...
+
+- Downloadable Content: the ability to add features and content to one's game.
+- Patches: the ability to fix a bug that is present in a shipped product.
+- Mods: grant other people the ability to create content for one's game.
+
+These tools help developers to extend their development beyond the initial
+release.
+
+Overview of \*.pck files
+------------------------
+
+Godot enables this via a feature called **resource packs**
+(\*.pck files).
+
+**Advantages:**
+
+- incremental updates/patches
+- offer DLCs
+- offer mod support
+- no source code disclosure needed for mods
+- more modular project structure
+- users don’t have to replace the entire game
+
+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 file to the users.
+
+\*.pck files usually contain, but are not limited to:
+
+- scripts
+- scenes
+- shaders
+- models
+- textures
+- sound effects
+- music
+- any other asset suitable for import into the game
+
+The \*.pck files can even be an entirely different Godot project, which the
+original game loads in at runtime.
+
+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.
+
+.. image:: img/export_pck.png
+
+Another method would be to `export from the command line
+<https://docs.godotengine.org/en/latest/getting_started/editor/command_line_tutorial.html#exporting>`_.
+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.
+
+.. note::
+   If one wishes to support mods for their game, they will need their users to
+   create similarly exported files. Assuming the original game expects a
+   certain structure for the \*.pck's resources and/or a certain interface for
+   its scripts, then either...
+
+   1. The developer must publicize documentation of these expected structures/
+      interfaces, expect modders to install Godot Engine, and then also expect
+      those modders to conform to the documentation's defined API when building
+      mod content for the game (so that it will work). Users would then use
+      Godot's built in exporting tools to create a \*.pck file, as detailed
+      above.
+   2. The developer uses Godot to build a GUI tool for adding their exact API
+      content to a project. This Godot tool must either run on a tools-enabled
+      build of the engine or have access to one (distributed alongside or
+      perhaps in the original game's files). The tool can then use the Godot
+      executable to export a \*.pck file from the command line with
+      :ref:`OS.execute <class_OS_execute>`. It makes the most sense for the
+      game to not use a tool-build though (for security) and for the modding
+      tools to *do* use a tool-enabled engine build.
+
+Opening \*.pck files at runtime
+-------------------------------
+
+To import a \*.pck file, one uses a one-liner. Keep in mind, there is no
+error or exception if the import fails. Instead, one might have to create some
+validation code as a layer on top. 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.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    func _your_function():
+        ProjectSettings.load_resource_pack("res://mod.pck")
+        # Now one can use the assets as if they had them in the project from the start
+        var imported_scene = load("res://mod_scene.tscn")
+
+ .. code-tab:: csharp
+
+    private void YourFunction()
+    {
+        ProjectSettings.LoadResourcePack("res://mod.pck");
+        // Now one can use the assets as if they had them in the project from the start
+        var importedScene = ResourceLoader.Load("res://mod_scene.tscn") as PackedScene;
+    }
+
+.. warning::
+  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 (solved easily with a tool isolating 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.
+
+Summary
+-------
+
+This tutorial should illustrate how easy adding mods, patches or DLC to a game
+is. The most important thing is to identify how one plans to distribute future
+content for their game and develop a workflow that is customized for that
+purpose. Godot should make that process smooth regardless of which route a
+developer pursues.

getting_started/workflow/export/index.rst

@@ -7,6 +7,7 @@ Export
 
 
    exporting_projects
+   exporting_pcks
    feature_tags
    exporting_for_pc
    exporting_for_ios