PlayerTimer Fabric

A Fabric mod providing independent per-player timers for Minecraft servers and singleplayer worlds.

Each player has their own timer which can:

• count up
• count down
• be paused/resumed
• be hidden or shown independently
• be triggered by commands or command blocks

Designed for:

• minigames
• escape rooms
• timed challenges
• parkour
• speedrunning
• multiplayer events
• adventure maps

---

Features

• Independent timer per player
• Countup and countdown modes
• Brigadier command support
• Pause and resume support
• Timer visibility control
• Countdown completion notification
• Sound effects on completion
• Multiple duration input formats
• Command block compatible using /execute as
• Built for Fabric
• Java 25 support

---

Commands

Command	Description
/playertimer startcountup	Start a countup timer
/playertimer startcountdown	Start a 5 minute countdown
/playertimer startcountdown <duration>	Start a countdown with custom duration
/playertimer pause	Pause the timer
/playertimer resume	Resume a paused timer
/playertimer stop	Stop the timer and hide it
/playertimer reset	Reset timer to 00:00
/playertimer hide	Hide the timer display
/playertimer show	Show the timer display

---

Duration Formats

The countdown command accepts multiple input formats.

Seconds

/playertimer startcountdown 300

Starts a 300 second countdown.

---

Standard Format

/playertimer startcountdown 05:30

Starts a 5 minute 30 second countdown using the mm:ss format.

Rules:

• mm must be between 0 and 59
• ss must be between 0 and 59

Examples:

05:30   ✓ valid
59:59   ✓ valid
60:00   ✗ invalid
05:60   ✗ invalid
99:99   ✗ invalid

---

Extended Format

/playertimer startcountdown 01:40:05

Starts a 1 hour 40 minute 5 second countdown using the hh:mm:ss format.

Rules:

• mm must be between 0 and 59
• ss must be between 0 and 59

Examples:

01:40:05   ✓ valid
10:59:59   ✓ valid
01:60:05   ✗ invalid
01:40:60   ✗ invalid

---

Text Format

/playertimer startcountdown 1h40m5s
/playertimer startcountdown 10m
/playertimer startcountdown 45s
/playertimer startcountdown 2h
/playertimer startcountdown 1h5s

Supports:

• hours (h)
• minutes (m)
• seconds (s)

Any combination may be used.

Rules:

• m must be between 0 and 59
• s must be between 0 and 59

Examples:

1h40m5s   ✓ valid
10m30s    ✓ valid
59m59s    ✓ valid
1h60m     ✗ invalid
10m90s    ✗ invalid
10s49m    ✗ invalid

---

Limits

The maximum allowed duration is:

2147483647 seconds

which is approximately:

68 years

This limit exists because the timer internally uses Java int values.

---

Timer States

Internally 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:

• resuming finished timers
• starting multiple timers simultaneously
• resuming timers that were stopped

---

Visibility

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 becomes hidden
Reset timer	Timer remains visible
Hide command	Timer becomes hidden
Show command	Timer becomes visible

---

Completion

When a countdown reaches zero:

• the timer stops automatically
• the timer enters the FINISHED state
• the player receives a notification
• a bell sound is played

---

Automation

Commands can be triggered via command blocks using Minecraft's execute command.

Example:

execute as @p run playertimer startcountdown 5m

This allows:

• buttons
• pressure plates
• redstone systems
• region triggers
• adventure map integration

---

Requirements

• Java 25
• Gradle
• Fabric Loader
• Fabric API

---

Build

./gradlew build

Compiled jars will appear in:

build/libs/

---

Versioning

PlayerTimer uses the following versioning scheme:

[target-minecraft-version]-[mod-version]

Example:

26.1.x-1.0

Meaning:

• Compatible with Minecraft 26.1.x / API 26.1.x
• Mod release version 1.0

---

Changelog

Release Notes

• Initial Fabric release
• Ported PlayerTimer from Paper to Fabric
• Added per-player timers
• Added countdown and countup modes
• Added timer state system
• Added visibility system
• Added Brigadier command support
• Added command block compatibility
• Added duration parsing with multiple formats
• Added action bar timer display
• Added countdown completion sounds
• Added Java 25 support
• Refactored timer logic into PlayerTimerService

---

License

MIT License