feat: ✨ Mod Hooks (GodotModding#408)

* feat: 🚧 first draft of the export plugin

The plan is to automate the creation of hooks for each function in all GDScripts.

* feat: 🚧 wip callable_stack

* refactor: 🚧 rename vanilla functions

Vanilla functions are renamed, and at the bottom of the script, mod loader hooks are generated. These hooks replace the vanilla functions and handle calls to the `callable_stack`.

* feat: 🚧 added return with types to hook

Currently, I'm stuck on this approach because the method list's return property does not contain any information if there is no return type defined for the method.

* refactor: 🚧 reworked callable_sack funcs

* refactor: 🚧 added return usage check

That seems to work for filtering out methods that have a return.

* refactor: 🚧 remove and add back class_name

Without removing the `class_name` before initializing the script on export, I get this parse error: `hides a global script class`. With these code changes, I get `Value of type [script_path] cannot be assigned to a variable of type [class_name]` if there is a self-assignment somewhere in the script.

* refactor: 🚧 No new script instance - load() the script 😶‍🌫️

Also added a check for static functions and currently working on recognizing inner classes.

* refactor: 🚧 added `get_return_type_string`

check the `type_hint` and add it if it's present.

* refactor: 🚧 added `is_top_level_func`

To check if the function has no space before `func` or `static`, used to ignore functions in inner classes. Later, we might want to figure out a way to include these.

* fix: 🚧 corrected return type in generated methods

Also removed extra comma in args list

* feat: 🚧 only add modloader text to modified scripts

until now all scripts received the "Mod Loader Hooks" header at the bottom
even when no changes where made.

* feat: 🚧 added optional @moddable requirement

* feat: 🚧 added `is_setter`

used to ignore setter funcs

* feat: 🚧 improved runtime performance by pre-hashing dict-lookup

Also refactored some of the function/field names to improved the modding experience

* feat: 🚧 fixed issues with inheritance by adding class hash

added getter method, made both static and moved getter/setter check to is_moddable check

* cleaner getters and setters

* feat: 🚧 added @not-moddable option to exclude methods

improved performance by exiting early when nothing is hooked

* refactor: ♻️ removed no longer used functions

and a first style and type pass

* refactor: 🚧 general code cleanup

* 🚧 refactor: move methods

* 🚧 refactor: extract methods

* 🚧 feat: mod hook packing prototype

* fix: 🚧 fix path to `mod_hook_preprocessor.gd`

* 🚧 fix: typos

* feat: 🚧 replace super calls

* refactor: ♻️ remove static from regex vars

* feat: 🚧 hook creation and loading (#3)

* feat: 🚧 hook creation and loading

* feat: ✨ hook creation and loading

---------

Co-authored-by: Luca Martinelli <lucxmangajet@gmail.com>
Co-authored-by: Qubus0 <steen.rickmer@gmx.de>

Author: 3 people

addons/mod_loader/_export_plugin/export_plugin.gd

@@ -0,0 +1,28 @@
+extends EditorExportPlugin
+
+const ModHookPreprocessorScript := preload("res://addons/mod_loader/internal/mod_hook_preprocessor.gd")
+static var ModHookPreprocessor
+
+
+func _get_name() -> String:
+	return "Godot Mod Loader Export Plugin"
+
+
+func _export_begin(features: PackedStringArray, is_debug: bool, path: String, flags: int) -> void:
+	ModHookPreprocessor = ModHookPreprocessorScript.new()
+	ModHookPreprocessor.process_begin()
+
+
+func _export_file(path: String, type: String, features: PackedStringArray) -> void:
+	if path.begins_with("res://addons") or path.begins_with("res://mods-unpacked"):
+		return
+
+	if type != "GDScript":
+		return
+
+	skip()
+	add_file(
+		path,
+		ModHookPreprocessor.process_script(path).to_utf8_buffer(),
+		false
+	)

addons/mod_loader/_export_plugin/plugin.cfg

@@ -0,0 +1,7 @@
+[plugin]
+
+name="A Mod Loader Export"
+description="Export plugin to generate the necessary callable stack."
+author="KANA"
+version="0.1"
+script="plugin.gd"

addons/mod_loader/_export_plugin/plugin.gd

@@ -0,0 +1,14 @@
+@tool
+extends EditorPlugin
+
+
+var _export_plugin: EditorExportPlugin
+
+
+func _enter_tree():
+	_export_plugin = preload("res://addons/mod_loader/_export_plugin/export_plugin.gd").new()
+	add_export_plugin(_export_plugin)
+
+
+func _exit_tree() -> void:
+	remove_export_plugin(_export_plugin)

addons/mod_loader/api/mod.gd

@@ -11,6 +11,32 @@ extends Object
 const LOG_NAME := "ModLoader:Mod"
 
 
+static func set_modding_hooks(new_callable_stack: Dictionary) -> void:
+	ModLoaderStore.modding_hooks = new_callable_stack
+
+
+static func add_hook(mod_callable: Callable, script_path: String, method_name: String, is_before := false) -> void:
+	ModLoaderStore.any_mod_hooked = true
+	var hash = get_hook_hash(script_path,method_name,is_before)
+	if not ModLoaderStore.modding_hooks.has(hash):
+		ModLoaderStore.modding_hooks[hash] = []
+	ModLoaderStore.modding_hooks[hash].push_back(mod_callable)
+	ModLoaderLog.debug("Added hook script: \"%s\" method: \"%s\" is_before: \"%s\"" % [script_path, method_name, is_before], LOG_NAME)
+	if not ModLoaderStore.hooked_script_paths.has(script_path):
+		ModLoaderStore.hooked_script_paths[script_path] = null
+
+
+static func call_hooks(self_object: Object, args: Array, hook_hash:int) -> void:
+	var hooks = ModLoaderStore.modding_hooks.get(hook_hash, null)
+	if hooks:
+		for mod_func in hooks:
+			mod_func.call(self_object, args)
+
+
+static func get_hook_hash(path:String, method:String, is_before:bool) -> int:
+	return hash(path + method + ("before" if is_before else "after"))
+
+
 ## Installs a script extension that extends a vanilla script.[br]
 ## The [code]child_script_path[/code] should point to your mod's extender script.[br]
 ## Example: [code]"MOD/extensions/singletons/utils.gd"[/code][br]

addons/mod_loader/internal/cache.gd

@@ -31,7 +31,7 @@ static func add_data(key: String, data: Dictionary) -> Dictionary:
 # Get data from a specific key
 static func get_data(key: String) -> Dictionary:
 	if not ModLoaderStore.cache.has(key):
-		ModLoaderLog.error("key: \"%s\" not found in \"ModLoaderStore.cache\"" % key, LOG_NAME)
+		ModLoaderLog.info("key: \"%s\" not found in \"ModLoaderStore.cache\"" % key, LOG_NAME)
 		return {}
 
 	return ModLoaderStore.cache[key]

addons/mod_loader/internal/file.gd

@@ -227,4 +227,3 @@ static func dir_exists(path: String) -> bool:
 # modders in understanding and troubleshooting issues.
 static func _code_note(_msg:String):
 	pass
-

addons/mod_loader/internal/mod_hook_packer.gd

@@ -0,0 +1,65 @@
+class_name _ModLoaderModHookPacker
+extends RefCounted
+
+
+# This class is used to generate mod hooks on demand and pack them into a zip file.
+# Currently all of the included functions are internal and should only be used by the mod loader itself.
+
+const LOG_NAME := "ModLoader:ModHookPacker"
+
+
+static func start() -> void:
+	var hook_pre_processor = _ModLoaderModHookPreProcessor.new()
+	hook_pre_processor.process_begin()
+
+	var mod_hook_pack_path := _ModLoaderPath.get_path_to_hook_pack()
+
+	# Create mod hook pack path if necessary
+	if not DirAccess.dir_exists_absolute(mod_hook_pack_path.get_base_dir()):
+		var error := DirAccess.make_dir_recursive_absolute(mod_hook_pack_path.get_base_dir())
+		if not error == OK:
+			ModLoaderLog.error("Error creating the mod hook directory at %s" % mod_hook_pack_path, LOG_NAME)
+			return
+		ModLoaderLog.debug("Created dir at: %s" % mod_hook_pack_path, LOG_NAME)
+
+	# Create mod hook zip
+	var zip_writer := ZIPPacker.new()
+	var error: Error
+
+	if not FileAccess.file_exists(mod_hook_pack_path):
+		# Clear cache if the hook pack does not exist
+		_ModLoaderCache.remove_data("hooks")
+		error = zip_writer.open(mod_hook_pack_path)
+	else:
+		# If there is a pack already append to it
+		error = zip_writer.open(mod_hook_pack_path, ZIPPacker.APPEND_ADDINZIP)
+	if not error == OK:
+		ModLoaderLog.error("Error(%s) writing to zip file at path: %s" % [error, mod_hook_pack_path], LOG_NAME)
+		return
+
+	var cache := _ModLoaderCache.get_data("hooks")
+	var script_paths_with_hook: Array = [] if cache.is_empty() else cache.script_paths
+	var new_hooks_created := false
+
+	# Get all scripts that need processing
+	ModLoaderLog.debug("Scripts requiring hooks: %s" % [ModLoaderStore.hooked_script_paths.keys()], LOG_NAME)
+	for path in ModLoaderStore.hooked_script_paths.keys():
+		if path in script_paths_with_hook:
+			continue
+
+		var processed_source_code := hook_pre_processor.process_script(path)
+
+		zip_writer.start_file(path.trim_prefix("res://"))
+		zip_writer.write_file(processed_source_code.to_utf8_buffer())
+		zip_writer.close_file()
+
+		ModLoaderLog.debug("Hooks created for script: %s" % path, LOG_NAME)
+		new_hooks_created = true
+		script_paths_with_hook.push_back(path)
+
+	if new_hooks_created:
+		_ModLoaderCache.update_data("hooks", {"script_paths": script_paths_with_hook})
+		_ModLoaderCache.save_to_file()
+		ModLoader.new_hooks_created.emit()
+
+	zip_writer.close()