API English

TrackTimer Plugin API

TrackTimer provides a read-only Java API for plugins on the same Paper server. Integrations can query configured events, their live status, and active players with UUIDs, names, and current positions. No HTTP service or separate process is required.

Requirements

• TrackTimer and the integrating plugin run on the same Paper server.
• Use a TrackTimer build containing de.ethria.trackTimer.api.TrackTimerApi.
• Call the API on Paper's main thread. The current implementation accesses TrackTimer's database synchronously and reads Bukkit player/location objects.
• TrackTimer event IDs are numeric long values from TrackTimer's database, not UUIDs.

Declare TrackTimer as an optional server dependency in the consuming plugin's paper-plugin.yml:

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

Set required: true if your plugin cannot work without TrackTimer. The TrackTimer JAR must also be on the compile classpath. The Paper dependency declaration alone does not provide a Maven compile dependency. TrackTimer does not currently publish a separate API artifact. For example, install a locally built TrackTimer JAR with mvn install:install-file and use it with Maven scope provided.

Obtain the API

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 is unavailable; race integration is disabled.");
    return;
}

TrackTimerApi api = trackTimer.getApi();

Query an event

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 copy
            // Associate the UUID and position with your own track.
        });
    });
} catch (SQLException exception) {
    getLogger().warning("Could not read TrackTimer event: " + exception.getMessage());
}

An unknown event ID returns Optional.empty(). getRaces() returns snapshots for all configured TrackTimer events and can also throw SQLException.

Snapshot fields

• RaceSnapshot.eventId(): TrackTimer event database ID.
• RaceSnapshot.eventName(): configured event name.
• RaceSnapshot.status(): NOT_STARTED, RUNNING, or FINISHED.
• RaceSnapshot.activePlayers(): immutable list of players currently racing.
• ActivePlayer.uuid() and name(): driver identity.
• ActivePlayer.location(): current Bukkit location as a copy, including world and coordinates; the player is online.

RUNNING means at least one player has an active race for the event. Players who cross the finish line are removed from activePlayers(). FINISHED is set when a participant completes their race and remains until a new start for that event. Live status is held in memory and resets on server restart. If all drivers cancel or leave before finishing, the current API does not retain an explicit cancelled state.

The API currently returns snapshots on demand and does not provide listeners for race start or finish. Poll at a modest interval if updates are needed. It is designed for same-server plugin integrations, not remote servers or external web clients.