API Methods

Use these when creating your mods.

Overview

Method	Description
install_script_extension	Extend a vanilla script
add_translation_from_resource	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
get_mod_config	Get data from a mod's config JSON file, or defaults from its manifest.json

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_from_resource

add_translation_from_resource(resource_path)

func add_translation_from_resource(
	# 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).

Note: This function is exclusive to ModLoader, and departs from Delta-V's two functions addTranslationsFromCSV and addTranslationsFromJSON, which aren't available in ModLoader.

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_from_resource.

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.

get_mod_config

var all_settings = get_mod_config(mod_id)
var key_settings = get_mod_config(mod_id, key)

func get_mod_config(
	# Full ID for the mod (eg. "AuthorName-ModName")
	mod_id:String = "",

	# (Optional) Get the data for a specific key
	key:String = ""
)->Dictionary:

Get data from a mod's config JSON file. Does not return the data directly.

Returns a dictionary with three keys: data, error, and error_msg. These are explained below.

See Config JSON for info on setting up defaults in your mod's manifest.json file, and applying per-user overrides.

Example

# Note the use of .data here
var do_thing = ModLoader.get_mod_config("AuthorName-ModName", "my_setting").data

Data

Data (data) is either the full config, or data from a specific key if one was specified.

If no user config JSON exists, data uses the defaults set in the mod's manifest.json (see Config JSON below). Returns an empty dictionary ({}) if either a) the mod's manifest.json has no defaults, or b) the specified key doesn't exist.

Error

Error (error) is 0 if there were no errors, or > 0 if the setting could not be retrieved:

#	Description	Data
0	No errors	As requested
1	Invalid mod_id	{}
2	No custom JSON exists	Defaults from manifest.json
3	Invalid key. Custom JSON does not exist	{}
4	Invalid key. Custom JSON does exist	{}

Error Msg

Text representation of the error that occurred, intended to make debugging easier.

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.

Next: Logging