From 5b39f781ae24cb4346679c500346ce4f0f186f51 Mon Sep 17 00:00:00 2001
From: Andrii Doroshenko <xrayez@gmail.com>
Date: Tue, 10 Mar 2020 12:12:56 +0200
Subject: [PATCH] Document modules ability to pre-register types (#3250)

`preregister_*_types()` is available to modules since
Vulkan branch has been merged.
---
 development/cpp/custom_modules_in_cpp.rst | 76 +++++++++++++++++++++++
 1 file changed, 76 insertions(+)

diff --git a/development/cpp/custom_modules_in_cpp.rst b/development/cpp/custom_modules_in_cpp.rst
index 6ea03e3ab..4aa1b825e 100644
--- a/development/cpp/custom_modules_in_cpp.rst
+++ b/development/cpp/custom_modules_in_cpp.rst
@@ -257,6 +257,82 @@ The output will be ``60``.
              template. See the :ref:`Compiling <toc-devel-compiling>` pages
              for more information.
 
+Customizing module types initialization
+---------------------------------------
+
+Modules can interact with other built-in engine classes during runtime and even
+affect the way core types are initialized. So far, we've been using
+``register_summator_types`` as a way to bring in module classes to be available
+within the engine.
+
+A crude order of the engine setup can be summarized as a list of the following
+type registration methods:
+
+.. code-block:: cpp
+
+    preregister_module_types();
+    preregister_server_types();
+    register_core_singletons();
+    register_server_types();
+    register_scene_types();
+    EditorNode::register_editor_types();
+    register_platform_apis();
+    register_module_types();
+    initialize_physics();
+    initialize_navigation_server();
+    register_server_singletons();
+    register_driver_types();
+    ScriptServer::init_languages();
+
+Our ``Summator`` class is initialized during the ``register_module_types()``
+call. Imagine that we need to satisfy some common module run-time dependency
+(like singletons), or allow us to override existing engine method callbacks
+before they can be assigned by the engine itself. In that case, we want to
+ensure that our module classes are registered *before* any other built-in type.
+
+This is where we can define an optional ``preregister_summator_types()``
+method which will be called before anything else during the
+``preregister_module_types()`` engine setup stage.
+
+We now need to add this method to ``register_types`` header and source files:
+
+.. code-block:: cpp
+
+    /* register_types.h */
+
+    #define MODULE_SUMMATOR_HAS_PREREGISTER
+    void preregister_summator_types();
+
+    void register_summator_types();
+    void unregister_summator_types();
+
+.. note:: Unlike other register methods, we have to explicitly define
+          ``MODULE_SUMMATOR_HAS_PREREGISTER`` to let the build system know what
+          relevant method calls to include at compile time. The module's name
+          has to be converted to uppercase as well.
+
+.. code-block:: cpp
+
+    /* register_types.cpp */
+
+    #include "register_types.h"
+
+    #include "core/class_db.h"
+    #include "summator.h"
+
+    void preregister_summator_types() {
+        // Called before any other core types are registered.
+        // Nothing to do here in this example.
+    }
+
+    void register_summator_types() {
+        ClassDB::register_class<Summator>();
+    }
+
+    void unregister_summator_types() {
+       // Nothing to do here in this example.
+    }
+
 Improving the build system for development
 ------------------------------------------