CompatLib is a comprehensive compatibility management library for Vintage Story modding. It offers tools to detect mod dependencies, handle compatibility conflicts, and streamline integration between mods, ensuring a harmonious modding experience.
- ✅ Mod Detection: Verify the presence of specific mods and retrieve their versions.
- 🔄 Compatibility Management: Register, process, and manage compatibility handlers for mods.
- 📊 Conflict Tracking: Dynamically detect and log compatibility conflicts.
- 🔧 Server & Client Commands: In-game commands for debugging compatibility issues.
- 🔒 Thread Safety: Utilizes thread-safe operations to ensure data integrity in multithreaded environments.
- 🛠️ Dynamic Handler Control: Enable or disable specific handlers at runtime for flexible compatibility management.
- 🕒 Version Compatibility Checks: Ensure handlers are compatible with specific mod versions to prevent conflicts.
- 📣 User Feedback Mechanism: Inform users about active handlers and detected conflicts, enhancing transparency.
- 📄 JSON Export for Compatibility Logs: Export compatibility logs in a structured JSON format for easier debugging and analysis.
- 📈 Logging Granularity: Introduced different log levels (INFO, WARNING, ERROR) to categorize messages, allowing for more granular control over logging output.
- Download: Obtain the latest CompatLib release from the Releases page.
- Placement: Place the
.dllfile in your Vintage Story Mods directory. - Reference: Ensure your mod's
.csprojreferences CompatLib for compatibility handling.
Use ModChecker to verify if a mod is installed:
bool isLoaded = ModChecker.IsModLoaded(api, "targetmodid");Retrieve a mod’s version:
string version = ModChecker.GetModVersion(api, "targetmodid");To register a compatibility handler for a specific mod:
CompatibilityManager.RegisterHandler(
targetmodid: "targetmodid",
priority: 100,
handler: () => {
// Custom compatibility logic
api.Logger.Notification("Applying compatibility fix for targetmodid.");
},
description: "Handler for targetmodid",
mutuallyExclusive: false,
dependencies: new List<string> { "dependencyModId" },
compatibleVersion: "1.0.0"
);priority: Determines the execution order of handlers; higher values indicate higher priority.description: A brief description of the handler.mutuallyExclusive: Indicates if the handler should not run alongside others for the same mod.dependencies: A list of mod IDs that this handler depends on.compatibleVersion: Specifies the mod version this handler is compatible with.
CompatLib automatically processes registered handlers when mods are detected on the server. To manually process handlers:
CompatibilityManager.ProcessHandlers("targetmodid", api);To dynamically enable or disable a specific handler:
CompatibilityManager.SetHandlerEnabled("targetmodid", "Handler for targetmodid", isEnabled: false);.compatlog
- Displays conflict logs in the chat.
/compatlog
- Shows logs in the server console.
Demonstrate how to register a handler with a version range:
CompatibilityManager.RegisterHandler(
targetmodid: "targetmodid",
priority: 100,
handler: () => {
// Custom compatibility logic
api.Logger.Notification("Applying compatibility fix for targetmodid.");
},
description: "Handler for targetmodid",
mutuallyExclusive: false,
dependencies: new List<string> { "dependencyModId" },
compatibleVersionRange: "[1.0.0,2.0.0)" // Compatible with versions 1.0.0 (inclusive) to 2.0.0 (exclusive)
);To export the compatibility logs in JSON format:
string jsonLogs = AnalyticsManager.ExportLogsAsJson();
// You can then save jsonLogs to a file or process it as needed.Explain how to log messages with different severity levels:
// Log an informational message
AnalyticsManager.LogInfo("This is an informational message.");
// Log a warning message
AnalyticsManager.LogWarning("This is a warning message.");
// Log an error message
AnalyticsManager.LogError("This is an error message.");| Method | Description |
|---|---|
IsModLoaded(api, modid) |
Checks if a mod is installed. |
GetModVersion(api, modid) |
Retrieves the version of a mod. |
| Method | Description |
|---|---|
RegisterHandler(modid, priority, handler, description, mutuallyExclusive, dependencies, compatibleVersion) |
Registers a compatibility handler with detailed parameters. |
ProcessHandlers(modid, api) |
Executes the appropriate handlers for a mod. |
GetRegistrations() |
Returns all registered handlers. |
SetHandlerEnabled(modid, description, isEnabled) |
Enables or disables a specific handler at runtime. |
| Method | Description |
|---|---|
LogConflict(message) |
Logs compatibility conflicts. |
LogInfo(message) |
Logs an informational message. |
LogWarning(message) |
Logs a warning message. |
LogError(message) |
Logs an error message. |
ConflictCount |
Retrieves the number of logged conflicts. |
GetConflictLogs() |
Returns a thread-safe snapshot of conflict logs. |
ExportLogsAsJson() |
Exports the conflict logs as a JSON-formatted string. |
Contributions are welcome! To get started:
- Fork the repository.
- Create a feature branch (
git checkout -b feature-name). - Commit your changes (
git commit -m "Add feature"). - Push to the branch (
git push origin feature-name). - Open a Pull Request.
This project is licensed under the MIT License. See LICENSE for details.
Developed by Elocrypt (elo).