Cooldowns & Scheduler - Refinery WIKI

`CooldownManager`

xyz.refineryteam.refinerycore.api.cooldown.CooldownManager tracks arbitrary cooldowns keyed by (namespace, key, subject). The namespace is typically your plugin or feature name (e.g. "kits", "combat"), so two plugins can use the same subject/key without colliding.

The command framework already uses an internal CooldownManager for the @Cooldown annotation — you only need to use this class directly for cooldowns outside of commands (ability usage, kit claims, etc).

KitsManager.java

CooldownManager cooldowns = new CooldownManager();

if (cooldowns.isOnCooldown("kits", "starter", player.getUniqueId())) {
    long remaining = cooldowns.remainingSeconds("kits", "starter", player.getUniqueId());
    context.reply("<red>Wait " + remaining + "s before using this again.");
    return;
}

cooldowns.set("kits", "starter", player.getUniqueId(), Duration.ofMinutes(30));

Method	Description
`set(namespace, key, subject, Duration)`	Starts (or overwrites) a cooldown
`setSeconds(namespace, key, subject, long)`	Shorthand for `set` with a `Duration.ofSeconds(...)`
`isOnCooldown(namespace, key, subject)`	Whether the cooldown is still active (auto-expires and returns `false` once elapsed)
`remainingMillis` / `remainingSeconds`	Time left, or `0` if not on cooldown
`tryAcquire(namespace, key, subject, Duration)`	Atomically checks-and-sets: starts the cooldown only if not already on one, returning `true` if it proceeded
`clear(namespace, key, subject)`	Removes a specific cooldown
`clearAll(subject)`	Removes every cooldown (any namespace/key) for a subject, e.g. on player quit

tryAcquire is the recommended entry point for most “can this action happen” checks, since it avoids a separate check-then-set race.

`PersistentCooldownManager`

xyz.refineryteam.refinerycore.api.cooldown.PersistentCooldownManager is a CooldownManager whose entries survive restarts, backed by a RefineryDatabase. Use it for kit/redemption/reward cooldowns where “relog or restart to skip the wait” would be exploitable. Reads are cached in memory after first load; writes go through to the database immediately (fire-and-forget async by default):

KitManager.java

PersistentCooldownManager kits = new PersistentCooldownManager(plugin, database);
kits.createTable(); // once, in onEnable
kits.loadAll();     // load unexpired rows into the memory cache

if (!kits.tryAcquire("kits", "starter", player.getUniqueId(), Duration.ofHours(24))) {
    long left = kits.remainingSeconds("kits", "starter", player.getUniqueId());
    context.reply("<red>Wait " + left + "s before claiming again.");
}

Method	Description
`createTable()`	Creates the backing `refinery_cooldowns` table — call once during setup
`loadAll()`	Loads all unexpired rows into the memory cache (expired rows are deleted); call after `createTable()` in `onEnable`
`set(namespace, key, subject, Duration)`	Starts a cooldown and persists it asynchronously
`tryAcquire(namespace, key, subject, Duration)`	Atomically starts the cooldown unless one is already active; persists on success and returns whether it was newly applied
`isOnCooldown(...)` / `remainingSeconds(...)` / `remainingMillis(...)`	Same semantics as `CooldownManager`, served from the memory cache
`clear(namespace, key, subject)`	Removes from memory and deletes its row asynchronously
`clearAll(subject)`	Clears every cooldown for a subject (e.g. on staff pardon), in memory and in the database
`purgeExpired()`	Deletes expired rows from the table — call occasionally (daily timer, `onDisable`); the memory cache self-cleans lazily but the table otherwise grows forever

The query API (isOnCooldown, remaining*, tryAcquire) is identical to CooldownManager, so switching an existing feature to persistent cooldowns is a one-line change plus the setup calls.

`RefineryScheduler`

xyz.refineryteam.refinerycore.api.scheduler.RefineryScheduler wraps Paper’s Folia-compatible region/entity/async schedulers behind a flat set of static methods, so plugin code doesn’t need to branch between the legacy BukkitScheduler and Folia’s region-based scheduler APIs.

EntityScheduler.java

RefineryScheduler.runSync(plugin, () -> {
    // runs on the global region scheduler
});

RefineryScheduler.runAsync(plugin, () -> {
    // runs on Paper's async scheduler
});

RefineryScheduler.runForEntity(plugin, someEntity, () -> {
    // runs on the entity's own scheduler — required on Folia for entity-specific logic
});

Method	Description
`runSync(plugin, Runnable)`	Runs once on the global region scheduler
`runSyncDelayed(plugin, Runnable, delayTicks)`	Same, after a tick delay
`runSyncRepeating(plugin, Runnable, delayTicks, periodTicks)`	Repeating task on the global region scheduler
`runAsync(plugin, Runnable)`	Runs once on Paper’s async scheduler
`runAsyncDelayed(plugin, Runnable, delayTicks)`	Same, after a delay (converted internally to milliseconds)
`runAsyncRepeating(plugin, Runnable, delayTicks, periodTicks)`	Repeating async task
`runForEntity(plugin, entity, Runnable)`	Runs once on the given entity’s own scheduler — required for entity-specific logic under Folia’s per-region threading
`runForEntityRepeating(plugin, entity, Runnable, delayTicks, periodTicks)`	Repeating variant of the above
`cancel(ScheduledTask)`	Cancels any task returned by the methods above

Prefer RefineryScheduler over calling Bukkit.getScheduler() directly anywhere your plugin might run on Folia. Mixing the legacy BukkitScheduler with Folia’s region schedulers in the same plugin is a common source of IllegalStateExceptions on Folia servers.

`TaskChain<T>`

xyz.refineryteam.refinerycore.api.scheduler.TaskChain formalizes async→sync→async sequencing. Each step declares where it runs; the chain handles the thread hops so you stop hand-rolling runAsync → runSync nesting:

PlayerLoader.java

TaskChain.of(plugin)
    .async(() -> repository.findPlayer(name))       // async pool
    .abortIfNull(p -> warnNotFound(name))           // bail with a callback if null
    .sync(player -> applyTitle(player))             // global region thread
    .asyncConsume(player -> logToWebhook(player))   // back to async, value unchanged
    .execute();

The current value flows through the chain — each step transforms it (async(Supplier), sync(Function)) or consumes it without changing it (syncConsume, asyncConsume).

Method	Description
`TaskChain.of(plugin)`	Starts a new chain rooted on your plugin; the flowing value starts as `null`
`async(Supplier<R>)`	Runs a supplier on the async scheduler and passes its result onward
`sync(Function<T, R>)`	Runs a transformation on the global region (main) thread
`syncConsume(Consumer<T>)` / `asyncConsume(Consumer<T>)`	Side-effecting steps that keep the flowing value unchanged
`abortIfNull(Consumer<T>)`	Aborts the chain if the current value is `null`, invoking the handler first
`abortIf(Predicate<T>, Consumer<T>)`	Aborts unless the predicate passes, invoking the handler first
`onError(Consumer<Throwable>)`	Error handler for exceptions thrown inside any step; without one, they’re logged to the plugin logger
`execute()`	Kicks off execution — chains are single-use, calling it twice throws

Aborted chains short-circuit: no further steps run once abortIfNull/abortIf fires.

​CooldownManager

​PersistentCooldownManager

​RefineryScheduler

​TaskChain<T>

`CooldownManager`

`PersistentCooldownManager`

`RefineryScheduler`

`TaskChain<T>`