-
Notifications
You must be signed in to change notification settings - Fork 30
Breaking Changes
This page lists any breaking changes that occur with ModLoader releases.
Mods are now always unpacked and loaded into ModLoaderStore.mod_data
. This change can potentially break mod lists that rely on having only loaded mods in mod_data
. Consequently, these mod lists may display mods that are currently not loaded. To address this issue, authors of mod lists need to adapt their code to check the new is_active
flag.
As outlined in the v6 release notes, ModLoader v6 has refactored its entire codebase. This meant we needed to deprecate certain methods and classes, but we've also added new deprecation methods to ensure these changes won't break active mods.
If you try to use an old method, you'll get an error in the editor until it's fixed. The error message will tell you exactly what needs to change.
See the Deprecated section below for the full list of changes.
There are several new classes in the api
directory, which is where all the publicly accessible methods are. These replace using ModLoader.*
and ModLoaderUtils.*
(see Deprecated below). The main classes you'll use are:
-
ModLoaderMod
- Everything related to mod setup, such asinstall_script_extension()
. -
ModLoaderLog
- All logging methods.
Some mods directly accessed variables and constants on ModLoader
, for example mod_data
or UNPACKED_DIR
. Data such as this is now considered internal, and should not be accessed directly (this includes any method/variable from the ModLoader
or ModLoaderStore
classes). Instead, we have introduced new methods in ModLoaderMod
to access these variables, such as ModLoaderMod.get_unpacked_dir()
and ModLoaderMod.get_mod_data_all()
.
Other internal classes and methods have been prefixed with an underscore (_
). Please do not use these. They are not considered public, so they might change at any point in the future. If there's some internal data you'd like to access, please raise an issue if you can, and we'll look into provided more API access to the data you want.
- The value for
compatible_mod_loader_version
no longer accepts a string. It needs to be passed an array instead. - The
config_defaults
field in manifest.json has been removed. It is no longer used for specifying default configuration values. - A new field called
config_schema
has been introduced in manifest.json. This field allows you to specify a JSONSchema for your Mod Configuration. JSONSchema provides a way to define the structure and validation rules for your configuration. - Warning: There is currently no fallback mechanism for migrating old configurations to the new system. You will need to update your mod to adapt to the new configuration structure.
- Fixed a bug in the
mod_id
validation where it was possible to create amod_id
with fewer than 7 characters. - Changed the mod config directory from
res://
touser://
.
Here's a list of every method and variable that is deprecated in v6. You can use a search & replace to update the old methods in your mod.
Old (Search) | New (Replace) |
---|---|
ModLoader.add_translation_from_resource |
ModLoaderMod.add_translation |
ModLoader.append_node_in_scene |
ModLoaderMod.append_node_in_scene |
ModLoader.get_mod_config |
ModLoaderConfig.get_config |
ModLoader.install_script_extension |
ModLoaderMod.install_script_extension |
ModLoader.mod_data |
ModLoaderMod.get_mod_data_all() |
ModLoader.register_global_classes_from_array |
ModLoaderMod.register_global_classes_from_array |
ModLoader.save_scene |
ModLoaderMod.save_scene |
ModLoader.UNPACKED_DIR |
ModLoaderMod.get_unpacked_dir() |
Note: Running a search & replace from ModLoaderUtils.log_
to ModLoaderLog.
will fix all of these at once.
Old (Search) | New (Replace) |
---|---|
ModLoaderUtils.log_debug_json_print |
ModLoaderLog.debug_json_print |
ModLoaderUtils.log_debug |
ModLoaderLog.debug |
ModLoaderUtils.log_error |
ModLoaderLog.error |
ModLoaderUtils.log_fatal |
ModLoaderLog.fatal |
ModLoaderUtils.log_info |
ModLoaderLog.info |
ModLoaderUtils.log_success |
ModLoaderLog.success |
ModLoaderUtils.log_warning |
ModLoaderLog.warning |
New validation may make existing mods invalid:
- #71 - Disallow leading zeros and overly long versions
-
#91 - Mod IDs listed in a mod manifest's
dependencies
andincompatibilities
are now validated
- ModLoader has been moved to the
res://addons/
directory.- The new location is autoloaded in the same way the old one was, with the same file (mod_loader.gd).
- Nothing else needs to change in your autoloads. There are other new classes, but they'll be loaded automatically.
- Logging in mods is now handled via the ModLoaderUtils class, which provides a host of new logging options. See Renamed Methods below.
-
ModLoader.mod_log
->ModLoaderUtils.log_info
-
ModLoader.dev_log
->ModLoaderUtils.log_debug
-
Old | New |
---|---|
ModLoader.mod_log |
ModLoaderUtils.log_info |
ModLoader.dev_log |
ModLoaderUtils.log_debug |
- All funcs have been converted to snake_case (see table below, and PR #32 for more info)
- meta.json is renamed to manifest.json, and its required keys have changed
- See the example manifest.json for the current structure.
- See also:
REQUIRED_MANIFEST_KEYS_ROOT
andREQUIRED_MANIFEST_KEYS_EXTRA
in mod_manifest.gd
Old | New |
---|---|
installScriptExtension |
install_script_extension |
addTranslationFromResource |
add_translation_from_resource |
appendNodeInScene |
append_node_in_scene |
saveScene |
save_scene |
- Two files have been renamed:
-
ModMain.gd
->mod_main.gd
-
_meta.json
->manifest.json
-
- The structure of the manifest JSON has changed.
- See README.md for an example.
- This file was previously named
_meta.json
Home ~ Setup ~ Mod Structure ~ Mod Files ~ API Methods ~ Logging