PlayHours/docs/FEATURES.md

Features Overview

This guide provides detailed explanations of all PlayHours features, how they work, and their interactions.

🕒 Schedule Enforcement

Core Functionality

PlayHours enforces server operating hours based on configurable schedules with support for:

• Per-day schedules - Different hours for each day of the week
• Multiple periods per day - Support for split schedules (e.g., morning and evening)
• Midnight-spanning periods - Ranges that cross midnight (e.g., 10:00 PM-02:00 AM)
• Default schedule - Fallback schedule for days without specific configuration
• Timezone awareness - All times are calculated in the configured timezone

Schedule Logic

The schedule enforcement follows this priority order:

1. Force Mode - Override all schedule logic
2. Blacklist - Always deny listed players
3. Whitelist - Always allow listed players (if enabled)
4. Date Exceptions - Special open/closed dates
5. Daily Schedule - Per-day time periods

Time Format

• Input Format: 12-hour AM/PM format ("09:00 AM-06:00 PM")
• Display Format: Automatically adapts to locale (English: 12-hour, French: 24-hour)
• Midnight Spanning: Detected when end time is before start time
• Validation: All time ranges are validated for correctness

Examples

# Standard business hours
[defaults]
periods = ["09:00 AM-06:00 PM"]

# Weekend with midnight span
[days]
friday = ["06:00 PM-02:00 AM"]    # Friday 6 PM to Saturday 2 AM
saturday = ["02:00 PM-02:00 AM"]  # Saturday 2 PM to Sunday 2 AM

🚫 Login Control

Access Denial

PlayHours prevents players from joining the server when:

• Server is closed according to schedule
• Within closing threshold (configurable minutes before close)
• Player is blacklisted (regardless of schedule)
• Whitelist is enabled and player is not whitelisted

Login Process

1. Player attempts to join
2. Permission check - Exempt players may bypass restrictions
3. Schedule check - Is server currently open?
4. Threshold check - Is within closing threshold?
5. List check - Is player whitelisted/blacklisted?
6. Decision - Allow or deny with appropriate message

Exempt Players

Players with exempt permission can:

• Bypass schedule - Join even when server is closed
• Bypass threshold - Join during closing threshold
• Override blacklist - Join even if blacklisted
• Stay connected - Not kicked at closing time (configurable)

Messages

Players receive clear messages when denied access:

• Server closed: "Server closed. Next open: Monday at 9:00 AM."
• Closing threshold: "Server closing soon. Next open: Monday at 9:00 AM."
• Blacklisted: "Access denied." (no schedule information)

⚠️ Warnings & Auto-Kick

Warning System

PlayHours broadcasts warnings before server closure:

• Configurable timing - Default: 15, 10, 5, 1 minutes before close
• Broadcast to all players - Server-wide announcements
• Include next open time - Inform players when server reopens
• Localized messages - Support for multiple languages

Countdown System

Second-by-second countdown before closing:

• Configurable duration - 0-60 seconds (0 = disabled)
• Final warning - "Closing in 5s" messages
• Precise timing - Exact second when server closes

Auto-Kick System

Automatic player removal at closing time:

• Kick non-exempt players - Remove players without exempt permission
• Optional exempt kick - Configurable whether to kick exempt players
• Clear messages - Inform players why they were kicked
• Next open time - Tell players when they can return

Warning Examples

[Server] Server closing in 15 minutes at 10:00 PM.
[Server] Server closing in 10 minutes at 10:00 PM.
[Server] Server closing in 5 minutes at 10:00 PM.
[Server] Server closing in 1 minute at 10:00 PM.
[Server] Closing in 5s
[Server] Closing in 4s
[Server] Closing in 3s
[Server] Closing in 2s
[Server] Closing in 1s

🔧 Force Modes

NORMAL Mode

Default operational mode:

• Follows schedule - Enforces configured hours
• Respects exceptions - Honors date exceptions
• Applies lists - Whitelist/blacklist in effect
• Standard behavior - All features work as configured

FORCE_OPEN Mode

Always allow access:

• 24/7 access - Server always open
• Override schedule - Ignores all schedule restrictions
• Respect blacklist - Blacklisted players still denied
• Exempt players - Can still join (redundant but allowed)
• Use case - Special events, maintenance overrides

FORCE_CLOSED Mode

Always deny access:

• Maintenance mode - Server always closed
• Override schedule - Ignores all schedule restrictions
• Exempt players - Can still join (unless kick_exempt=true)
• Use case - Server maintenance, emergency closures

Force Mode Examples

/hours force open    # Enable 24/7 access
/hours force close   # Enter maintenance mode
/hours force normal  # Return to normal schedule

👥 Whitelist/Blacklist

Whitelist System

When enabled, only listed players can join:

• Always allowed - Listed players can join anytime
• Always denied - Non-listed players denied even during open hours
• Independent of schedule - Works regardless of server hours
• Case insensitive - Player names matched regardless of case

Blacklist System

When enabled, listed players are always denied:

• Always denied - Listed players cannot join anytime
• Override schedule - Denied even during open hours
• Independent of schedule - Works regardless of server hours
• Exempt override - Exempt players can still join

List Management

• Toggle players - Add/remove players from lists
• Auto-enable - Lists automatically enabled when players added
• Independent operation - Whitelist and blacklist work separately
• Permission override - Exempt players can bypass blacklist

Examples

# Add to whitelist
/hours lists whitelist toggle PlayerName

# Add to blacklist
/hours lists blacklist toggle Griefer123

# Enable whitelist
/hours lists whitelist enable

📅 Date Exceptions

Closed Dates

Full day closures:

• Format: YYYY-MM-DD (e.g., 2025-12-25)
• Effect: Server closed all day regardless of schedule
• Use cases: Holidays, maintenance days, special events

