Skip to content

Breaking Changes

KANAjetzt edited this page Jun 28, 2023 · 16 revisions

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.

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.

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.

Public Classes (API)

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 as install_script_extension().
  • ModLoaderLog - All logging methods.

Internal Classes

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.

Configs

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

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 every method and variable that is deprecated in v6. 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

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 and incompatibilities 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

Renamed Methods

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 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
  • 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