Breaking Changes

This page lists any breaking changes that occur with ModLoader releases.

v6.0.0

Deprecation Messages

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.

See the Deprecated section below for the full list of changes. If you try to use an old method, you'll get an error in the editor until it's fixed. The error notice will tell you exactly what needs to change.

New Classes

There are several new classes in the api directory, which is where all the publicly accessible methods are. The main classes you'll use are:

• ModLoaderMod - Everything related to mod setup, such as install_script_extension().
• ModLoaderLog - All logging methods.

These replace using ModLoader.* and ModLaoderUtils.* (see Deprecated below).

New ModLoaderStore

Some mods directly accessed variables and constants on ModLoader, for example mod_data or UNPACKED_DIR. This has been moved to the new ModLoaderStore. We have introduced new methods in ModLoaderMod to access these variables. We recommend not accessing any of the variables in ModLoaderStore directly to prevent your mods from breaking in the future.

New Config System

• 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.
• It's important to note that 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.

Others

• Fixed a bug in the mod_id validation where it was possible to create a mod_id with fewer than 7 characters.
• Changed the mod config directory from res:// to user://.

Deprecated

Here's a list of everything that was deprecated. You can use a search & replace to update the old methods in your mod.

Setup

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()

Logging

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

v5.0.1

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 and incompatibilities are now validated

v4.0.0

• 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

Renamed Methods

Old	New
ModLoader.mod_log	ModLoaderUtils.log_info
ModLoader.dev_log	ModLoaderUtils.log_debug

v3.1.0

• 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 and REQUIRED_MANIFEST_KEYS_EXTRA in mod_manifest.gd

Renamed Methods

Old	New
installScriptExtension	install_script_extension
addTranslationFromResource	add_translation_from_resource
appendNodeInScene	append_node_in_scene
saveScene	save_scene

v3.0.0

• 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