PlayHours

ByMrKayJayDee
Mods

PlayHours is a Forge 1.20.1 server mod that enforces schedules: set per-day open windows, block logins outside hours, warn at 15/10/5/1 min, auto-kick at close, handle holidays, whitelist/blacklist, force modes, LuckPerms.

Description

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

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

🔗 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.