Aevum • Aevum API

##Aevum API

The AevumAPI exposes static methods to drive Aevum from your own plugin — create and control timers/stopwatches, read their time, manage marks, and react to them through Bukkit events or tick handlers.

INFO

Every instance is addressed by a ScopedId — (name, scope, owner). Build one with ScopedId.global(name), ScopedId.player(name, uuid), or ScopedId.team(name, teamId).

###Installation

Add the JitPack repository and the dependency. Replace the version with the latest published tag.

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.33drygo</groupId>
    <artifactId>Aevum</artifactId>
    <version>1.0.0</version>
    <scope>provided</scope>
</dependency>

repositories {
    maven { url = uri("https://jitpack.io") }
}

dependencies {
    compileOnly("com.github.33drygo:Aevum:1.0.0")
}

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    compileOnly 'com.github.33drygo:Aevum:1.0.0'
}

Then declare Aevum as a dependency in your plugin.yml:

name: MyPlugin
main: com.example.MyPlugin
version: 1.0
softdepend:   # use depend instead if Aevum is required
  - Aevum

###Addressing instances — `ScopedId`

dev.drygo.aevum.scope.ScopedId is a record (name, scope, owner). The owner is null for global, the player UUID for player scope, and the team id for team scope.

ScopedId global = ScopedId.global("event");
ScopedId mine   = ScopedId.player("personal", player.getUniqueId());
ScopedId team   = ScopedId.team("round", "red");

Names are restricted to [A-Za-z0-9_-]+ (ScopedId.isValidName). Internally an id serializes to a key like p:personal:<uuid>.

###AevumAPI Methods

All methods are static on dev.drygo.aevum.api.AevumAPI.

Timers

void createTimer(ScopedId id, long seconds) — create a timer of the given duration.
void createGlobalTimer(String name, long seconds) — shorthand for a global timer.
void removeTimer(ScopedId id) / stopTimer(ScopedId id) — delete / stop.
void pauseTimer(ScopedId id) / resumeTimer(ScopedId id) — pause / resume.
void addTimerTime(ScopedId id, long seconds) / removeTimerTime(...) / setTimerTime(...) — adjust remaining time.
long getTimerRemaining(ScopedId id) — remaining seconds.
String getTimerFormatted(ScopedId id) — formatted remaining time.
boolean isTimerRunning(ScopedId id) / isTimerPaused(ScopedId id) / timerExists(ScopedId id) — state checks.
Scope getTimerScope(String name) — the scope a name is locked to.
Set<String> getTimerNames() — every timer name.

AevumAPI.createTimer(ScopedId.global("event"), 300);
AevumAPI.addTimerTime(ScopedId.global("event"), 60);
long left = AevumAPI.getTimerRemaining(ScopedId.global("event"));

Stopwatches

void createStopwatch(ScopedId id) / createStopwatch(ScopedId id, long offset) — create (optionally starting from an offset).
void createGlobalStopwatch(String name) — shorthand for a global stopwatch.
void removeStopwatch(ScopedId id) — delete.
void startStopwatch(ScopedId id) / pauseStopwatch(ScopedId id) / stopStopwatch(ScopedId id) / resetStopwatch(ScopedId id) — control.
void addStopwatchTime(ScopedId id, long seconds) / removeStopwatchTime(...) / setStopwatchElapsed(...) — adjust elapsed time.
long getStopwatchElapsed(ScopedId id) — elapsed seconds.
String getStopwatchFormatted(ScopedId id) — formatted elapsed time.
boolean isStopwatchRunning(ScopedId id) / isStopwatchPaused(ScopedId id) / stopwatchExists(ScopedId id) — state checks.
Scope getStopwatchScope(String name) — the scope a name is locked to.
Set<String> getStopwatchNames() — every stopwatch name.

Marks (checkpoints)

Identical shape for timers (...Timer...) and stopwatches (...Stopwatch...):

Mark markTimer(ScopedId id, String label) — record a checkpoint, returns the Mark.
long getTimerMark(ScopedId id, String label) — seconds recorded at the mark (-1 if absent).
long getTimerMarkEpoch(ScopedId id, String label) — epoch millis when it was recorded.
boolean removeTimerMark(ScopedId id, String label) — remove one; false if absent.
void clearTimerMarks(ScopedId id) — remove all.
Map<String, Mark> getTimerMarks(ScopedId id) — every mark by label.

Mark is a record: Mark(long seconds, long epochMillis).

AevumAPI.markStopwatch(id, "lap1");
Map<String, Mark> marks = AevumAPI.getStopwatchMarks(id);

Tick handlers

Code-driven callbacks run once per second for each running instance — an alternative to listening for the tick events.

void onTimerTick(TimerTickHandler handler) / removeTimerTick(...)
void onStopwatchTick(StopwatchTickHandler handler) / removeStopwatchTick(...)

AevumAPI.onTimerTick((id, remainingSeconds) -> {
    if (id.name().equals("event") && remainingSeconds == 10) {
        Bukkit.broadcastMessage("10 seconds left!");
    }
});

TimerTickHandler and StopwatchTickHandler are functional interfaces:
void onTick(ScopedId id, long remainingSeconds) and void onTick(ScopedId id, long elapsedSeconds).

###Events

Aevum fires standard Bukkit events you can listen to with a normal listener. They all carry name, scope and owner.

Timer events — dev.drygo.aevum.timer.events

TimerStartEvent — getName(), getScope(), getOwner(), getDurationSeconds().
TimerTickEvent — fired once per second before zero. getRemainingSeconds().
TimerEndEvent — fired when the countdown reaches zero.
TimerMarkEvent — a checkpoint was recorded. getLabel(), getSeconds() (remaining at the mark), getEpochMillis().

@EventHandler
public void onEnd(TimerEndEvent event) {
    if (event.getName().equals("event")) {
        Bukkit.broadcastMessage("The event timer ended!");
    }
}

Stopwatch events — dev.drygo.aevum.stopwatch.events

StopwatchStartEvent — a stopwatch started. getName(), getScope(), getOwner().
StopwatchTickEvent — fired once per whole second while running.
StopwatchMarkEvent — a checkpoint was recorded. getLabel(), getSeconds() (elapsed at the mark), getEpochMillis().

Stopwatches count up indefinitely, so there is no "end" event — pause, reset or delete them through the API or commands.

###Notes

All AevumAPI methods are static — no instantiation needed.
Mutating methods affect the Aevum-managed instances directly; the same instances surface in /aevum, placeholders and persistence.
A name is locked to one scope; use getTimerScope / getStopwatchScope to discover it before building a ScopedId.
Team scope requires the Stella plugin to be present at runtime.
Like all Bukkit work, call mutating methods from the main thread.