feat: ✨ options for game version validation

addons/mod_loader/mod_loader_store.gd

@@ -123,11 +123,10 @@ func _init():
 
 
 # Update ModLoader's options, via the custom options resource
-func _update_ml_options_from_options_resource() -> void:
-	# Path to the options resource
-	# See: res://addons/mod_loader/resources/options_current.gd
-	var ml_options_path := "res://addons/mod_loader/options/options.tres"
-
+#
+# Parameters:
+# - ml_options_path: Path to the options resource. See: res://addons/mod_loader/resources/options_current.gd
+func _update_ml_options_from_options_resource(ml_options_path := "res://addons/mod_loader/options/options.tres") -> void:
 	# Get user options for ModLoader
 	if not _ModLoaderFile.file_exists(ml_options_path) and not ResourceLoader.exists(ml_options_path):
 		ModLoaderLog.fatal(str("A critical file is missing: ", ml_options_path), LOG_NAME)
@@ -177,8 +176,8 @@ func _update_ml_options_from_options_resource() -> void:
 		# Update from the options in the resource
 		ml_options = override_options
 
-		if not ml_options.customize_script_path.is_empty():
-			ml_options.customize_script_instance = load(ml_options.customize_script_path).new(ml_options)
+	if not ml_options.customize_script_path.is_empty():
+		ml_options.customize_script_instance = load(ml_options.customize_script_path).new(ml_options)
 
 
 func _exit_tree() -> void:

addons/mod_loader/resources/options_profile.gd

@@ -2,6 +2,8 @@ class_name ModLoaderOptionsProfile
 extends Resource
 ##
 ## Class to define and store Mod Loader Options.
+##
+## @tutorial(Example Customization Script): https://example.com
 
 
 ## Settings for game version validation.
@@ -17,36 +19,12 @@ enum VERSION_VALIDATION {
 	## Use [member customize_script_path] to specify a script that customizes the Mod Loader options.
 	## In this script, you must set [member custom_game_version_validation_callable]
 	## to a custom validation [Callable].
-	##
-	## Example:
-	## [codeblock]
-	## extends RefCounted
-	##
-	## func _init(ml_options: ModLoaderOptionsProfile) -> void:
-	##    # Assign a custom validation function.
-	##    # Use `OS.has_feature(feature_tag)` to apply different validations for different platforms.
-	##    ml_options.custom_game_version_validation_callable = custom_is_game_version_compatible
-	##
-	## func custom_is_game_version_compatible(manifest: ModManifest) -> bool:
-	##    print("! ☞ﾟヮﾟ)☞ CUSTOM VALIDATION HERE ☜ﾟヮﾟ☜) !")
-	##
-	##    var mod_id := manifest.get_mod_id()
-	##
-	##    for version in manifest.compatible_game_version:
-	##        if not version == "pizza":
-	##            manifest.validation_messages_warning.push_back(
-	##                "The mod \"%s\" may not be compatible with the current game version.
-	##                Enable at your own risk. (current game version: %s, mod compatible with game versions: %s)" %
-	##                [mod_id, MyGlobalVars.MyGameVersion, manifest.compatible_game_version]
-	##            )
-	##            return false
-	##
-	##    return true
-	## [/codeblock]
-	##
+	## [br]
+	## ===[br]
+	## [b]Note:[color=note "Easier Mod Loader Updates"][/color][/b][br]
 	## Using a customization script allows you to keep your custom code outside the addon directory,
-	## making it easier to update the mod loader without affecting your modifications.
-	##
+	## making it easier to update the mod loader without affecting your modifications. [br]
+	## ===[br]
 	CUSTOM,
 }
 

test/Unit/test_options.gd

