Add support for custom extensions: tests + docs + CI update

Author: trobugno

.github/workflows/pandora-ci.yml

@@ -39,7 +39,7 @@ jobs:
       fail-fast: false
       max-parallel: 10
       matrix:
-        godot-version: ["4.3", "4.4"]
+        godot-version: ["4.4", "4.5.1"]
 
     name: "🤖 CI on Godot ${{ matrix.godot-version }}"
     steps:

docs/_sidebar.md

@@ -5,25 +5,26 @@
   - [🔹 Editor Interface](/concepts/editor.md "🧩 Editor Interface")
   - [🔹 Categories and Entities](/concepts/entities.md "🧩 Categories and Entities")
   - [🔹 Properties](/concepts/properties/ "🧩 Properties")
-    - [🔹 String](/concepts/properties/string.md "🧩 String")
-    - [🔹 Integer](/concepts/properties/integer.md "🧩 Integer")
-    - [🔹 Float](/concepts/properties/float.md "🧩 Float")
-    - [🔹 Bool](/concepts/properties/bool.md "🧩 Bool")
-    - [🔹 Vector2i](/concepts/properties/vector2i.md "🧩 Vector2i")
-    - [🔹 Vector2](/concepts/properties/vector2.md "🧩 Vector2")
-    - [🔹 Vector3i](/concepts/properties/vector3i.md "🧩 Vector3i")
-    - [🔹 Vector3](/concepts/properties/vector3.md "🧩 Vector3")
-    - [🔹 Color](/concepts/properties/color.md "🧩 Color")
-    - [🔹 Reference](/concepts/properties/reference.md "🧩 Reference")
-    - [🔹 Resource](/concepts/properties/resource.md "🧩 Resource")
-    - [🔹 Array](/concepts/properties/array.md "🧩 Array")
+	- [🔹 String](/concepts/properties/string.md "🧩 String")
+	- [🔹 Integer](/concepts/properties/integer.md "🧩 Integer")
+	- [🔹 Float](/concepts/properties/float.md "🧩 Float")
+	- [🔹 Bool](/concepts/properties/bool.md "🧩 Bool")
+	- [🔹 Vector2i](/concepts/properties/vector2i.md "🧩 Vector2i")
+	- [🔹 Vector2](/concepts/properties/vector2.md "🧩 Vector2")
+	- [🔹 Vector3i](/concepts/properties/vector3i.md "🧩 Vector3i")
+	- [🔹 Vector3](/concepts/properties/vector3.md "🧩 Vector3")
+	- [🔹 Color](/concepts/properties/color.md "🧩 Color")
+	- [🔹 Reference](/concepts/properties/reference.md "🧩 Reference")
+	- [🔹 Resource](/concepts/properties/resource.md "🧩 Resource")
+	- [🔹 Array](/concepts/properties/array.md "🧩 Array")
 - [🔌 GDScript API](/api/)
   - [🔹 Accessing Data](/api/access.md "🔌 Accessing Data")
   - [🔹 Entity Instancing](/api/instancing.md "🔌 Entity Instancing")
   - [🔹 Saving and Loading](/api/saveload.md "🔌 Saving and Loading")
 - [🧠 Mastery](/mastery/)
   - [🔹 Generating ID Constants](/mastery/id-constants.md "🧠 Generating ID Constants")
   - [🔹 Custom Scripts](/mastery/custom-scripts.md "🧠 Custom Scripts")
