A Fabric mod providing independent per-player timers for Minecraft servers and singleplayer worlds.
Current Fabric build:
26.20.19.3 or newer0.153.0+26.2Each player has their own timer which can:
Designed for:
/execute as| Command | Description |
|---|---|
/playertimer startcountup |
Start a countup timer using the configured default colour |
/playertimer startcountup <color> |
Start a coloured countup timer |
/playertimer startcountdown |
Start a 5 minute countdown using the configured default colour |
/playertimer startcountdown <duration> |
Start a countdown with custom duration using the configured default colour |
/playertimer startcountdown <duration> <color> |
Start a coloured countdown |
/playertimer pause |
Pause the timer |
/playertimer resume |
Resume a paused timer |
/playertimer stop |
Stop the timer and reset it to 00:00 |
/playertimer reset |
Reset timer to 00:00 |
/playertimer hide |
Hide the timer display |
/playertimer show |
Show the timer display |
/playertimer admin clear <player> |
Clear the timer for player <player> (op level 2+) |
/playertimer admin clearall |
Clear the timer for all players (op level 2+) |
The countdown command accepts multiple input formats.
/playertimer startcountdown 300Starts a 300 second countdown.
/playertimer startcountdown 05:30Starts a 5 minute 30 second countdown.
Rules:
mm must be between 0 and 59ss must be between 0 and 59Examples:
05:30 ✓ valid
59:59 ✓ valid
60:00 ✗ invalid
05:60 ✗ invalid
99:99 ✗ invalid/playertimer startcountdown 01:40:05Starts a 1 hour 40 minute 5 second countdown.
Rules:
mm must be between 0 and 59ss must be between 0 and 59Examples:
01:40:05 ✓ valid
10:59:59 ✓ valid
01:60:05 ✗ invalid
01:40:60 ✗ invalid/playertimer startcountdown 1h40m5s
/playertimer startcountdown 10m
/playertimer startcountdown 45s
/playertimer startcountdown 2h
/playertimer startcountdown 1h5sSupports:
h)m)s)Any combination may be used.
Rules:
m must be between 0 and 59s must be between 0 and 59Examples:
1h40m5s ✓ valid
10m30s ✓ valid
59m59s ✓ valid
1h60m ✗ invalid
10m90s ✗ invalid
10s49m ✗ invalidThe maximum allowed duration is:
2147483647 secondswhich is approximately:
68 yearsThis limit exists because the timer internally uses Java int values.
Timers may optionally be started with a colour argument.
| Colour |
|---|
| black |
| dark_blue |
| dark_green |
| dark_aqua |
| dark_red |
| dark_purple |
| gold |
| gray |
| dark_gray |
| blue |
| green |
| aqua |
| red |
| light_purple |
| yellow |
| white |
Examples:
/playertimer startcountup red
/playertimer startcountdown 5m gold
/playertimer startcountdown 01:30 dark_blueInternally the mod tracks timer state using a finite state model.
| State | Meaning |
|---|---|
READY |
Timer exists but has not started |
RUNNING |
Timer is actively counting |
PAUSED |
Timer is temporarily halted |
STOPPED |
Timer was manually stopped |
FINISHED |
Countdown reached zero |
This prevents invalid operations such as:
Timer visibility is independent of timer state.
| Action | Result |
|---|---|
| Start timer | Timer becomes visible |
| Pause timer | Timer remains visible |
| Resume timer | Timer becomes visible |
| Stop timer | Timer remains unchanged |
| Reset timer | Timer remains visible |
| Hide command | Timer becomes hidden |
| Show command | Timer becomes visible |
When a countdown reaches zero:
FINISHED stateCommands can be triggered via command blocks using Minecraft's execute command.
Example:
execute as @p run playertimer startcountdown 5mThis allows:
All timers are saved to disk and restored on server restart or crash recovery. Timer data is stored in:
config/playertimer/timers.jsonConfiguration is stored in:
config/playertimer/config.tomlThe current configuration supports:
defaultColor = "WHITE"Saves occur:
When a timer is restored after a restart, its state is set to PAUSED regardless of whether it was running before — the server was not ticking so the timer was not advancing. If the timer was started by the player directly, they are responsible for resuming it. If the timer was started by a minigame or adventure map, the game is responsible for resuming it.
On load: if a timer entry has a corrupt UUID it is skipped and a warning is logged. If the file cannot be read at all, a RuntimeException is thrown which prevents the mod from initialising.
On save: if the file cannot be written, an error is logged and a RuntimeException is thrown. Because the timer is considered critical infrastructure (e.g. for minigames), this will cause the server to crash rather than continue with unsaved state.
./gradlew buildCompiled jars will appear in:
build/libs/PlayerTimer uses the following versioning scheme:
[mod-version]Example:
1.4.0Minecraft compatibility is tracked in fabric.mod.json, gradle.properties, and the changelog entry for each release.
PlayerTimer domain modelTimerOperationResult enum replacing exception-based control flowPlayerTimerCommand class from PlayerTimerModTimerStore for JSON persistence via GsonTimerCommandContextPlayerTimerServiceMIT License
