Java and Kotlin plugin API

The plugin API is for code running in the same JVM as the EnderDash agent. External scripts should use the HTTP API.

The API is experimental. Match the dependency to a supported agent release and handle missing providers, nullable history, and asynchronous failures.

Add a compile-only dependency

Kotlin Gradle consumers can resolve the multiplatform artifact's JVM variant:

repositories { mavenCentral() }
dependencies { compileOnly("com.enderdash:enderdash-api:VERSION") }

Java or Maven consumers should use the JVM artifact:

<dependency>
  <groupId>com.enderdash</groupId>
  <artifactId>enderdash-api-jvm</artifactId>
  <version>VERSION</version>
  <scope>provided</scope>
</dependency>

Replace VERSION with a released version compatible with your installed agent. See Maven Central for published JVM versions.

The agent supplies the API at runtime. Do not shade it into your plugin. A second copy can have a separate provider and fail to see the agent's instance.

Declare load order

For Bukkit or Paper, add this to plugin.yml:

softdepend: [EnderDash]

For BungeeCord or Waterfall, use the capitalized key in bungee.yml or plugin.yml:

softDepends: [EnderDash]

For Velocity, declare an optional plugin dependency with ID enderdash in the plugin annotation. Use a required dependency instead if your plugin cannot function without EnderDash.

A soft dependency permits startup without EnderDash. Your code must handle that case and retry during the platform's server-ready or plugin-enable lifecycle if needed.

Retrieve the provider from Java

The current API uses a Kotlin companion object. Java calls the accessor through Companion:

import com.enderdash.agent.api.EnderDashApi;

public final class EnderDashIntegration {
  public void onEnable() {
    EnderDashApi api = EnderDashApi.Companion.getOrNull();
    if (api == null) {
      // Defer the lookup until the platform reports that EnderDash has loaded.
      return;
    }
    System.out.println("EnderDash API " + api.getApiVersion() + " on server " + api.getServerId());
  }
}

Kotlin uses EnderDashApi.getOrNull(). The strict get() accessor fails when no provider has been registered. Use it only when your lifecycle guarantees the agent is ready.

Public surface

History lookups do not query Mojang or perform a new network lookup. Blank, malformed, unknown, or unenriched inputs can return null. A missing result is not a negative identity decision.

Do not call the internal setProvider method. The agent owns provider registration and shutdown.

Hosted verification and lifecycle

Creation and cancellation are Kotlin suspending functions. Call them from your plugin's managed coroutine lifecycle. A registered validation handler returns an AutoCloseable; close it when the plugin shuts down.

Use the complete verification example. It handles registration, challenge identity, explicit validation, and cleanup.

API documentation and validation

The JVM API documentation describes the selected published version. The source and generated documentation for the agent version you target define its contract.

This repository compiles the Java and Kotlin examples with ./gradlew :enderdash-api:checkDocExamples. A dependency or API change must keep those examples compiling.