Developer API

Carousel exposes its registry, live ride settings and cancellable Bukkit rider events. Integrations run on the server thread. Source access is private; using a binary dependency does not grant source redistribution rights.

Binary Dependency

Place your authorized carousel-2.0.4.jar in your integration’s libs/ directory. Use a compile-only dependency; do not shade or redistribute Carousel inside another plugin.

Gradle Groovy

dependencies {
    compileOnly files('libs/carousel-2.0.4.jar')
}

Gradle Kotlin

dependencies {
    compileOnly(files("libs/carousel-2.0.4.jar"))
}

Declare the runtime dependency in your integration’s plugin.yml:

depend: [Carousel]

Use softdepend only for an optional integration and guard every Carousel API reference when the plugin is unavailable.

Registry Access

import dev.despical.carousel.CarouselPlugin;
import dev.despical.carousel.core.Carousel;

CarouselPlugin carouselPlugin = CarouselPlugin.getInstance();
Carousel ride = carouselPlugin.getCarouselRegistry().getCarousel("spawn");

if (ride != null) {
    String id = ride.getName();
}

The ID accessor is getName(), not getId(). Registry IDs are case-sensitive. Lookups return null when absent; collections are immutable snapshots containing live references.

Calls such as start(), stop() and restart() manage transient entities. Settings setters do not validate, save or restart automatically. Registry registration/unregistration also does not persist data. For an intentional settings change, use the exposed storage service to save the registered ride and restart it if needed.

Lifecycle and Thread Ownership

Use the API only after Carousel is enabled, on the Bukkit server thread. A reload replaces registry instances: resolve a fresh ride instead of retaining stale references. Do not move entities, modify settings or publish rider events asynchronously.

Rider Events

• CarouselMountEvent: after access and saddle checks, before normal mounting feedback.
• CarouselDismountEvent: before normal dismount feedback.

Both extend dev.despical.carousel.api.event.CarouselEvent, expose getCarousel() and getPlayer(), and implement Bukkit Cancellable. Cancel the concrete event to prevent its normal underlying interaction and feedback. Forced teardown/disconnect paths may still detach passengers.

Authorized collaborators can generate local reference documentation with gradlew.bat javadocJar. This guide does not publish Carousel source or register a public Javadoc site.