@@ -0,0 +1,47 @@
+extends GutTest
+
+
+func load_manifest_test_mod_1() -> ModManifest:
+	var mod_path := "res://mods-unpacked/test-mod1/"
+	var manifest_data: Dictionary = _ModLoaderFile.load_manifest_file(mod_path)
+
+	return ModManifest.new(manifest_data, mod_path)
+
+
+func test_customize_script() -> void:
+	ModLoaderStore._update_ml_options_from_options_resource("res://test_options/customize_script/options_custom_validation.tres")
+	var manifest := load_manifest_test_mod_1()
+
+	assert_eq(
+		"".join(manifest.validation_messages_warning),
+		"! ☞ﾟヮﾟ)☞ CUSTOM VALIDATION HERE ☜ﾟヮﾟ☜) !"
+	)
+
+
+func test_customize_script_no_callable() -> void:
+	# Clear saved error logs before testing to prevent false positives.
+	ModLoaderLog.logged_messages.by_type.error.clear()
+
+	ModLoaderStore._update_ml_options_from_options_resource("res://test_options/customize_script_no_callable_set/options_custom_validation_no_callable_set.tres")
+	var manifest := load_manifest_test_mod_1()
+
+	var logs := ModLoaderLog.get_by_type_as_string("error")
+
+	assert_string_contains("".join(logs), "No custom game version validation callable detected. Please provide a valid validation callable.")
+
+
+func test_game_verion_validation_disabled() ->  void:
+	ModLoaderStore._update_ml_options_from_options_resource("res://test_options/game_version_validation_disabled/options_game_version_validation_disabled.tres")
+	var manifest := load_manifest_test_mod_1()
+
+	assert_true(manifest.validation_messages_error.size() == 0)
+
+
+func test_game_verion_validation_default() ->  void:
+	ModLoaderStore._update_ml_options_from_options_resource("res://test_options/game_version_validation_default/options_game_version_validation_default.tres")
+	var manifest := load_manifest_test_mod_1()
+
+	assert_eq(
+		"".join(manifest.validation_messages_error).replace("\r", "").replace("\n", "").replace("\t", ""),
+		"The mod \"test-mod1\" is incompatible with the current game version.(current game version: 1000.0.0, mod compatible with game versions: [\"0.0.1\"])"
+	)

test/test_options/customize_script/custom_validation.tres

@@ -0,0 +1,26 @@
+[gd_resource type="Resource" script_class="ModLoaderOptionsProfile" load_steps=2 format=3 uid="uid://dky5648t3gmp2"]
+
+[ext_resource type="Script" path="res://addons/mod_loader/resources/options_profile.gd" id="1_3rpjy"]
+
+[resource]
+script = ExtResource("1_3rpjy")
+enable_mods = true
+locked_mods = Array[String]([])
+disabled_mods = Array[String]([])
+allow_modloader_autoloads_anywhere = false
+customize_script_path = "res://test_options/customize_script/customize_script.gd"
+log_level = 3
+ignore_deprecated_errors = false
+ignored_mod_names_in_log = Array[String]([])
+steam_id = 0
+semantic_version = "0.0.0"
+load_from_steam_workshop = false
+load_from_local = true
+override_path_to_mods = ""
+override_path_to_configs = ""
+override_path_to_workshop = ""
+override_path_to_hook_pack = ""
+override_hook_pack_name = ""
+restart_notification_scene_path = "res://addons/mod_loader/restart_notification.tscn"
+disable_restart = false
+game_version_validation = 2

addons/mod_loader/options/example_customize_script.gd → test/test_options/customize_script/customize_script.gd

@@ -3,6 +3,7 @@ extends RefCounted
 # This is an example script for the ModLoaderOptionsProfile `customize_script_path`.
 # Ideally, place this script outside the `mod_loader` directory to simplify the update process.
 
+
 # This script is loaded after `mod_loader_store.ml_options` has been initialized.
 # It receives `ml_options` as an argument, allowing you to apply settings
 # that cannot be configured through the editor UI.
@@ -17,30 +18,9 @@ func _init(ml_options: ModLoaderOptionsProfile) -> void:
 		# Set `custom_game_version_validation_callable` to use a custom validation function.
 		ml_options.custom_game_version_validation_callable = custom_is_game_version_compatible
 
+
 # Custom validation function
 # See `ModManifest._is_game_version_compatible()` for the default validation logic.
 func custom_is_game_version_compatible(manifest: ModManifest) -> bool:
