PlayHours - Server Operation Hours Enforcement
Server-side Forge mod for Minecraft 1.20.1 that enforces configurable server open hours with per-day schedules, automatic warnings, login blocking, and comprehensive admin commands.
🎯 What is PlayHours?
PlayHours gives server administrators complete control over when players can access their server. Set specific hours for each day of the week, create exceptions for holidays, manage whitelists/blacklists, and automatically warn and kick players when the server is closing.
Perfect for:
- 🏫 Educational servers with class schedules
- 👨👩👧👦 Family servers with screen time limits
- 🎮 Event-based servers with specific opening times
- 🔧 Maintenance windows and scheduled downtime
✨ Key Features
🕒 Flexible Schedule System
- Per-day schedules - Different hours for each day of the week
- Midnight-spanning - Support for schedules that cross midnight (e.g., "11:00 PM-2:00 AM")
- Default periods - Set default hours that apply to all days
- Date exceptions - Special open/closed dates for holidays and events
🚫 Access Control
- Login blocking - Players cannot join outside open hours
- Whitelist/Blacklist - Player-specific access control independent of schedule
- Permission-based exemptions - Ops and permitted players can bypass restrictions
- Custom kick messages - Clear, localized messages explaining why access is denied
⚠️ Smart Warning System
- Configurable warnings - Default: 15, 10, 5, and 1 minute before close
- Automatic kick - Players are removed when server closes
- Countdown messages - Real-time updates on remaining time
- Exempt permissions - Allow specific players to stay online
🔧 Force Modes
- NORMAL - Follow configured schedule
- FORCE_OPEN - Server always accessible (maintenance mode off)
- FORCE_CLOSED - Server always closed (maintenance mode)
- Easy toggle - Change modes with simple commands
📢 Dynamic MOTD
- Real-time status - Server list shows if server is open or closed
- Next open/close - Displays when server will open or close next
- Countdown timer - Shows minutes until close when closing soon
- Color-coded - Green for open, red for closed, yellow for closing soon
- Customizable format - Full control over MOTD appearance
🌍 Multi-Language Support
- English - 12-hour AM/PM format
- French - 24-hour format
- Locale-aware - Automatically adapts time formatting
- Extensible - Easy to add new languages via JSON files
🔑 Permission Integration
- LuckPerms - Soft dependency with automatic detection
- Vanilla ops - Fallback to ops.json if LuckPerms not present
- Three permission nodes:
playhours.admin - Full administrative accessplayhours.view - View status and schedulesplayhours.exempt - Bypass schedule restrictions
💻 Comprehensive Commands
Full /hours command tree with intuitive subcommands:
/hours status - Current server status and next open/close/hours force <normal|open|close> - Override schedule/hours reload - Hot-reload configuration/hours set day <day> <period> - Modify day schedules/hours exceptions add/remove - Manage date exceptions/hours lists add/remove - Manage whitelist/blacklist/hours motd enable/disable - Control MOTD display
🚀 Quick Start
Installation
- Download the latest version from CurseForge
- Place
playhours-x.x.x.jar in your server's mods/ folder
- Start the server to generate default configuration
- Edit
config/playhours.toml to your needs
- Use
/hours reload or restart the server
Basic Configuration Example
[general]
timezone = "America/New_York"
[defaults]
periods = ["09:00 AM-06:00 PM"]
[days]
monday = ["09:00 AM-06:00 PM"]
tuesday = ["09:00 AM-06:00 PM"]
wednesday = ["09:00 AM-06:00 PM"]
thursday = ["09:00 AM-06:00 PM"]
friday = ["09:00 AM-06:00 PM"]
saturday = ["02:00 PM-11:59 PM"]
sunday = ["02:00 PM-10:00 PM"]
[warnings]
intervals = [15, 10, 5, 1]
[exceptions]
open_dates = ["2025-12-31 08:00 PM-11:59 PM"]
closed_dates = ["2025-12-25"]
📋 Requirements
- Minecraft: 1.20.1
- Forge: 47.4.10 or higher
- Java: 17 or 23 (recommended: 17 LTS)
- Server-side only - No client mod required
- Dedicated server - Not compatible with single-player or LAN
🎮 Usage Examples
Educational Server
# School hours: Monday-Friday 8 AM - 3 PM
[days]
monday = ["08:00 AM-03:00 PM"]
tuesday = ["08:00 AM-03:00 PM"]
wednesday = ["08:00 AM-03:00 PM"]
thursday = ["08:00 AM-03:00 PM"]
friday = ["08:00 AM-03:00 PM"]
saturday = []
sunday = []
Family Server with Screen Time
# Weekdays: After homework (4-8 PM), Weekends: Afternoon/evening
[days]
monday = ["04:00 PM-08:00 PM"]
tuesday = ["04:00 PM-08:00 PM"]
wednesday = ["04:00 PM-08:00 PM"]
thursday = ["04:00 PM-08:00 PM"]
friday = ["04:00 PM-10:00 PM"]
saturday = ["10:00 AM-10:00 PM"]
sunday = ["10:00 AM-08:00 PM"]
Event Server
# Friday night events only
[days]
friday = ["07:00 PM-11:59 PM"]
[exceptions]
open_dates = ["2025-12-31 08:00 PM-02:00 AM"] # New Year's Eve party
Maintenance Mode
# Close server for maintenance
/hours force close
# Reopen after maintenance
/hours force normal
🛠️ Advanced Features
Timezone Support
Full IANA timezone database support with automatic DST handling:
[general]
timezone = "America/New_York" # or "Europe/Paris", "Asia/Tokyo", etc.
Midnight-Spanning Ranges
Support for time ranges that cross midnight:
[days]
saturday = ["10:00 PM-02:00 AM"] # Saturday 10 PM to Sunday 2 AM
Priority System
Access decisions follow this priority:
- Force Mode (FORCE_OPEN/FORCE_CLOSED)
- Blacklist (always denied)
- Whitelist (always allowed)
- Date Exceptions (special dates)
- Day Schedule (regular hours)
Hot Reload
Change configuration without server restart:
/hours reload
📚 Documentation
For detailed documentation, please visit the GitHub repository:
- Installation Guide - Step-by-step setup
- Configuration Guide - Complete configuration reference
- Commands Reference - All commands with examples
- MOTD Customization - Advanced MOTD formatting
- Permissions System - LuckPerms integration details
- Technical Details - Architecture and implementation
- Changelog - Version history and updates
🐛 Bug Reports & Feature Requests
Found a bug or have a feature request? Please report it on the Gitea repository.
📄 License
All Rights Reserved © 2025 Mr-KayJayDee
🔗 Links
PlayHours - Take control of your server's schedule. Simple to configure, powerful to use.
