Overview
SimpleTime is a utility class for working with time values in a human-readable format. It converts strings like “5 minutes” or “2 hours” into ticks, seconds, or milliseconds.
Creating time instances
from
Creates a SimpleTime from a human-readable string.
Time string like “1 second”, “5 minutes”, “2 hours”, etc.
A new SimpleTime instance.
SimpleTime time = SimpleTime.from("5 minutes");
SimpleTime disabled = SimpleTime.from("none");
SimpleTime ticks = SimpleTime.from("100 ticks");
fromSeconds
Creates a SimpleTime from a number of seconds.
A new SimpleTime instance.
SimpleTime time = SimpleTime.fromSeconds(300); // 5 minutes
- Ticks:
"20 ticks", "100 ticks"
- Seconds:
"1 second", "30 seconds"
- Minutes:
"5 minutes", "1 minute"
- Hours:
"2 hours", "1 hour"
- Days:
"7 days", "1 day"
- Disabled:
"none", "never", "0"
SimpleTime ticks = SimpleTime.from("20 ticks");
SimpleTime seconds = SimpleTime.from("30 seconds");
SimpleTime minutes = SimpleTime.from("5 minutes");
SimpleTime hours = SimpleTime.from("2 hours");
SimpleTime days = SimpleTime.from("7 days");
SimpleTime disabled = SimpleTime.from("none");
Methods
getTimeTicks
Gets the time in ticks (1 second = 20 ticks).
SimpleTime time = SimpleTime.from("5 seconds");
int ticks = time.getTimeTicks(); // 100
If the time ticks exceeds Integer.MAX_VALUE, it will overflow. Use the long variant if needed.
getTimeSeconds
Gets the time in seconds.
SimpleTime time = SimpleTime.from("2 minutes");
long seconds = time.getTimeSeconds(); // 120
getTimeMilliseconds
Gets the time in milliseconds.
The time in milliseconds.
SimpleTime time = SimpleTime.from("1 second");
long millis = time.getTimeMilliseconds(); // 1000
getRaw
Gets the original human-readable string.
The original time string.
SimpleTime time = SimpleTime.from("5 minutes");
String raw = time.getRaw(); // "5 minutes"
isEnabled
Checks if the time is enabled (not “none”, “never”, or “0”).
True if the time is enabled.
SimpleTime time = SimpleTime.from("5 minutes");
if (time.isEnabled()) {
// Schedule task
}
SimpleTime disabled = SimpleTime.from("none");
if (!disabled.isEnabled()) {
// Skip scheduling
}
Time comparison methods
isOverLimitMs
Checks if the given timestamp has passed the time limit.
The timestamp in milliseconds to check against.
True if current time - limit > this time.
SimpleTime cooldown = SimpleTime.from("5 minutes");
long lastUsed = System.currentTimeMillis();
// Later...
if (cooldown.isOverLimitMs(lastUsed)) {
// Cooldown expired
player.sendMessage("You can use this ability again!");
}
isUnderLimitMs
Checks if the given timestamp has not yet passed the time limit.
The timestamp in milliseconds to check against.
True if current time - limit < this time.
SimpleTime cooldown = SimpleTime.from("10 seconds");
long lastUsed = System.currentTimeMillis();
if (cooldown.isUnderLimitMs(lastUsed)) {
// Still on cooldown
String timeLeft = cooldown.formatWaitTime(lastUsed);
player.sendMessage("Wait " + timeLeft + " before using again!");
}
The timestamp of the last execution.
Human-readable time remaining (e.g., “5m 23s”).
SimpleTime cooldown = SimpleTime.from("30 minutes");
long lastUsed = System.currentTimeMillis();
String remaining = cooldown.formatWaitTime(lastUsed);
player.sendMessage("Cooldown: " + remaining);
// Output: "Cooldown: 29m 59s"
Usage examples
Cooldown system
public class AbilityCooldown {
private final Map<UUID, Long> cooldowns = new HashMap<>();
private final SimpleTime cooldownTime;
public AbilityCooldown(String cooldown) {
this.cooldownTime = SimpleTime.from(cooldown);
}
public boolean canUse(Player player) {
if (!cooldowns.containsKey(player.getUniqueId())) {
return true;
}
long lastUsed = cooldowns.get(player.getUniqueId());
return cooldownTime.isOverLimitMs(lastUsed);
}
public void use(Player player) {
cooldowns.put(player.getUniqueId(), System.currentTimeMillis());
}
public String getRemainingTime(Player player) {
if (!cooldowns.containsKey(player.getUniqueId())) {
return "Ready";
}
long lastUsed = cooldowns.get(player.getUniqueId());
if (cooldownTime.isOverLimitMs(lastUsed)) {
return "Ready";
}
return cooldownTime.formatWaitTime(lastUsed);
}
}
// Usage
AbilityCooldown cooldown = new AbilityCooldown("5 minutes");
if (cooldown.canUse(player)) {
// Execute ability
cooldown.use(player);
player.sendMessage("Ability used!");
} else {
String remaining = cooldown.getRemainingTime(player);
player.sendMessage("Wait " + remaining + " before using again!");
}
Configuration with SimpleTime
public class MyConfig {
@Getter
private static SimpleTime saveInterval;
@Getter
private static SimpleTime sessionTimeout;
private static void init() {
saveInterval = SimpleTime.from(
getString("Save_Interval", "5 minutes")
);
sessionTimeout = SimpleTime.from(
getString("Session_Timeout", "30 minutes")
);
}
}
// Start auto-save task
if (MyConfig.getSaveInterval().isEnabled()) {
Common.runTimer(
MyConfig.getSaveInterval().getTimeTicks(),
() -> saveData()
);
}
Scheduled tasks
public void scheduleAnnouncement(String message, String interval) {
SimpleTime time = SimpleTime.from(interval);
if (!time.isEnabled()) {
return; // Skip if disabled
}
Common.runTimer(
time.getTimeTicks(),
time.getTimeTicks(),
() -> Bukkit.broadcastMessage(message)
);
}
// Usage
scheduleAnnouncement("&6Server restart in 1 hour!", "10 minutes");
scheduleAnnouncement("&7Tip: Use /help for commands", "5 minutes");
Session expiration
public class UserSession {
private final UUID playerId;
private long lastActivity;
private static final SimpleTime TIMEOUT = SimpleTime.from("30 minutes");
public UserSession(UUID playerId) {
this.playerId = playerId;
this.lastActivity = System.currentTimeMillis();
}
public void updateActivity() {
this.lastActivity = System.currentTimeMillis();
}
public boolean isExpired() {
return TIMEOUT.isOverLimitMs(lastActivity);
}
public String getTimeUntilExpiry() {
if (isExpired()) {
return "Expired";
}
return TIMEOUT.formatWaitTime(lastActivity);
}
}
Notes
- SimpleTime automatically converts between ticks, seconds, and milliseconds
- Use
"none", "never", or "0" to create disabled time instances
- The
getTimeTicks() method returns an int and may overflow for very large values
- Time comparisons use
System.currentTimeMillis() internally
- All time values are immutable once created