-	print("! ☞ﾟヮﾟ)☞ CUSTOM VALIDATION HERE ☜ﾟヮﾟ☜) !")
-
-	var mod_id := manifest.get_mod_id()
-
-	for version in manifest.compatible_game_version:
-		if not version == "pizza":
-			# Push a warning message displayed after manifest validation is complete.
-			manifest.validation_messages_warning.push_back(
-				"The mod \"%s\" may not be compatible with the current game version.
-				Enable at your own risk. (Current game version: %s, mod compatible with game versions: %s)" %
-				[mod_id, "MyGlobalVars.MyGameVersion", manifest.compatible_game_version]
-			)
-			return true
-
-		if not version == "pineapple":
-			# Push an error message displayed after manifest validation is complete.
-			manifest.validation_messages_error.push_back(
-				"The mod \"%s\" is incompatible with the current game version.
-				(Current game version: %s, mod compatible with game versions: %s)" %
-				[mod_id, "MyGlobalVars.MyGameVersion", manifest.compatible_game_version]
-			)
-			return false
-
+	manifest.validation_messages_warning.push_back("! ☞ﾟヮﾟ)☞ CUSTOM VALIDATION HERE ☜ﾟヮﾟ☜) !")
 	return true

test/test_options/customize_script/options_custom_validation.tres

@@ -0,0 +1,9 @@
+[gd_resource type="Resource" script_class="ModLoaderCurrentOptions" load_steps=3 format=3 uid="uid://d08kklljebrnh"]
+
+[ext_resource type="Resource" uid="uid://dky5648t3gmp2" path="res://test_options/customize_script/custom_validation.tres" id="1_s4sec"]
+[ext_resource type="Script" path="res://addons/mod_loader/resources/options_current.gd" id="2_1rct1"]
+
+[resource]
+script = ExtResource("2_1rct1")
+current_options = ExtResource("1_s4sec")
+feature_override_options = {}

test/test_options/customize_script_no_callable_set/custom_validation_no_callable_set.tres

@@ -0,0 +1,26 @@
+[gd_resource type="Resource" script_class="ModLoaderOptionsProfile" load_steps=2 format=3 uid="uid://1gab2n8lgi60"]
+
+[ext_resource type="Script" path="res://addons/mod_loader/resources/options_profile.gd" id="1_d2tfu"]
+
+[resource]
+script = ExtResource("1_d2tfu")
+enable_mods = true
+locked_mods = Array[String]([])
+disabled_mods = Array[String]([])
+allow_modloader_autoloads_anywhere = false
+customize_script_path = "res://test_options/customize_script_no_callable_set/customize_script_no_callable_set.gd"
+log_level = 3
+ignore_deprecated_errors = false
+ignored_mod_names_in_log = Array[String]([])
+steam_id = 0
+semantic_version = "0.0.0"
+load_from_steam_workshop = false
+load_from_local = true
+override_path_to_mods = ""
+override_path_to_configs = ""
+override_path_to_workshop = ""
+override_path_to_hook_pack = ""
+override_hook_pack_name = ""
+restart_notification_scene_path = "res://addons/mod_loader/restart_notification.tscn"
+disable_restart = false
+game_version_validation = 2

test/test_options/customize_script_no_callable_set/customize_script_no_callable_set.gd

@@ -0,0 +1,27 @@
+extends RefCounted
+
+# This is an example script for the ModLoaderOptionsProfile `customize_script_path`.
+# Ideally, place this script outside the `mod_loader` directory to simplify the update process.
+
+
+# This script is loaded after `mod_loader_store.ml_options` has been initialized.
+# It receives `ml_options` as an argument, allowing you to apply settings
+# that cannot be configured through the editor UI.
+func _init(ml_options: ModLoaderOptionsProfile) -> void:
+	# Use OS.has_feature() to apply changes only for specific platforms,
+	# or create multiple customization scripts and set their paths accordingly in the option profiles.
+	if OS.has_feature("Steam"):
+		pass
+	elif OS.has_feature("Epic"):
+		pass
+	else:
+		pass
+		# Set `custom_game_version_validation_callable` to use a custom validation function.
+		#ml_options.custom_game_version_validation_callable = custom_is_game_version_compatible
+
+
+# Custom validation function
+# See `ModManifest._is_game_version_compatible()` for the default validation logic.
+func custom_is_game_version_compatible(manifest: ModManifest) -> bool:
+	manifest.validation_messages_warning.push_back("! ☞ﾟヮﾟ)☞ CUSTOM VALIDATION HERE ☜ﾟヮﾟ☜) !")
+	return true

test/test_options/customize_script_no_callable_set/options_custom_validation_no_callable_set.tres

