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 access
  • playhours.view - View status and schedules
  • playhours.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

1. Download the latest version from CurseForge
2. Place playhours-x.x.x.jar in your server's mods/ folder
3. Start the server to generate default configuration
4. Edit config/playhours.toml to your needs
5. 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:

1. Force Mode (FORCE_OPEN/FORCE_CLOSED)
2. Blacklist (always denied)
3. Whitelist (always allowed)
4. Date Exceptions (special dates)
5. 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

• Source Code: https://gitea.kamisama.ovh/kayjaydee/PlayHours
• Documentation: Full Documentation
• Issues: Bug Reports & Features

PlayHours - Take control of your server's schedule. Simple to configure, powerful to use.