Durations

Package: dev.anchorlight.stonelib.time

Time shown to players comes in three shapes that are not interchangeable. 18:30 in a sentence reads as a time of day, and 18 minutes 30 seconds does not fit on a scoreboard. Durations gives each shape its own method, so the choice is explicit.

Formats

Method	Use it for	Examples
clock	Bossbars and live countdowns, where the digits are ticking and the reader is watching them.	0:05, 12:34, 1:02:33
human	Prose: a quest description, a cooldown message. Never renders like a clock.	1 second, 30 seconds, 18 minutes, 18m 30s, 2 hours, 2h 5m
compact	Sidebars and status lines, where space is tight. At most two units.	30s, 5m 30s, 2h 5m

Each takes either a Duration or a whole number of seconds:

Durations.clock(Duration.ofSeconds(754));      // "12:34"
Durations.human(Duration.ofMinutes(18));       // "18 minutes"
Durations.human(1110);                         // "18m 30s"
Durations.compact(Duration.ofSeconds(7530));   // "2h 5m"

Exact output

Input	clock	human	compact
0 seconds	0:00	0 seconds	0s
1 second	0:01	1 second	1s
45 seconds	0:45	45 seconds	45s
1 minute	1:00	1 minute	1m 0s
18 minutes 30 seconds	18:30	18m 30s	18m 30s
1 hour	1:00:00	1 hour	1h 0m
1 hour 30 seconds	1:00:30	1h 0m	1h 0m
2 hours 5 minutes 40 seconds	2:05:40	2h 5m	2h 5m
50 hours	50:00:00	50 hours	50h 0m

Rules behind the table:

• Hours never roll over into days.
• Once there are hours, human and compact show only hours and minutes, dropping seconds.
• human uses a spelled-out, correctly pluralised unit only when the value is a whole number of that unit, and the short form otherwise.
• Fractions of a second are dropped, never rounded up.
• null and negative durations are shown as zero.

Ticks

Method	Meaning
toTicks(Duration)	Whole server ticks, at 20 per second, for scheduler calls.

scheduler.runSyncLater(this::endRound, Durations.toTicks(Duration.ofMinutes(5)));   // 6000 ticks

toTicks works in whole seconds, so Duration.ofMillis(1500) becomes 20 ticks, not 30, and anything under a second becomes 0. For sub-second delays, pass a tick count directly.