Open Dates

Special open windows:

• Format: YYYY-MM-DD hh:mm AM-hh:mm PM (e.g., 2025-12-31 08:00 PM-11:59 PM)
• Effect: Server open during specified time regardless of schedule
• Use cases: Special events, extended hours, one-off openings

Exception Priority

Exceptions take precedence over normal schedule:

1. Closed exceptions - Always deny access
2. Open exceptions - Always allow access
3. Normal schedule - Follow configured hours

Examples

[exceptions]
# Holiday closures
closed_dates = ["2025-12-25", "2026-01-01"]

# Special event windows
open_dates = [
    "2025-12-31 08:00 PM-11:59 PM",  # New Year's Eve
    "2025-07-04 12:00 PM-11:59 PM"   # Independence Day
]

🌍 Multi-Language Support

Supported Languages

• English (en_us) - 12-hour AM/PM format
• French (fr_fr) - 24-hour format

Smart Time Formatting

Time display automatically adapts to locale:

• English: "06:00 PM" (12-hour format)
• French: "18:00" (24-hour format)

Message Localization

All player-facing messages are localized:

• Access denied messages
• Warning broadcasts
• Kick messages
• Status displays
• MOTD content

Locale Configuration

[general]
message_locale = "en_us"  # or "fr_fr"

Custom Messages

Override default messages with custom text:

[messages]
kick = "Le serveur est fermé ! Revenez %openday% à %opentime%."
warn = "⚠️ ATTENTION: Server will close in %minutes% minute%s% at %closetime%."

🔑 Permission System

Permission Nodes

• playhours.admin - Full administrative access
• playhours.view - Read-only status access
• playhours.exempt - Bypass all schedule restrictions

LuckPerms Integration

Soft dependency on LuckPerms:

• Automatic detection - Works with or without LuckPerms
• Permission checking - Uses LuckPerms when available
• Fallback system - Falls back to vanilla ops when LuckPerms unavailable
• Timeout protection - Prevents blocking on permission checks

Vanilla Ops Fallback

When LuckPerms is not available:

• Level 1+ - Can use /hours status
• Level 2+ - Full admin access and exemption

Permission Examples

# LuckPerms commands
/lp group default permission set playhours.view true
/lp group admin permission set playhours.admin true
/lp group admin permission set playhours.exempt true

# Vanilla ops
/op PlayerName  # Level 2 for admin access

📢 MOTD System

Dynamic Server List

The MOTD (Message of the Day) displays real-time schedule information:

• Server status - Open/Closed with colors
• Next open time - When server will open next
• Next close time - When server will close next
• Countdown timer - Minutes until close
• Force mode indicators - FORCE_OPEN/FORCE_CLOSED status

MOTD Features

• Automatic updates - Refreshes every 60 seconds (configurable)
• Color support - Minecraft color codes for status indication
• Custom formatting - Flexible format strings with placeholders
• Multi-language - Localized content based on server locale
• Performance optimized - Efficient updates to minimize server load

MOTD Configuration

[motd]
show_status = true                    # Display Open/Closed status
show_next_open = true                 # Show next opening time
show_next_close = true                # Show next closing time
use_colors = true                     # Enable colored MOTD
open_color = "green"                  # Color for "open" status
closed_color = "red"                  # Color for "closed" status
update_delay_seconds = 60             # Update frequency

MOTD Examples

When Open:

🟢 Open | Closes at 10:00 PM

When Closed:

🔴 Closed | Opens Monday at 9:00 AM

With Countdown:

🟢 Open | Closing in 15 min | Closes at 10:00 PM

🔄 Hot Reload

Configuration Reload

Apply changes without server restart:

• Command: /hours reload
• Effect: Reloads all configuration settings
• Immediate: Changes take effect instantly
• Safe: No data loss or server interruption

What Gets Reloaded

• Schedule configuration - All time periods and exceptions
• Message translations - Language files and custom messages
• MOTD settings - Display configuration
• Permission settings - Exemption and bypass settings

When to Use

• After editing config file - Apply configuration changes
• After changing timezone - Update time calculations
• After modifying schedule - Apply new hours
• After updating messages - Apply translation changes

🚨 Error Handling

Graceful Degradation

PlayHours handles errors gracefully:

• Config not ready - Defers checks until configuration is loaded
• Permission timeouts - Falls back to vanilla ops on timeout
• Invalid configuration - Uses safe defaults until fixed
• Network issues - Continues operation with cached data

Error Recovery

• Automatic retry - Retries failed operations
• Fallback systems - Uses alternative methods when primary fails
• Logging - Comprehensive error logging for debugging
• User feedback - Clear error messages for administrators

🔧 Advanced Features

Midnight Spanning

Support for time ranges that cross midnight:

• Automatic detection - When end time is before start time
• Proper calculation - Handles day boundaries correctly
• Schedule logic - Includes spanning ranges in both days
• Next open/close - Calculates correctly across day boundaries

Timezone Handling

Robust timezone support:

• IANA identifiers - Standard timezone names
• Automatic DST - Handles daylight saving time changes
• Local time display - Times shown in server timezone
• Consistent calculations - All time operations use same timezone

Performance Optimization

Efficient operation:

• Cached calculations - Schedule data cached for performance
• Minimal updates - MOTD updates only when necessary
• Efficient checks - Optimized permission and schedule checks
• Resource management - Minimal server resource usage

📚 Related Documentation

• Configuration Guide - Detailed configuration options
• Commands Reference - All available commands
• MOTD System - MOTD configuration and customization
• Permissions System - Permission details
• Usage Examples - Real-world scenarios

---

For specific configuration options, see the Configuration Guide.