🕒 ChallengeTimer

A powerful and flexible Minecraft plugin for tracking challenge completion times with persistent data storage and customizable display options.

---

✨ Features

• 🎯 Dual Timer Modes: Global timer for all players or individual timers per player
• 💾 Persistent Storage: Timer data survives server restarts and player disconnections
• ⏸️ Smart Auto-Pause: Automatically pauses timers when players leave the server
• 🎨 Fully Customizable: Configure colors, text, and timer behavior
• 📊 Real-time Display: Timer shown in action bar with play/pause indicators
• 🔄 Seamless Resume: Continue exactly where you left off after reconnecting

---

🚀 Installation

1. Download the latest ChallengeTimer.jar file
2. Place it in your server's plugins folder
3. Start/restart your server
4. Configure the plugin in plugins/ChallengeTimer/config.yml
5. Reload or restart the server to apply changes

---

🎮 Commands

Command	Permission	Description
/start	challengetimer.start	Start or resume the timer
/pause	challengetimer.pause	Pause the running timer
/reset	challengetimer.reset	Reset the timer to 00:00:00

Note: In individual timer mode, commands can only be used by players. In global mode, commands work from console and in-game.

---

⚙️ Configuration

Basic Settings

# ChallengeTimer Plugin Configuration
# Supports Minecraft Colors aswell as Hex-Code Colors

# Individual timers mode
# If true: Each player has their own timer
# If false: Global timer for all players
individual_timers: false

text:
  timer_label: "Challenge Timer"
  timer_divider: " >> "
  start_label: " ⏸ "
  pause_label: " ▶ "

colors:
  timer_title: "gold"        # Color for Timer Label
  start_label: "yellow"      # Color for start Icon
  stop_label: "green"        # Color for pause Icon
  days: "green"              # Color for Days
  hours: "aqua"              # Color for Hours
  minutes: "yellow"          # Color for Minutes
  seconds: "white"           # Color for Seconds
  separator: "gray"          # Color for Seperator (e.g. days, hours, minutes, seconds)~~~~

Timer Modes

🌍 Global Timer Mode (individual_timers: false)

• Single shared timer for all players
• Timer pauses when the last player leaves the server
• Commands work from console and in-game
• Perfect for server-wide challenges

👤 Individual Timer Mode (individual_timers: true)

• Separate timer for each player
• Each player's timer pauses when they leave the server
• Commands only work in-game for each player
• Ideal for personal challenges and competitions

---

🎨 Display Features

Timer Format

Challenge Timer | ▶ 2d 14h 37m 42s

Status Indicators

• ▶ - Timer is running
• ⏸ - Timer is paused

Time Units

• Days (d) - Only shown when > 0
• Hours (h) - Only shown when > 0 or days > 0
• Minutes (m) - Always shown
• Seconds (s) - Always shown

---

🔧 Advanced Features

Auto-Pause System

• Global Mode: Timer automatically pauses when the last player leaves
• Individual Mode: Each player's timer pauses when they disconnect
• Smart Resume: Use /start to continue exactly where you left off

Data Persistence

• All timer data stored in timer_data.yml
• Survives server crashes and restarts
• Handles pause time calculations across server downtime

Color Customization

Supports both named colors and hex codes:

Named Colors: black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, white

Hex Colors: #FF5733, #00FF00, #1E90FF, etc.

---

📝 Usage Examples

Starting a Challenge

/start
> Challenge Timer started!

Pausing Mid-Challenge

/pause
> Challenge Timer paused!

Resuming After Break

/start
> Challenge Timer resumed!

Resetting for New Challenge

/reset
> Challenge Timer reset!

---

🎯 Use Cases

• Speedrun Challenges: Track completion times for builds, achievements, or custom objectives
• Server Events: Time-limited competitions and challenges
• Personal Goals: Individual progress tracking for long-term projects
• Race Competitions: Multiple players competing with separate timers
• Survival Challenges: Track how long players survive in hardcore mode

---

🛠️ Technical Details

Requirements

• Minecraft Version: 1.19+
• Server Software: Paper, Spigot, or Bukkit
• Java Version: 17+

Permissions

challengetimer.start: true    # Allow starting timers
challengetimer.pause: true    # Allow pausing timers  
challengetimer.reset: true    # Allow resetting timers

File Structure

plugins/
├── ChallengeTimer/
│   ├── config.yml        # Main configuration
│   └── timer_data.yml    # Persistent timer data (auto-generated)
└── ChallengeTimer.jar    # Plugin file

---

🐛 Troubleshooting

Timer Not Displaying

• Check if timer is started with /start
• Verify player has joined after timer start
• Ensure ActionBar isn't being overridden by other plugins

Data Not Persisting

• Check file permissions on timer_data.yml
• Verify server has write access to plugin folder
• Check server logs for save/load errors

Commands Not Working

• Verify correct permission nodes are set
• In individual mode, ensure commands are used by players (not console)
• Check command spelling and syntax

---

📊 Example Timer Displays

Challenge Timer | ▶ 42s                    # Under 1 minute
Challenge Timer | ▶ 15m 30s                # Under 1 hour  
Challenge Timer | ▶ 2h 45m 12s             # Under 1 day
Challenge Timer | ▶ 1d 12h 30m 45s         # Over 1 day
Challenge Timer | ⏸ 5h 23m 17s             # Paused timer

---

🤝 Contributing

Found a bug or have a feature request? Feel free to submit an issue or pull request!

---

Made with ❤️ for the Minecraft community