API Methods

🚨 This documentation is outdated. Please go here: ModLoader-API

---

ModLoaderMod

Description

ModLoaderMod provides all the API methods for creating mods.

Methods

Method	Description
install_script_extension	Extend a vanilla script
add_translation	Import a translation file (eg mod_text.en.translation)
append_node_in_scene	Create and add a node to a instanced scene
save_scene	Save the scene as a PackedScene, overwriting Godot's cache if needed

Method Descriptions

install_script_extension

install_script_extension(child_script_path)

func install_script_extension(
	# res:// path to the extending script
	child_script_path:String
)

Add a script that extends a vanilla script. This allows you to overwrite funcs, extend them, and add your own. See Script Inheritance below for more info on usage.

child_script_path is the path to your mod's extender script path, eg MOD/extensions/singletons/utils.gd.

Inside that extender script, it should include extends "{target}", where {target} is the vanilla path, eg: extends "res://singletons/utils.gd".

Your extender scripts don't have to follow the same directory path as the vanilla file, but it's good practice to do so.

One approach to organising your extender scripts is to put them in a dedicated folder named "extensions", eg:

yourmod.zip
├───.import
└───mods-unpacked
    └───Author-ModName
        ├───mod_main.gd
        ├───manifest.json
        └───extensions
            └───Any files that extend vanilla code can go here, eg:
            ├───main.gd
            └───singletons
                ├───item_service.gd
                └───debug_service.gd

add_translation

add_translation(resource_path)

func add_translation(
	# res:// path to the .translation file.
	resource_path: String
)

Add a translation file, eg "mytranslation.en.translation".

To create a *.translation file, add a CSV to your project's filesystem. The *.translation file be automatically generated in the same directory as your CSV.The translation file should have been created in Godot already (when you add a CSV to the filesystem, such a file will be created for you).

In your CSV, strings with commas (,) must be escaped by wrapping them in double quotes ("). If you don't do this, then your string won't load, and it will stop any strings below it from loading.

If all of your translatable strings have stopped working, then you have made an error in the path you provided to add_translation.

CSV Example

keys,en
MODNAME_EXAMPLE,This is an example. Use "MODNAME_EXAMPLE" where a translatable string is accepted and this text will be shown instead
MODNAME_COMMA_NOTE,"If your string contains a comma like this, you need to wrap the string in double quotes"

append_node_in_scene

append_node_in_scene(modified_scene, node_name, node_parent, instance_path, is_visible)

func appendNodeInScene(
	# an instanced scene of a PackedScene you want to replace
	modified_scene:Scene,

	# name of the new node
	node_name:String = "",

	# path to the parent node in the PackedScene
	node_parent = null,

	# path used to instanciate the node
	instance_path:String = "",

	# node visibility state
	is_visible:bool = true
)

Create and add a node to a instanced scene.

---

save_scene

save_scene(modified_scene, scene_path)

func saveScene(
	# an instanced scene of a PackedScene you want to replace
	modified_scene:Scene,

	# path to the PackedScene
	scene_path:String
)

Save the scene as a PackedScene, overwriting Godot's cache if needed.

Additional Info

Note: This info comes from the docs for the Delta-V mod loader.

Script inheritance

In order to allow modifying game functions without copying the contents of the functions or entire scripts in mod code, this system makes use of inheritance for hooking. We exploit the fact that all Godot scripts are also classes and may extend other scripts in the same way how a class may extend another class; this allows mods to include script extensions, which extend some standard game script and selectively override some methods.

For example, this simple script extension changes the path that save files are loaded from in the game Brotato.

The location of this example script extension would be here:

res://mods-unpacked/Author-ModName/extensions/singletons/progress_data.gd

# Our base script is the original game script.
extends "res://singletons/progress_data.gd"

# This overrides the method with the same name, changing the value of its argument:
func load_game_file(path:String = SAVE_PATH)->void:
	var modded_path = path + "--modded.json"

	# Calling the base method will call the original game method:
	.load_game_file(modded_path)

	# Note that if the vanilla script returned something, we would do this instead:
	#return .load_game_file(modded_path)

To install it, call modLoader.install_script_extension from your mod's mod_main.gd, in _init:

extends Node

func _init(modLoader = ModLoader):
	modLoader.install_script_extension('res://mods-unpacked/Author-ModName/extensions/singletons/progress_data.gd')

Inheritance chaining

To allow multiple mods to customize the same base script, installScriptExtension takes care to enable inheritance chaining. In practice, this is transparent to mods, and things should "just work".

If a script given to installScriptExtension extends from a game script which is already extended, then it will be extended from the last child script. For example, if we have two mods with a extends "res://main.gd" script, then the first mod's script will extend from the game's main, but after this "res://main.gd" will point at the extended script, so the second mod's script will extend from the first mod's script instead.