02 / Java API

Java API-installation

Denne guide viser, hvordan du bygger et Paper-plugin med MineCore Java API’et. Den følger strukturen i MineCore-repositoriets example-module.

1. Opret et Paper-plugin

Dit plugin skal have en klasse, der arver fra JavaPlugin, og en plugin.yml. Eksemplet bruger ExamplePlugin som entrypoint.

package dk.mineclub.minecore.example;

import org.bukkit.plugin.java.JavaPlugin;

public class ExamplePlugin extends JavaPlugin {
    @Override
    public void onEnable() {
        getLogger().info("ExamplePlugin er startet");
    }
}

2. Tilføj MineCore API’et

Eksemplet bruger Java 25-varianten af API’et. Vælg den artifact, der matcher din valgte Java target.

dependencies {
    implementation("dk.mineclub.minecore:api-jvm25:0.1.1")
    compileOnly("io.papermc.paper:paper-api:$paperApiVersion")
}

MineCore-eksemplet bruger Gradle Kotlin DSL i example/build.gradle.kts. Det aktiverer også Shadow-plugin’et, så plugin-JAR’en kan bygges som en samlet distribution.

plugins {
    id("java-library")
    alias(libs.plugins.shadow)
}

Husk at gøre MineCore API’et tilgængeligt ved runtime. Du skal enten shade API’et ind i din egen plugin-JAR med Shadow, eller bruge MineCore som separat plugin og deklarere det som en soft dependency.

Hvis MineCore leveres separat på serveren, kan dependency’en være compileOnly, så API’et ikke pakkes endnu en gang ind i dit plugin:

dependencies {
    compileOnly("dk.mineclub.minecore:api-jvm25:0.1.1")
}

3. Konfigurér plugin.yml

Opret src/main/resources/plugin.yml, og peg main på din JavaPlugin-klasse:

name: "ExamplePlugin"
main: "dk.mineclub.minecore.example.ExamplePlugin"
version: "${version}"

Tilføj softdepend, når MineCore ligger som separat plugin i serverens plugins/-mappe:

name: "ExamplePlugin"
main: "dk.mineclub.minecore.example.ExamplePlugin"
version: "${version}"
softdepend:
  - MineCore

Brug kun softdepend-modellen, hvis MineCore-plugin’et faktisk er installeret. Hvis du shader API’et ind i din egen JAR, skal du ikke gøre din plugin afhængig af en separat MineCore-installation.

4. Hent MineCoreApi

Eksemplet opretter en API-instans i onEnable() og registrerer derefter event-listeners på MineCore’s async event bus.

public class ExamplePlugin extends JavaPlugin {
    public MineCoreApi api;

    @Override
    public void onEnable() {
        api = new MineCoreApi();
        StoreListeners listeners = new StoreListeners(api, this);
        api.getAsyncEventBus().register(listeners);
    }
}

5. Opret en request

Eksemplets BuyCommand bygger et StoreProduct, lægger det i en StoreRequest og sender requesten gennem request-manageren.

StoreProduct product = StoreProduct.builder()
    .name("Example Product")
    .id("example_product")
    .price(1)
    .quantity(1)
    .build();

StoreRequest request = StoreRequest.builder()
    .storeProducts(new StoreProduct[] {product})
    .mcaccount(player.getUniqueId())
    .build();

plugin.api.getMinecoreRequestManager().createRequest(request);

6. Opret serverbetalinger

MineCore Java API’et understøtter også serverbetalinger gennem RequestManager. En ServerPayRequest indeholder spillerens Minecraft-konto som tekst i mcaccount og beløbet i amount. Send requesten gennem createServerPay; metoden returnerer en ServerPayResponse, hvis kaldet lykkes.

ServerPayRequest payRequest = ServerPayRequest.builder()
    .mcaccount(player.getUniqueId().toString())
    .amount(10.0)
    .build();

ServerPayResponse response =
    plugin.api.getMinecoreRequestManager().createServerPay(payRequest);

if (response != null) {
    plugin.getLogger().info("Serverbetaling oprettet");
}

API’et serialiserer requesten til JSON og sender den til /server/pay med MineCore-tokenet. Hvis requesten er null, hvis svaret mangler, eller hvis kaldet fejler, returnerer createServerPay null.

ServerPayRequest payRequest = ServerPayRequest.builder()
    .mcaccount("player-uuid")
    .amount(10.0)
    .build();

JsonObject json = payRequest.toJson();

Brug altid ServerPayRequest og ServerPayResponse fra samme API-artifact som resten af dit plugin.

7. Hent og håndtér votes

Votes kan hentes gennem RequestManager.getVotes. Brug GetVotesOptions til at filtrere på spiller, status, side og antal resultater. GetVotesResponse.getAll() giver vote-listen, uanset om svaret er pagineret.

GetVotesOptions options = GetVotesOptions.builder()
    .mcaccount(player.getUniqueId().toString())
    .page(1)
    .limit(25)
    .withMeta(true)
    .build();

  GetVotesResponse response =
    plugin.api.getMinecoreRequestManager().getVotes(options);

  if (response != null && response.getAll() != null) {
    for (MappedVote vote : response.getAll()) {
      plugin.getLogger().info("Vote: " + vote.getId());
    }
  }

En MappedVote indeholder blandt andet id, status, createdAt, updatedAt og mcaccount. Når et modtaget vote er behandlet, markeres det med acceptVote(vote). Brug rejectVote(vote), hvis vote-data ikke kan behandles.

MappedVote vote = event.getVote();

  if (vote != null && processVote(vote)) {
    plugin.api.getMinecoreRequestManager().acceptVote(vote);
  } else if (vote != null) {
    plugin.api.getMinecoreRequestManager().rejectVote(vote);
  }

8. Håndtér events

Registrér en klasse med Guava’s @Subscribe. MineCore’s example håndterer pre-create, post-create, modtagne requests og votes i samme listener:

@Subscribe
public void receiveEvent(ReceiveRequestEvent event) {
    StoreCreatedRequest request = event.getStoreRequest();
    if (request == null) {
        return;
    }

    processRequest(request);
    mineCoreApi.getMinecoreRequestManager().acceptRequest(request);
}

@Subscribe
public void receiveVoteEvent(ReceiveVoteEvent event) {
    MappedVote vote = event.getVote();
    processVote(vote);
    mineCoreApi.getMinecoreRequestManager().acceptVote(vote);
}

Se event-livscyklus-guiden for forskellen på de enkelte events og hvornår de kaldes.

9. Byg og installér

Kør buildet fra MineCore-projektets rod med Gradle wrapperen:

./gradlew :example:build

På Windows kan du bruge:

.\\gradlew.bat :example:build

Installér den byggede JAR fra example/build/libs/ i Paper-serverens plugins/-mappe, og genstart serveren. Brug samme Java target til API-artifact, compile target og serverens JVM.

API-eksemplet er baseret på MineCore’s dev-branch. Tjek altid den konkrete release, før du låser artifact-version og Paper API-version i dit eget plugin.