+  - [🔹 Custom Extensions](/mastery/custom_extensions.md "🧠 Custom Extensions")
 - [🔥 Ignis: The Flame Master's Story](/ignis/)
   - [🔹 Crafting Fire Spells](/ignis/spells.md "🔥 Crafting Fire Spells")
   - [🔹 Designing the Quest](/ignis/quest.md "🔥 Designing the Quest")

docs/assets/project_settings_pandora_extensions.png

@@ -0,0 +1,40 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://bo47l766jex2a"
+path="res://.godot/imported/project_settings_pandora_extensions.png-06f78ae3e4eb3da1bbfe02745f33c5b2.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://docs/assets/project_settings_pandora_extensions.png"
+dest_files=["res://.godot/imported/project_settings_pandora_extensions.png-06f78ae3e4eb3da1bbfe02745f33c5b2.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

docs/assets/project_settings_pandora_extensions.png.import

@@ -0,0 +1,40 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://eti3nl7vgxa8"
+path="res://.godot/imported/test_property.png-1080ebd719ad5d4f9efab45fb62e8bce.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://docs/assets/test_property.png"
+dest_files=["res://.godot/imported/test_property.png-1080ebd719ad5d4f9efab45fb62e8bce.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

docs/assets/test_property.png

@@ -34,4 +34,4 @@ func get_item(id:String) -> Item:
 with which you could change the previous code to:
 ```gdscript
 var texture = ItemRepository.get_item(Items.PICKAXE).get_item_texture()
-```
+```

docs/assets/test_property.png.import

@@ -0,0 +1,23 @@
+# Custom Extensions
+
+Pandora allows you to extend its property system with your own custom property types.
+This can be useful when you want to define specific data structures for your game,
+such as recipes, drops, or status effects.
+
+## Registering a Custom Extension
+To register a new custom property, create a new folder within the **pandora/extensions** folder with the following structure:
+_pandora/extensions/new_custom_property_:
+- **icons**: This folder is <u>optional</u>, but it could be useful if you want to add icons. The name of this folder is not mandatory; it could also be called assets.
+- **model**: This is a required folder. The name must match this one. Inside it, you will create a .gd file that will represent the data model used within and outside of Pandora's ecosystem.
+    - **types**: Inside the model folder, the types folder must be created. Inside it, you will create a .gd file that <u>extends PandoraPropertyType</u>, which contains the settings, serialization, and deserialization of the new property.
+- **property_button**: This is a required folder where you will create a file called property_button.tscn, which will be a <u>PandoraPropertyButton</u> that can be used by the Pandora bar.
+- **ui_component**: Mandatory folder, here you will create the scene that will be displayed when you want to use the new custom property.
+
+Once your extension is registered, it will automatically appear in the Pandora property selector, allowing you to use it in your entities and access it at runtime like any other Pandora property.
+
+**NOTE**: If you want to add or change the extensions folder, just go to **Project/Project Settings/Pandora/Config** and set _Extensions_ array:
+![custom_extensions](../assets/pandora_settings_custom_extensions.png)
+
+## Example
+For a complete and working example of a custom property, take a look at **pandora/extensions/test_property**
+![test_property](../assets/test_property.png)

docs/mastery/custom-scripts.md

@@ -10,10 +10,11 @@ const __source = 'res://addons/pandora/settings/pandora_settings.gd'
 const TEST_DIR = "testdata"
 
 const IDType := PandoraSettings.IDType
+const EXTENSION_NAME := "test_property"
 
 const SETTING_ID_TYPE := PandoraSettings.SETTING_ID_TYPE
 const SETTING_PANDORA_DATA_PATH := PandoraSettings.SETTING_PANDORA_DATA_PATH
-
+const SETTINGS_PANDORA_EXTENSIONS_DIR := PandoraSettings.SETTINGS_PANDORA_EXTENSIONS_DIR
 
 func test_initialize() -> void:
 	ProjectSettings.clear(SETTING_ID_TYPE)
@@ -96,3 +97,12 @@ func test_set_data_path() -> void:
 
 	Pandora._clear()
 	Pandora.load_data()
+
+func test_compare_with_extensions_models() -> void:
+	ProjectSettings.clear(SETTINGS_PANDORA_EXTENSIONS_DIR)
+	PandoraSettings.init_setting(
+		SETTINGS_PANDORA_EXTENSIONS_DIR, ["res://pandora/extensions"],
+		TYPE_ARRAY, PROPERTY_HINT_DIR
+	)
+	var actual := PandoraSettings.compare_with_extensions_models(EXTENSION_NAME)
+	assert_bool(actual).is_equal(true)