From 77d438cf696397afc29ed15a3601ead7e971617b Mon Sep 17 00:00:00 2001 From: HetCreep Date: Mon, 8 Jun 2026 19:48:55 +0700 Subject: [PATCH] Clarify BepInDependency version errors and docs (#1330) The chainloader collected both not-installed dependencies and installed-but-incompatible-version dependencies into one list and reported them all as "missing dependencies", which is confusing when the plugin is present but on a version outside the requested range. Separate the two cases and log distinct, actionable messages: one for dependencies that are not installed, and one for dependencies present with an incompatible version (showing the found version and the required range). Also expand the BepInDependency(string, string) xmldoc: the version is a SemVer range, link the range syntax, and warn about the BepInEx 5 -> 6 behaviour change (a bare version was a minimum, now it is exact). Fixes #779 --- BepInEx.Core/Bootstrap/BaseChainloader.cs | 38 +++++++++++++++++------ BepInEx.Core/Contract/Attributes.cs | 14 +++++++-- 2 files changed, 41 insertions(+), 11 deletions(-) diff --git a/BepInEx.Core/Bootstrap/BaseChainloader.cs b/BepInEx.Core/Bootstrap/BaseChainloader.cs index c6fe182..bec5b6b 100644 --- a/BepInEx.Core/Bootstrap/BaseChainloader.cs +++ b/BepInEx.Core/Bootstrap/BaseChainloader.cs @@ -344,6 +344,7 @@ public abstract class BaseChainloader { var dependsOnInvalidPlugin = false; var missingDependencies = new List(); + var incompatibleDependencies = new List>(); foreach (var dependency in plugin.Dependencies) { static bool IsHardDependency(BepInDependency dep) => @@ -359,15 +360,22 @@ public abstract class BaseChainloader pluginVersion = pluginInfo?.Metadata.Version; } - if (!dependencyExists || dependency.VersionRange != null && - !dependency.VersionRange.IsSatisfied(pluginVersion)) + // The dependency is not installed at all. + if (!dependencyExists) { - // If the dependency is hard, collect it into a list to show if (IsHardDependency(dependency)) missingDependencies.Add(dependency); continue; } + // The dependency is installed, but its version does not satisfy the requested range. + if (dependency.VersionRange != null && !dependency.VersionRange.IsSatisfied(pluginVersion)) + { + if (IsHardDependency(dependency)) + incompatibleDependencies.Add(new KeyValuePair(dependency, pluginVersion?.ToString())); + continue; + } + // If the dependency is a hard and is invalid (e.g. has missing dependencies), report that to the user if (invalidPlugins.Contains(dependency.DependencyGUID) && IsHardDependency(dependency)) { @@ -387,13 +395,25 @@ public abstract class BaseChainloader continue; } - if (missingDependencies.Count != 0) + if (missingDependencies.Count != 0 || incompatibleDependencies.Count != 0) { - var message = $@"Could not load [{plugin}] because it has missing dependencies: { - string.Join(", ", missingDependencies.Select(s => s.VersionRange == null ? s.DependencyGUID : $"{s.DependencyGUID} ({s.VersionRange})").ToArray()) - }"; - DependencyErrors.Add(message); - Logger.Log(LogLevel.Error, message); + if (missingDependencies.Count != 0) + { + var message = $@"Could not load [{plugin}] because it has missing dependencies: { + string.Join(", ", missingDependencies.Select(s => s.VersionRange == null ? s.DependencyGUID : $"{s.DependencyGUID} ({s.VersionRange})").ToArray()) + }. Install the listed plugin(s) and restart the game."; + DependencyErrors.Add(message); + Logger.Log(LogLevel.Error, message); + } + + if (incompatibleDependencies.Count != 0) + { + var message = $@"Could not load [{plugin}] because the following dependencies are installed with an incompatible version: { + string.Join(", ", incompatibleDependencies.Select(s => $"{s.Key.DependencyGUID} (found {s.Value}, requires {s.Key.VersionRange})").ToArray()) + }. Update the listed plugin(s) to a version that satisfies the requirement."; + DependencyErrors.Add(message); + Logger.Log(LogLevel.Error, message); + } invalidPlugins.Add(plugin.Metadata.GUID); continue; diff --git a/BepInEx.Core/Contract/Attributes.cs b/BepInEx.Core/Contract/Attributes.cs index 0de9e93..87ae233 100644 --- a/BepInEx.Core/Contract/Attributes.cs +++ b/BepInEx.Core/Contract/Attributes.cs @@ -120,8 +120,18 @@ public class BepInDependency : Attribute, ICacheable /// not load and an error will be logged instead. /// /// The GUID of the referenced plugin. - /// The version range of the referenced plugin. - /// When version is supplied the dependency is always treated as HardDependency + /// + /// The version requirement of the referenced plugin, parsed as a SemVer range + /// (see ). A plain version such as + /// 1.2.0 requires that exact version; use a range such as >=1.2.0, 1.2.*, + /// ~1.2.0 or ^1.2.0 to accept more than one version. + /// + /// + /// When a version is supplied the dependency is always treated as a hard dependency. + /// Plugins migrating from BepInEx 5 should note a behaviour change: a bare version was previously + /// treated as a minimum (>=), whereas in BepInEx 6 it is an exact match. Use + /// >=1.2.0 to keep the old behaviour. + /// public BepInDependency(string guid, string version) : this(guid) { VersionRange = Range.Parse(version);