-
Notifications
You must be signed in to change notification settings - Fork 31
API Methods
🚨 This documentation is outdated. Please go here: ModLoader-API
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(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(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(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(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.
Note: This info comes from the docs for the Delta-V mod loader.
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')
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.
Home ~ Setup ~ Mod Structure ~ Mod Files ~ API Methods ~ Logging