feat: ✨ adds refresh_scene and extend_scene

[KANAjetzt]

Changes to ModLoaderMod

New Methods

static func refresh_scene(scene_path: String) -> void:
Refreshes a specific scene by marking it for refresh.

This function is useful if a script extension is not automatically applied. This situation can occur when a script is attached to a preloaded scene. If you encounter issues where your script extension is not working as expected, try to identify the scene to which it is attached and use this method to refresh it. This will reload already loaded scenes and apply the script extension.

🚨 refresh_scene will only work for Godot 4.3 and up. 🚨

static func extend_scene(scene_vanilla_path: String, edit_callable: Callable) -> void:
Extends a specific scene by providing a callable function to modify it. The callable receives an instance of the vanilla_scene as the first parameter and has to return the modified version.

Removed Methods

static func append_node_in_scene(modified_scene: Node, node_name: String = "", node_parent = null, instance_path: String = "", is_visible: bool = true) -> void:
Removed without replacement because it was always unintuitive to use. Instead of this method, the scene extension setup can be used to add a node to a scene.

static func save_scene(modified_scene: Node, scene_path: String) -> void:
save_scene has been moved to scene_extension.gd as an internal method used by handle_scene_extensions()

New Class - _ModLoaderSceneExtension

Similar to _ModLoaderScriptExtension, this class encompasses everything related to modifying PackedScenes, with the hope of continuous improvement.

Currently, preloaded scenes can't be modified using these methods because CACHE_MODE_REPLACE loads the scene from file and, with that, wipes any changes stored in the cached instance. For loaded scenes, this should work just fine.

💡 Preloaded scenes can be modified by adding the code to the script extension.

Changes to ModLoader

• Removed deprecation of append_node_in_scene and save_scene. I think we can remove the other deprecations in a subsequent PR.
• Added calls to _ModLoaderSceneExtension.refresh_scenes() and _ModLoaderSceneExtension.handle_scene_extensions() at the end of _load_mods()

Changes to ModLoaderStore

• Added var scenes_to_refresh := []
  Stores scene paths that need to be reloaded from file.
• Added var scenes_to_modify := {}
  Dictionary of callables to modify a specific scene.
  Example property: "scene_path": [Callable, Callable]

Example mod_main.gd

extends Node

const TEST_MOD0_DIR := "Test-Mod0"
const TEST_MOD0_LOG_NAME := "Test-Mod0:Main"

var mod_dir_path := ""
var extensions_dir_path := ""
var translations_dir_path := ""


func _init() -> void:
	mod_dir_path = ModLoaderMod.get_unpacked_dir().path_join(TEST_MOD0_DIR)
	# Add extensions
	install_script_extensions()
	# Edit Scenes
	edit_scenes()


func install_script_extensions() -> void:
	extensions_dir_path = mod_dir_path.path_join("extensions")
	ModLoaderMod.install_script_extension(extensions_dir_path.path_join("preload_scene.gd"))
	ModLoaderMod.install_script_extension(extensions_dir_path.path_join("main.gd"))


func edit_main_scene(scene_instance: Node) -> Node:
	var button: Button = scene_instance.get_node("CanvasLayer/Button")
	button.text = "MODDDED!!!!!"

	return scene_instance


func edit_scenes() -> void:
	ModLoaderMod.refresh_scene("res://preload_scene.tscn")
	ModLoaderMod.extend_scene("res://main.tscn", edit_main_scene)

Closes #377

[Qubus0]

promising! still need to test later.
do you think this is unit testable?

[KANAjetzt]

Should be testable, but first, we need to migrate or rebuild the testing for the 4.x branch 👀

[Qubus0]

new hope for scene modifications 🚀