class_name ModLoaderMod extends Object ## ## This Class provides helper functions to build mods. ## ## @tutorial(Script Extensions): https://wiki.godotmodding.com/#/guides/modding/script_extensions ## @tutorial(Script Hooks): https://wiki.godotmodding.com/#/guides/modding/script_hooks ## @tutorial(Mod Structure): https://wiki.godotmodding.com/#/guides/modding/mod_structure ## @tutorial(Mod Files): https://wiki.godotmodding.com/#/guides/modding/mod_files const LOG_NAME := "ModLoader:Mod" ## Installs a script extension that extends a vanilla script.[br] ## [br] ## [b]Parameters:[/b][br] ## - [param child_script_path] ([String]): The path to the mod's extender script.[br] ## [br] ## [b]Returns:[/b][br] ## - No return value[br] ## [br] ## This is the preferred way of modifying a vanilla [Script][br] ## Since Godot 4, extensions can cause issues with scripts that use [code]class_name[/code] ## and should be avoided if present.[br] ## See [method add_hook] for those cases.[br] ## [br] ## The [param child_script_path] should point to your mod's extender script.[br] ## Example: [code]"MOD/extensions/singletons/utils.gd"[/code][br] ## Inside the extender script, include [code]extends {target}[/code] where [code]{target}[/code] is the vanilla path.[br] ## Example: [code]extends "res://singletons/utils.gd"[/code].[br] ## ===[br] ## [b]Note:[/b][br] ## Your extender script doesn't have to follow the same directory path as the vanilla file, ## but it's good practice to do so.[br] ## ===[br] ## [br] static func install_script_extension(child_script_path: String) -> void: var mod_id: String = _ModLoaderPath.get_mod_dir(child_script_path) var mod_data: ModData = get_mod_data(mod_id) if not ModLoaderStore.saved_extension_paths.has(mod_data.manifest.get_mod_id()): ModLoaderStore.saved_extension_paths[mod_data.manifest.get_mod_id()] = [] ModLoaderStore.saved_extension_paths[mod_data.manifest.get_mod_id()].append(child_script_path) # If this is called during initialization, add it with the other # extensions to be installed taking inheritance chain into account if ModLoaderStore.is_initializing: ModLoaderStore.script_extensions.push_back(child_script_path) # If not, apply the extension directly else: _ModLoaderScriptExtension.apply_extension(child_script_path) ## Adds all methods from a file as hooks. [br] ## [br] ## [b]Parameters:[/b][br] ## - [param vanilla_script_path] ([String]): The path to the script which will be hooked.[br] ## - [param hook_script_path] ([String]): The path to the script containing hooks.[br] ## [br] ## [b]Returns:[/b][br] ## - No return value[br] ## [br] ## The file needs to extend [Object].[br] ## The methods in the file need to have the exact same name as the vanilla method ## they intend to hook, all mismatches will be ignored. [br] ## See: [method add_hook] ## [br] ## [b]Examples:[/b][br] ## [codeblock] ## ModLoaderMod.install_script_hooks( ## "res://tools/utilities.gd", ## extensions_dir_path.path_join("tools/utilities-hook.gd") ## ) ## [/codeblock] static func install_script_hooks(vanilla_script_path: String, hook_script_path: String) -> void: var hook_script := load(hook_script_path) as GDScript var hook_script_instance := hook_script.new() # Every script that inherits RefCounted will be cleaned up by the engine as # soon as there are no more references to it. If the reference is gone # the method can't be called and everything returns null. # Only Object won't be removed, so we can use it here. if hook_script_instance is RefCounted: ModLoaderLog.fatal( "Scripts holding mod hooks should always extend Object (%s)" % hook_script_path, LOG_NAME ) var vanilla_script := load(vanilla_script_path) as GDScript var vanilla_methods := vanilla_script.get_script_method_list().map( func(method: Dictionary) -> String: return method.name ) var methods := hook_script.get_script_method_list() for hook in methods: if hook.name in vanilla_methods: ModLoaderMod.add_hook(Callable(hook_script_instance, hook.name), vanilla_script_path, hook.name) continue ModLoaderLog.debug( 'Skipped adding hook "%s" (not found in vanilla script %s)' % [hook.name, vanilla_script_path], LOG_NAME ) if not OS.has_feature("editor"): continue vanilla_methods.sort_custom(( func(a_name: String, b_name: String, target_name: String) -> bool: return a_name.similarity(target_name) > b_name.similarity(target_name) ).bind(hook.name)) var closest_vanilla: String = vanilla_methods.front() if closest_vanilla.similarity(hook.name) > 0.8: ModLoaderLog.hint( 'Did you mean "%s" instead of "%s"?' % [closest_vanilla, hook.name], LOG_NAME ) ## Adds a hook, a custom mod function, to a vanilla method.[br] ## [br] ## [b]Parameters:[/b][br] ## - [param mod_callable] ([Callable]): The function that will executed when ## the vanilla method is executed. When writing a mod callable, make sure ## that it [i]always[/i] receives a [ModLoaderHookChain] object as first argument, ## which is used to continue down the hook chain (see: [method ModLoaderHookChain.execute_next]) ## and allows manipulating parameters before and return values after the ## vanilla method is called. [br] ## - [param script_path] ([String]): Path to the vanilla script that holds the method.[br] ## - [param method_name] ([String]): The method the hook will be applied to.[br] ## [br] ## [b]Returns:[/b][br][br] ## - No return value[br] ## [br] ## Opposed to script extensions, hooks can be applied to scripts that use ## [code]class_name[/code] without issues.[br] ## If possible, prefer [method install_script_extension].[br] ## [br] ## [b]Examples:[/b][br] ## [br] ## Given the following vanilla script [code]main.gd[/code] ## [codeblock] ## class_name MainGame ## extends Node2D ## ## var version := "vanilla 1.0.0" ## ## ## func _ready(): ## $CanvasLayer/Control/Label.text = "Version: %s" % version ## print(Utilities.format_date(15, 11, 2024)) ## [/codeblock] ## ## It can be hooked in [code]mod_main.gd[/code] like this ## [codeblock] ## func _init() -> void: ## ModLoaderMod.add_hook(change_version, "res://main.gd", "_ready") ## ModLoaderMod.add_hook(time_travel, "res://tools/utilities.gd", "format_date") ## # Multiple hooks can be added to a single method. ## ModLoaderMod.add_hook(add_season, "res://tools/utilities.gd", "format_date") ## ## ## # The script we are hooking is attached to a node, which we can get from reference_object ## # then we can change any variables it has ## func change_version(chain: ModLoaderHookChain) -> void: ## # Using a typecast here (with "as") can help with autocomplete and avoiding errors ## var main_node := chain.reference_object as MainGame ## main_node.version = "Modloader Hooked!" ## # _ready, which we are hooking, does not have any arguments ## chain.execute_next() ## ## ## # Parameters can be manipulated easily by changing what is passed into .execute_next() ## # The vanilla method (Utilities.format_date) takes 3 arguments, our hook method takes ## # the ModLoaderHookChain followed by the same 3 ## func time_travel(chain: ModLoaderHookChain, day: int, month: int, year: int) -> String: ## print("time travel!") ## year -= 100 ## # Just the vanilla arguments are passed along in the same order, wrapped into an Array ## var val = chain.execute_next([day, month, year]) ## return val ## ## ## # The return value can be manipulated by calling the next hook (or vanilla) first ## # then changing it and returning the new value. ## func add_season(chain: ModLoaderHookChain, day: int, month: int, year: int) -> String: ## var output = chain.execute_next([day, month, year]) ## match month: ## 12, 1, 2: ## output += ", Winter" ## 3, 4, 5: ## output += ", Spring" ## 6, 7, 8: ## output += ", Summer" ## 9, 10, 11: ## output += ", Autumn" ## return output ## [/codeblock] ## static func add_hook(mod_callable: Callable, script_path: String, method_name: String) -> void: _ModLoaderHooks.add_hook(mod_callable, script_path, method_name) ## Registers an array of classes to the global scope since Godot only does that in the editor.[br] ## [br] ## [b]Parameters:[/b][br] ## - [param new_global_classes] ([Array]): An array of class definitions to be registered.[br] ## [br] ## [b]Returns:[/b][br] ## - No return value[br] ## [br] ## Format: [code]{ "base": "ParentClass", "class": "ClassName", "language": "GDScript", "path": "res://path/class_name.gd" }[/code][br] ## [br] ## ===[br] ## [b]Tip:[/b][color=tip][/color][br] ## You can find these easily in the project.godot file under `_global_script_classes`[br] ## (but you should only include classes belonging to your mod)[br] ## ===[br] static func register_global_classes_from_array(new_global_classes: Array) -> void: ModLoaderUtils.register_global_classes_from_array(new_global_classes) var _savecustom_error: int = ProjectSettings.save_custom(_ModLoaderPath.get_override_path()) ## Adds a translation file.[br] ## [br] ## [b]Parameters:[/b][br] ## - [param resource_path] ([String]): The path to the translation resource file.[br] ## [b]Returns:[/b][br] ## - No return value[br] ## [br] ## ===[br] ## [b]Note:[/b][br] ## The [code].translation[/code] file should have been created by the Godot editor already, usually when importing a CSV file. ## The translation file should named [code]name.langcode.translation[/code] -> [code]mytranslation.en.translation[/code].[br] ## ===[br] static func add_translation(resource_path: String) -> void: if not _ModLoaderFile.file_exists(resource_path): ModLoaderLog.fatal("Tried to load a position resource from a file that doesn't exist. The invalid path was: %s" % [resource_path], LOG_NAME) return var translation_object: Translation = load(resource_path) if translation_object: TranslationServer.add_translation(translation_object) ModLoaderLog.info("Added Translation from Resource -> %s" % resource_path, LOG_NAME) else: ModLoaderLog.fatal("Failed to load translation at path: %s" % [resource_path], LOG_NAME) ## Marks the given scene for to be refreshed. It will be refreshed at the correct point in time later.[br] ## [br] ## [b]Parameters:[/b][br] ## - [param scene_path] ([String]): The path to the scene file to be refreshed. ## [br] ## [b]Returns:[/b][br] ## - No return value[br] ## [br] ## ===[br] ## [b]Note:[/b][color=abstract "Version"][/color][br] ## This function requires Godot 4.3 or higher.[br] ## ===[br] ## [br] ## 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. ## [br] static func refresh_scene(scene_path: String) -> void: if scene_path in ModLoaderStore.scenes_to_refresh: return ModLoaderStore.scenes_to_refresh.push_back(scene_path) ModLoaderLog.debug("Added \"%s\" to be refreshed." % scene_path, LOG_NAME) ## Extends a specific scene by providing a callable function to modify it. ## [br] ## [b]Parameters:[/b][br] ## - [param scene_vanilla_path] ([String]): The path to the vanilla scene file.[br] ## - [param edit_callable] ([Callable]): The callable function to modify the scene.[br] ## [br] ## [b]Returns:[/b][br] ## - No return value[br] ## [br] ## The callable receives an instance of the "vanilla_scene" as the first parameter.[br] static func extend_scene(scene_vanilla_path: String, edit_callable: Callable) -> void: if not ModLoaderStore.scenes_to_modify.has(scene_vanilla_path): ModLoaderStore.scenes_to_modify[scene_vanilla_path] = [] ModLoaderStore.scenes_to_modify[scene_vanilla_path].push_back(edit_callable) ## Gets the [ModData] from the provided namespace.[br] ## [br] ## [b]Parameters:[/b][br] ## - [param mod_id] ([String]): The ID of the mod.[br] ## [br] ## [b]Returns:[/b][br] ## - [ModData]: The [ModData] associated with the provided [code]mod_id[/code], or null if the [code]mod_id[/code] is invalid.[br] static func get_mod_data(mod_id: String) -> ModData: if not ModLoaderStore.mod_data.has(mod_id): ModLoaderLog.error("%s is an invalid mod_id" % mod_id, LOG_NAME) return null return ModLoaderStore.mod_data[mod_id] ## Gets the [ModData] of all loaded Mods as [Dictionary].[br] ## [br] ## [b]Returns:[/b][br] ## - [Dictionary]: A dictionary containing the [ModData] of all loaded mods.[br] static func get_mod_data_all() -> Dictionary: return ModLoaderStore.mod_data ## Returns the path to the directory where unpacked mods are stored.[br] ## [br] ## [b]Returns:[/b][br] ## - [String]: The path to the unpacked mods directory.[br] static func get_unpacked_dir() -> String: return _ModLoaderPath.get_unpacked_mods_dir_path() ## Returns true if the mod with the given [code]mod_id[/code] was successfully loaded.[br] ## [br] ## [b]Parameters:[/b][br] ## - [param mod_id] ([String]): The ID of the mod.[br] ## [br] ## [b]Returns:[/b][br] ## - [bool]: true if the mod is loaded, false otherwise.[br] static func is_mod_loaded(mod_id: String) -> bool: if ModLoaderStore.is_initializing: ModLoaderLog.warning( "The ModLoader is not fully initialized. " + "Calling \"is_mod_loaded()\" in \"_init()\" may result in an unexpected return value as mods are still loading.", LOG_NAME ) # If the mod is not present in the mod_data dictionary or the mod is flagged as not loadable. if not ModLoaderStore.mod_data.has(mod_id) or not ModLoaderStore.mod_data[mod_id].is_loadable: return false return true ## Returns true if the mod with the given mod_id was successfully loaded and is currently active. ## [br] ## Parameters: ## - [param mod_id] ([String]): The ID of the mod. ## [br] ## Returns: ## - [bool]: true if the mod is loaded and active, false otherwise. static func is_mod_active(mod_id: String) -> bool: return is_mod_loaded(mod_id) and ModLoaderStore.mod_data[mod_id].is_active