CompatLib Documentation

Overview

CompatLib is designed to streamline mod compatibility by providing a structured approach to detect and manage interactions between various mods. It offers utilities to check for the presence of specific mods, retrieve mod versions, and register compatibility handlers that ensure seamless integration.

Getting Started

Installation

To integrate CompatLib into your modding project, follow these steps:

1. Download CompatLib: Get the latest release from the Releases page.

2. Add to Project: Include the CompatLib DLL in your mod's project references.

3. Namespace Inclusion: Add the CompatLib namespace in your code:

   using CompatLib;

Initialization

Initialize CompatLib within your mod's main class by extending ModSystem:

using Vintagestory.API.Common;

namespace YourModNamespace
{
    public class YourModSystem : ModSystem
    {
        public override void Start(ICoreAPI api)
        {
            base.Start(api);
            // Initialize CompatLib
            api.Logger.Notification("YourMod initialized with CompatLib support.");
        }
    }
}

Mod Detection and Version Checking

Before implementing compatibility features, it's crucial to verify if the target mod is loaded. CompatLib provides the ModChecker utility for this purpose.

Example: Verifying Mod Presence and Version

using Vintagestory.API.Common;

namespace YourModNamespace
{
    public class YourModSystem : ModSystem
    {
        public override void Start(ICoreAPI api)
        {
            base.Start(api);

            string targetModId = "targetmodid";

            if (ModChecker.IsModLoaded(api, targetModId))
            {
                string modVersion = ModChecker.GetModVersion(api, targetModId);
                api.Logger.Notification($"Mod '{targetModId}' is loaded. Version: {modVersion}");
            }
            else
            {
                api.Logger.Warning($"Mod '{targetModId}' is not loaded. Compatibility features will be disabled.");
            }
        }
    }
}

• IsModLoaded returns true if the mod is installed.
• GetModVersion retrieves the mod version, returning "unknown" if unavailable.

In this example, replace "targetmodid" with the Mod ID of the mod you want to check. The IsModLoaded method returns a boolean indicating the presence of the specified mod.

Registering Compatibility Handlers

CompatLib allows you to register handlers that manage interactions with other mods. These handlers ensure your mod functions correctly alongside others.

Example: Registering a Compatibility Handler

using Vintagestory.API.Common;

namespace YourModNamespace
{
    public class YourModSystem : ModSystem
    {
        public override void Start(ICoreAPI api)
        {
            base.Start(api);

            CompatibilityManager.RegisterHandler(
                targetModId: "targetmodid",
                priority: 100,
                handler: () =>
                {
                    // Compatibility logic for the target mod
                    api.Logger.Notification("Compatibility handler for 'targetmodid' executed.");
                },
                description: "Ensures compatibility with Target Mod",
                mutuallyExclusive: false,
                dependencies: new List<string> { "dependencyModId" },
                compatibleVersion: "1.0.0"
            );
        }
    }
}

• priority: Defines execution order (higher value = higher priority).
• mutuallyExclusive: Prevents multiple handlers for the same mod from running simultaneously.
• dependencies: Specifies required mods for this handler to activate.
• compatibleVersion: Ensures compatibility with a specific mod version.

In this example:

• targetModId: The Mod ID of the mod you're targeting.

• 100: The priority of the handler. Higher values indicate higher priority.

• The lambda function contains the compatibility logic to be executed if the target mod is present.

• The description provides context for the handler's purpose.

Processing Compatibility Handlers

After registering handlers, CompatLib processes them based on detected mods. This typically occurs in the StartServerSide method.

Example: Processing Handlers

using Vintagestory.API.Common;
using Vintagestory.API.Server;

namespace YourModNamespace
{
    public class YourModSystem : ModSystem
    {
        public override void StartServerSide(ICoreServerAPI api)
        {
            base.StartServerSide(api);

            var modGroups = CompatibilityManager.GetRegistrations().GroupBy(r => r.TargetModId);
            foreach (var group in modGroups)
            {
                string modid = group.Key;
                if (ModChecker.IsModLoaded(api, modid))
                {
                    CompatibilityManager.ProcessHandlers(modid, api);
                }
                else
                {
                    api.Logger.Notification($"Mod '{modid}' not detected; skipping compatibility handlers.");
                }
            }
        }
    }
}

• Groups registered handlers by Mod ID.
• Processes handlers if the mod is detected.

Managing Handlers at Runtime

You can enable or disable specific handlers dynamically.

Example: Enabling/Disabling a Handler

CompatibilityManager.SetHandlerEnabled("targetmodid", "Handler for targetmodid", isEnabled: false);

• Useful for runtime debugging or selective feature activation.

Logging and Conflict Resolution

CompatLib includes AnalyticsManager to log conflicts and errors, helping with debugging and ensuring smooth operation.

Example: Logging Conflicts

AnalyticsManager.LogConflict("Conflicting behavior detected between ModA and ModB.");

Example: Retrieving Conflict Logs

foreach (var log in AnalyticsManager.GetConflictLogs())
{
    api.Logger.Notification(log);
}

Exporting Logs to JSON

AnalyticsManager.ExportLogsToJson("path/to/logfile.json");

Debugging: In-Game Commands

CompatLib provides chat commands to retrieve compatibility logs.

Client Command

.compatlog

• Displays conflict logs in the chat.

Server Command

/compatlog

• Shows logs in the server console.

Best Practices

• Modular Handlers: Keep compatibility handlers independent for maintainability.
• Priority Management: Assign priorities strategically to prevent execution conflicts.
• Logging: Use logging features to track compatibility processes.
• Community Collaboration: Work with other modders to enhance compatibility solutions.