feat: ✨ support async hooks for methods using await (#470)

* feat: ✨ support async hooks for methods using await

* privatization

---------

Co-authored-by: Qubus0 <steen.rickmer@gmx.de>

Author: KANAjetzt

addons/mod_loader/api/hook_chain.gd

@@ -31,20 +31,49 @@ func _init(reference_object: Object, callbacks: Array) -> void:
 ##
 ## [br][b]Returns:[/b] [Variant][br][br]
 func execute_next(args := []) -> Variant:
-	_callback_index -= 1
+	var callback := _get_next_callback()
+	if not callback:
+		return
+
+	# Vanilla needs to be called without the hook chain being passed
+	if _is_callback_vanilla():
+		return callback.callv(args)
+
+	return callback.callv([self] + args)
 
-	if _callback_index < 0:
+
+## Same as [method execute_next], but asynchronous - it can be used if a method uses [code]await[/code]. [br]
+## This hook needs to be used if the vanilla method uses [code]await[/code] somewhere. [br]
+## Make sure to call this method [i][color=orange]once[/color][/i] somewhere in the [param mod_callable] you pass to [method ModLoaderMod.add_hook]. [br]
+##
+## [br][b]Parameters:[/b][br]
+## - [param args] ([Array]): An array of all arguments passed into the vanilla function. [br]
+##
+## [br][b]Returns:[/b] [Variant][br][br]
+func execute_next_async(args := []) -> Variant:
+	var callback := _get_next_callback()
+	if not callback:
+		return
+
+	# Vanilla needs to be called without the hook chain being passed
+	if _is_callback_vanilla():
+		return await callback.callv(args)
+
+	return await callback.callv([self] + args)
+
+
+func _get_next_callback() -> Variant:
+	_callback_index -= 1
+	if not _callback_index >= 0:
 		ModLoaderLog.fatal(
 			"The hook chain index should never be negative. " +
 			"A mod hook has called execute_next twice or ModLoaderHookChain was modified in an unsupported way.",
 			LOG_NAME
 		)
 		return
 
-	var callback :=  _callbacks[_callback_index]
+	return _callbacks[_callback_index]
 
-	# Vanilla call is always at index 0 and needs to be called without the hook chain being passed
-	if _callback_index == 0:
-		return callback.callv(args)
 
-	return callback.callv([self] + args)
+func _is_callback_vanilla() -> bool:
+	return _callback_index == 0

addons/mod_loader/internal/hooks.gd

@@ -11,8 +11,7 @@ const LOG_NAME := "ModLoader:Hooks"
 ## To add hooks from a mod use [method ModLoaderMod.add_hook].
 static func add_hook(mod_callable: Callable, script_path: String, method_name: String) -> void:
 	ModLoaderStore.any_mod_hooked = true
-	var hash = get_hook_hash(script_path, method_name)
-
+	var hash := get_hook_hash(script_path, method_name)
 	if not ModLoaderStore.modding_hooks.has(hash):
 		ModLoaderStore.modding_hooks[hash] = []
 	ModLoaderStore.modding_hooks[hash].push_back(mod_callable)
@@ -29,13 +28,19 @@ static func call_hooks(vanilla_method: Callable, args: Array, hook_hash: int) ->
 	if hooks.is_empty():
 		return vanilla_method.callv(args)
 
-	# Create a hook chain which will call down until the vanilla method is reached
-	var callbacks = [vanilla_method]
-	callbacks.append_array(hooks)
-	var chain := ModLoaderHookChain.new(vanilla_method.get_object(), callbacks)
+	var chain := ModLoaderHookChain.new(vanilla_method.get_object(), [vanilla_method] + hooks)
 	return chain.execute_next(args)
 
 
+static func call_hooks_async(vanilla_method: Callable, args: Array, hook_hash: int) -> Variant:
+	var hooks: Array = ModLoaderStore.modding_hooks.get(hook_hash, [])
+	if hooks.is_empty():
+		return await vanilla_method.callv(args)
+
+	var chain := ModLoaderHookChain.new(vanilla_method.get_object(), [vanilla_method] + hooks)
+	return await chain.execute_next_async(args)
+
+
 static func get_hook_hash(path: String, method: String) -> int:
 	return hash(path + method)