@@ -0,0 +1,9 @@
+[gd_resource type="Resource" script_class="ModLoaderCurrentOptions" load_steps=3 format=3 uid="uid://c25j7kt7y8ora"]
+
+[ext_resource type="Resource" uid="uid://1gab2n8lgi60" path="res://test_options/customize_script_no_callable_set/custom_validation_no_callable_set.tres" id="1_xrqi6"]
+[ext_resource type="Script" path="res://addons/mod_loader/resources/options_current.gd" id="2_4o6bw"]
+
+[resource]
+script = ExtResource("2_4o6bw")
+current_options = ExtResource("1_xrqi6")
+feature_override_options = {}

test/test_options/game_version_validation_default/game_version_validation_default.tres

@@ -0,0 +1,26 @@
+[gd_resource type="Resource" script_class="ModLoaderOptionsProfile" load_steps=2 format=3 uid="uid://bnc6gslxpnx3y"]
+
+[ext_resource type="Script" path="res://addons/mod_loader/resources/options_profile.gd" id="1_kdajl"]
+
+[resource]
+script = ExtResource("1_kdajl")
+enable_mods = true
+locked_mods = Array[String]([])
+disabled_mods = Array[String]([])
+allow_modloader_autoloads_anywhere = false
+customize_script_path = ""
+log_level = 3
+ignore_deprecated_errors = false
+ignored_mod_names_in_log = Array[String]([])
+steam_id = 0
+semantic_version = "1000.0.0"
+load_from_steam_workshop = false
+load_from_local = true
+override_path_to_mods = ""
+override_path_to_configs = ""
+override_path_to_workshop = ""
+override_path_to_hook_pack = ""
+override_hook_pack_name = ""
+restart_notification_scene_path = "res://addons/mod_loader/restart_notification.tscn"
+disable_restart = false
+game_version_validation = 0

test/test_options/game_version_validation_default/options_game_version_validation_default.tres

@@ -0,0 +1,9 @@
+[gd_resource type="Resource" script_class="ModLoaderCurrentOptions" load_steps=3 format=3 uid="uid://emmn66l0e1n0"]
+
+[ext_resource type="Resource" uid="uid://bnc6gslxpnx3y" path="res://test_options/game_version_validation_default/game_version_validation_default.tres" id="1_ey6sk"]
+[ext_resource type="Script" path="res://addons/mod_loader/resources/options_current.gd" id="2_0ultl"]
+
+[resource]
+script = ExtResource("2_0ultl")
+current_options = ExtResource("1_ey6sk")
+feature_override_options = {}

test/test_options/game_version_validation_disabled/game_version_validation_disabled.tres

@@ -0,0 +1,26 @@
+[gd_resource type="Resource" script_class="ModLoaderOptionsProfile" load_steps=2 format=3 uid="uid://d2ktmje1gd5vb"]
+
+[ext_resource type="Script" path="res://addons/mod_loader/resources/options_profile.gd" id="1_vd02r"]
+
+[resource]
+script = ExtResource("1_vd02r")
+enable_mods = true
+locked_mods = Array[String]([])
+disabled_mods = Array[String]([])
+allow_modloader_autoloads_anywhere = false
+customize_script_path = ""
+log_level = 3
+ignore_deprecated_errors = false
+ignored_mod_names_in_log = Array[String]([])
+steam_id = 0
+semantic_version = "1000.0.0"
+load_from_steam_workshop = false
+load_from_local = true
+override_path_to_mods = ""
+override_path_to_configs = ""
+override_path_to_workshop = ""
+override_path_to_hook_pack = ""
+override_hook_pack_name = ""
+restart_notification_scene_path = "res://addons/mod_loader/restart_notification.tscn"
+disable_restart = false
+game_version_validation = 1

test/test_options/game_version_validation_disabled/options_game_version_validation_disabled.tres

@@ -0,0 +1,9 @@
+[gd_resource type="Resource" script_class="ModLoaderCurrentOptions" load_steps=3 format=3 uid="uid://dsegljus5l2qm"]
+
+[ext_resource type="Resource" uid="uid://d2ktmje1gd5vb" path="res://test_options/game_version_validation_disabled/game_version_validation_disabled.tres" id="1_18vx8"]
+[ext_resource type="Script" path="res://addons/mod_loader/resources/options_current.gd" id="2_5hgrx"]
+
+[resource]
+script = ExtResource("2_5hgrx")
+current_options = ExtResource("1_18vx8")
+feature_override_options = {}