API Deutsch

TrackTimer Plugin-API

TrackTimer stellt eine Read-only-Java-API für andere Plugins auf demselben Paper-Server bereit. Damit lassen sich Events, ihr Live-Status sowie aktive Spieler einschließlich UUID, Name und aktueller Position abfragen. Ein HTTP-Dienst oder separater Prozess ist dafür nicht nötig.

Voraussetzungen

• TrackTimer und das integrierende Plugin laufen auf demselben Paper-Server.
• Verwende einen TrackTimer-Build, der de.ethria.trackTimer.api.TrackTimerApi enthält.
• API-Aufrufe müssen auf dem Paper-Hauptthread erfolgen. Die aktuelle Implementierung greift synchron auf die TrackTimer-Datenbank und Bukkit-Spieler-/Positionsobjekte zu.
• TrackTimer-Event-IDs sind numerische long-Werte aus der TrackTimer-Datenbank, keine UUIDs.

Trage TrackTimer in der paper-plugin.yml des konsumierenden Plugins als optionale Abhängigkeit ein:

dependencies:
  server:
    TrackTimer:
      load: BEFORE
      required: false
      join-classpath: true

Setze required: true, wenn dein Plugin ohne TrackTimer nicht funktionieren kann. Zum Kompilieren muss das TrackTimer-JAR zusätzlich auf dem Compile-Classpath liegen. Die Paper-Abhängigkeitsdeklaration allein stellt keine Maven-Compile-Abhängigkeit bereit. TrackTimer veröffentlicht derzeit kein separates API-Artefakt. Ein lokal gebautes TrackTimer-JAR kann beispielsweise mit mvn install:install-file als Abhängigkeit mit Maven-Scope provided eingebunden werden.

API beziehen

import de.ethria.trackTimer.TrackTimer;
import de.ethria.trackTimer.api.TrackTimerApi;
import org.bukkit.plugin.Plugin;

Plugin dependency = getServer().getPluginManager().getPlugin("TrackTimer");
if (!(dependency instanceof TrackTimer trackTimer) || !dependency.isEnabled()) {
    getLogger().info("TrackTimer ist nicht verfügbar; Rennintegration bleibt aus.");
    return;
}

TrackTimerApi api = trackTimer.getApi();

Ein Event abfragen

import java.sql.SQLException;

try {
    api.getRace(eventId).ifPresent(race -> {
        getLogger().info("TrackTimer-Event " + race.eventName()
                + " (" + race.eventId() + "): " + race.status());

        race.activePlayers().forEach(driver -> {
            var uuid = driver.uuid();
            var name = driver.name();
            var location = driver.location(); // defensive Kopie
            // UUID und Position der eigenen Strecke zuordnen.
        });
    });
} catch (SQLException exception) {
    getLogger().warning("TrackTimer-Event konnte nicht gelesen werden: " + exception.getMessage());
}

Eine unbekannte Event-ID ergibt Optional.empty(). getRaces() liefert Snapshots für alle konfigurierten TrackTimer-Events und kann ebenfalls SQLException werfen.

Snapshot-Felder

• RaceSnapshot.eventId(): Datenbank-ID des TrackTimer-Events.
• RaceSnapshot.eventName(): konfigurierter Event-Name.
• RaceSnapshot.status(): NOT_STARTED, RUNNING oder FINISHED.
• RaceSnapshot.activePlayers(): unveränderliche Liste der Spieler, die aktuell fahren.
• ActivePlayer.uuid() und name(): Identität des Fahrers.
• ActivePlayer.location(): aktuelle Bukkit-Position als Kopie mit Welt und Koordinaten; der Spieler ist online.

RUNNING bedeutet, dass mindestens ein Spieler für das Event ein aktives Rennen hat. Wer die Ziellinie überquert hat, wird aus activePlayers() entfernt. FINISHED wird gesetzt, sobald ein Teilnehmer sein Rennen beendet hat, und bleibt bis zu einem neuen Start dieses Events bestehen. Der Live-Status liegt im Arbeitsspeicher und wird bei einem Serverneustart zurückgesetzt. Wenn alle Fahrer vor dem Zieleinlauf abbrechen oder den Server verlassen, speichert die aktuelle API keinen eigenen Abbruchstatus.

Die API liefert derzeit Snapshots auf Anfrage und keine Listener für Start oder Ende eines Rennens. Für Aktualisierungen sollte ein maßvolles Abfrageintervall verwendet werden. Die API ist für Plugins auf demselben Server vorgesehen, nicht für entfernte Server oder externe Web-Clients.