Integration API

Overview

MMO Skill Tree supports optional integrations with other Hytale mods. External mods can provide adapters that hook into MMO Skill Tree's systems (e.g., awarding Fishing XP when a fishing mod fires a catch event) without either mod hard-depending on the other.

The integration system has two layers:

1. Built-in adapters — MMO Skill Tree ships with adapters for supported mods. Each adapter uses reflection to detect whether the target mod is installed and self-activates at startup. No server config required.
2. Config overrides — Server owners can optionally disable or re-prioritize adapters via integrations.json.

Compatible Mods

MMO Skill Tree ships with built-in support for the following mods:

No configuration is needed — just install both mods and the integration activates automatically. Check [Integrations] in your server log to confirm it's active.

For Mod Authors

To integrate your mod with MMO Skill Tree, add the API jar as a compile-only dependency and implement the appropriate interface. Your adapter is discovered automatically at server startup.

Step 1: Add the API Dependency

The API is published as a separate, lightweight jar (mmoskilltree-api) versioned independently from the main plugin. Add it as compileOnly so it's available at compile time but not bundled into your jar — MMO Skill Tree provides it at runtime.

// build.gradle
dependencies {
    compileOnly 'ziggfreed:mmoskilltree-api:1.0.0'
}

The API jar contains only interfaces and annotations — no plugin logic, no transitive dependencies beyond JSR-305 nullability annotations.

Step 2: Implement the Domain Interface

Each integration domain has a specific interface. Currently available:

Implement the interface and annotate your class with @IntegrationMeta to declare your domain and priority:

import com.ziggfreed.mmoskilltree.integration.IntegrationDomain;
import com.ziggfreed.mmoskilltree.integration.IntegrationMeta;
import com.ziggfreed.mmoskilltree.integration.fishing.FishingIntegration;

@IntegrationMeta(
    domain = IntegrationDomain.FISHING,
    priority = 10
)
public class YourFishingAdapter implements FishingIntegration {

    @Override
    public String getModName() {
        return "Your Fishing Mod";
    }

    @Override
    public boolean initialize() {
        // Set up reflection handles, verify your mod's API is available
        // Return false to gracefully skip this adapter
        return true;
    }

    @Override
    public void shutdown() {
        // Clean up resources
    }

    @Override
    public void onFishCaught(String playerName, String fishIdentifier, int rarity) {
        // Called by MMO Skill Tree when it detects a fish catch
    }

    @Override
    public boolean isFishItem(String itemIdentifier) {
        // Return true if your mod recognizes this as a fish
        return false;
    }

    @Override
    public String getFishDisplayName(String fishIdentifier) {
        // Return a human-readable name for the fish, or null
        return null;
    }
}

@IntegrationMeta Fields

Step 3: Submit Your Adapter

Built-in adapters are registered explicitly inside MMO Skill Tree (Hytale mod classloaders don't support Java ServiceLoader discovery). To add your adapter:

1. Build your adapter following the patterns above
2. Open a pull request or reach out on Discord to have it included in the next release

Once registered, MMO Skill Tree calls your adapter's initialize() at startup. If your mod isn't installed, initialize() returns false (via a failed Class.forName()) and the adapter is silently skipped. No server owner configuration needed.

Step 4: Reflection Pattern for External API Calls

Your adapter should never directly import classes from the mod it integrates with. Instead, use reflection to access the external mod's API. This ensures your adapter compiles even if the target mod isn't present at build time.

// WRONG - breaks if the mod isn't on the classpath
import com.example.fishmod.FishAPI;

// RIGHT - reflection-safe
public class MyAdapter implements FishingIntegration {
    private static final String API_CLASS = "com.example.fishmod.FishAPI";
    private Method isFishMethod;
    private Object apiInstance;

    @Override
    public boolean initialize() {
        try {
            Class<?> api = Class.forName(API_CLASS);
            apiInstance = api.getMethod("getInstance").invoke(null);
            isFishMethod = api.getMethod("isFish", String.class);
            return true;
        } catch (Exception e) {
            return false;  // Gracefully skip
        }
    }

    @Override
    public boolean isFishItem(String id) {
        try {
            return (Boolean) isFishMethod.invoke(apiInstance, id);
        } catch (Exception e) {
            return false;
        }
    }
}

Selection Behavior

When multiple adapters are discovered for the same domain (e.g., two fishing mod integrations), MMO Skill Tree selects one using this process:

1. All discovered adapters are grouped by domain
2. Within each domain, adapters are sorted by effective priority (lowest first)
3. Each adapter is tried in order:
   • If disabled in config → skip
   • If initialize() returns false or throws → skip (target mod not installed)
   • First adapter that passes all checks becomes active
4. If no adapter succeeds, the domain uses a no-op implementation (safe, does nothing)

Config Overrides (Server Owners)

By default, all discovered adapters are enabled and use their annotation-declared priority. Server owners can override this in mods/mmoskilltree/integrations.json:

{
  "schemaVersion": 1,
  "overrides": {
    "com.example.MyFishingAdapter": {
      "enabled": false
    },
    "com.other.BetterFishingAdapter": {
      "priority": 1
    }
  }
}

Override keys are the fully qualified class name of the adapter. Available fields:

If the file doesn't exist, an empty one is generated on first startup. Server owners never need to edit it unless they want to disable or re-order integrations.

Startup Logging

MMO Skill Tree logs the full integration resolution process at startup. Look for lines prefixed with [Integrations] in the server log:

[INFO] [Integrations] Discovered 4 adapter(s) (explicit registry)
[INFO] [Integrations] Fishing: activated HyFishing via ...HyFishingAdapter
[INFO] [Integrations] Parries: activated PerfectParries via ...PerfectParriesAdapter
[INFO] [Integrations] Citizens: activated HyCitizens via ...HyCitizensAdapter
[INFO] [Integrations] SimpleEnchantments adapter initialized — event bus handlers registered
[INFO] [Integrations] === Integration Resolution Summary ===
[INFO] [Integrations] Fishing: ACTIVE - HyFishing | ...
[INFO] [Integrations] Parries: ACTIVE - PerfectParries | ...
[INFO] [Integrations] Citizens: ACTIVE - HyCitizens | ...
[INFO] [Integrations] Enchanting: ACTIVE - SimpleEnchantments | ...
[INFO] [Integrations] ========================================

API Reference

All classes are in the com.ziggfreed.mmoskilltree.integration package.

Quick Start Checklist