Files

Mr¤KayJayDee c0fd2a2787 feat(docs): complete PlayHours mod implementation with comprehensive documentation

- Add complete PlayHours mod source code with all features:
  * Schedule enforcement with per-day schedules and midnight-spanning support
  * Login control with configurable thresholds and exemptions
  * Warnings and auto-kick system with countdown functionality
  * Force modes (NORMAL/FORCE_OPEN/FORCE_CLOSED) for maintenance
  * Whitelist/blacklist system for player access control
  * Date exceptions for holidays and special events
  * Multi-language support (English/French) with smart time formatting
  * LuckPerms integration with vanilla ops fallback
  * Dynamic MOTD system with real-time schedule display
  * Comprehensive command system with permission integration
  * TOML configuration with hot-reload support

- Add comprehensive documentation suite:
  * Installation guide with step-by-step setup instructions
  * Complete configuration reference with all options
  * Commands reference with usage examples
  * Features overview with detailed explanations
  * MOTD system configuration and customization guide
  * Permissions system documentation with LuckPerms integration
  * Technical details covering architecture and limitations
  * Usage examples with real-world scenarios
  * Changelog with version history

- Add resource files:
  * Language files (en_us.json, fr_fr.json) with localized messages
  * Mod metadata (mods.toml) with proper Forge configuration
  * Resource pack metadata (pack.mcmeta)

- Update build configuration:
  * Gradle build system with proper dependencies
  * Project properties and version management
  * Development environment setup

- Restructure documentation:
  * Replace old README.txt with new comprehensive README.md
  * Create modular documentation structure in docs/ directory
  * Add cross-references and navigation between documents
  * Include quick start guide and common use cases

This commit represents the complete v1.0.0 release of PlayHours, a production-ready server operation hours enforcement mod for Minecraft Forge 1.20.1.

2025-10-23 23:28:20 +02:00

12 KiB

Raw Permalink Blame History

Usage Examples

This guide provides real-world examples and scenarios for configuring PlayHours in different server environments.

🏢 Business Server

Standard Business Hours

Scenario: A business server that operates Monday-Friday, 9 AM to 6 PM.

Configuration:

[general]
timezone = "America/New_York"
force_mode = "NORMAL"
closing_threshold_minutes = 15
deny_login_during_threshold = true
kick_exempt = false
warning_minutes = [15, 10, 5, 1]
countdown_seconds = 5
exempt_bypass_schedule = true
exempt_bypass_threshold = true
message_locale = "en_us"
motd_enabled = true

[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 = []
sunday = []

Commands:

# Set timezone
/hours set timezone America/New_York

# Configure default hours
/hours set default periods add "09:00 AM-06:00 PM"

# Set weekend to closed
/hours set day sat periods clear
/hours set day sun periods clear

# Configure warnings
/hours set warnings 15 10 5 1
/hours set countdown 5

🎮 Gaming Server

Extended Gaming Hours

Scenario: A gaming server with extended hours, including late-night sessions.

Configuration:

[general]
timezone = "Europe/London"
force_mode = "NORMAL"
closing_threshold_minutes = 30
deny_login_during_threshold = true
kick_exempt = false
warning_minutes = [30, 15, 10, 5, 1]
countdown_seconds = 10
exempt_bypass_schedule = true
exempt_bypass_threshold = true
message_locale = "en_us"
motd_enabled = true

[defaults]
periods = ["06:00 PM-11:59 PM"]

[days]
monday = ["06:00 PM-11:59 PM"]
tuesday = ["06:00 PM-11:59 PM"]
wednesday = ["06:00 PM-11:59 PM"]
thursday = ["06:00 PM-11:59 PM"]
friday = ["06:00 PM-02:00 AM"]  # Extended Friday night
saturday = ["02:00 PM-02:00 AM"]  # All day Saturday
sunday = ["02:00 PM-11:59 PM"]

Commands:

# Set timezone
/hours set timezone Europe/London

# Configure default hours
/hours set default periods add "06:00 PM-11:59 PM"

# Set extended Friday night
/hours set day fri periods add "06:00 PM-02:00 AM"

# Set all-day Saturday
/hours set day sat periods add "02:00 PM-02:00 AM"

# Configure extended warnings
/hours set warnings 30 15 10 5 1
/hours set countdown 10

🎓 Educational Server

School Hours with Breaks

Scenario: An educational server that operates during school hours with breaks.

Configuration:

[general]
timezone = "America/Chicago"
force_mode = "NORMAL"
closing_threshold_minutes = 10
deny_login_during_threshold = true
kick_exempt = false
warning_minutes = [10, 5, 1]
countdown_seconds = 3
exempt_bypass_schedule = true
exempt_bypass_threshold = true
message_locale = "en_us"
motd_enabled = true

[defaults]
periods = ["08:00 AM-03:00 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 = []

[exceptions]
closed_dates = [
    "2025-12-23",  # Winter break
    "2025-12-24",
    "2025-12-25",
    "2025-12-26",
    "2025-12-27",
    "2025-12-28",
    "2025-12-29",
    "2025-12-30",
    "2025-12-31",
    "2026-01-01",
    "2026-01-02",
    "2026-01-03"
]

Commands:

# Set timezone
/hours set timezone America/Chicago

# Configure school hours
/hours set default periods add "08:00 AM-03:00 PM"

# Add winter break closures
/hours exceptions add-closed "2025-12-23"
/hours exceptions add-closed "2025-12-24"
/hours exceptions add-closed "2025-12-25"
# ... (continue for all break days)

# Configure warnings
/hours set warnings 10 5 1
/hours set countdown 3

🏥 Healthcare Server

24/7 with Maintenance Windows

Scenario: A healthcare server that operates 24/7 with scheduled maintenance windows.

Configuration:

[general]
timezone = "America/Los_Angeles"
force_mode = "NORMAL"
closing_threshold_minutes = 0
deny_login_during_threshold = false
kick_exempt = false
warning_minutes = [60, 30, 15, 10, 5, 1]
countdown_seconds = 10
exempt_bypass_schedule = true
exempt_bypass_threshold = true
message_locale = "en_us"
motd_enabled = true

[defaults]
periods = ["12:00 AM-11:59 PM"]  # 24/7

[days]
monday = ["12:00 AM-11:59 PM"]
tuesday = ["12:00 AM-11:59 PM"]
wednesday = ["12:00 AM-11:59 PM"]
thursday = ["12:00 AM-11:59 PM"]
friday = ["12:00 AM-11:59 PM"]
saturday = ["12:00 AM-11:59 PM"]
sunday = ["12:00 AM-11:59 PM"]

[exceptions]
closed_dates = [
    "2025-01-01",  # New Year's Day
    "2025-07-04",  # Independence Day
    "2025-12-25"   # Christmas Day
]

# Maintenance windows (closed for maintenance)
open_dates = [
    "2025-01-15 02:00 AM-04:00 AM",  # Monthly maintenance
    "2025-02-15 02:00 AM-04:00 AM",
    "2025-03-15 02:00 AM-04:00 AM"
]

Commands:

# Set timezone
/hours set timezone America/Los_Angeles

# Configure 24/7 operation
/hours set default periods add "12:00 AM-11:59 PM"

# Add holiday closures
/hours exceptions add-closed "2025-01-01"
/hours exceptions add-closed "2025-07-04"
/hours exceptions add-closed "2025-12-25"

# Add maintenance windows
/hours exceptions add-open "2025-01-15 02:00 AM-04:00 AM"

# Configure extended warnings
/hours set warnings 60 30 15 10 5 1
/hours set countdown 10

🎉 Event Server

Special Event Hours

Scenario: A server that hosts special events with extended hours.

Configuration:

[general]
timezone = "Europe/Paris"
force_mode = "NORMAL"
closing_threshold_minutes = 20
deny_login_during_threshold = true
kick_exempt = false
warning_minutes = [20, 15, 10, 5, 1]
countdown_seconds = 5
exempt_bypass_schedule = true
exempt_bypass_threshold = true
message_locale = "fr_fr"
motd_enabled = true

[defaults]
periods = ["07:00 PM-11:00 PM"]

[days]
monday = ["07:00 PM-11:00 PM"]
tuesday = ["07:00 PM-11:00 PM"]
wednesday = ["07:00 PM-11:00 PM"]
thursday = ["07:00 PM-11:00 PM"]
friday = ["07:00 PM-11:00 PM"]
saturday = ["07:00 PM-11:00 PM"]
sunday = ["07:00 PM-11:00 PM"]

[exceptions]
open_dates = [
    "2025-12-31 08:00 PM-11:59 PM",  # New Year's Eve
    "2025-07-14 08:00 PM-11:59 PM",  # Bastille Day
    "2025-12-25 08:00 PM-11:59 PM"   # Christmas Eve
]

Commands:

# Set timezone
/hours set timezone Europe/Paris

# Configure regular hours
/hours set default periods add "07:00 PM-11:00 PM"

# Add special event hours
/hours exceptions add-open "2025-12-31 08:00 PM-11:59 PM"
/hours exceptions add-open "2025-07-14 08:00 PM-11:59 PM"
/hours exceptions add-open "2025-12-25 08:00 PM-11:59 PM"

# Configure warnings
/hours set warnings 20 15 10 5 1
/hours set countdown 5

🛡️ Whitelist Server

Invitation-Only Server

Scenario: A private server with whitelist-only access.

Configuration:

[general]
timezone = "America/New_York"
force_mode = "NORMAL"
closing_threshold_minutes = 0
deny_login_during_threshold = true
kick_exempt = false
warning_minutes = [15, 10, 5, 1]
countdown_seconds = 5
exempt_bypass_schedule = true
exempt_bypass_threshold = true
message_locale = "en_us"
motd_enabled = true

[defaults]
periods = ["06:00 PM-10:00 PM"]

[days]
monday = ["06:00 PM-10:00 PM"]
tuesday = ["06:00 PM-10:00 PM"]
wednesday = ["06:00 PM-10:00 PM"]
thursday = ["06:00 PM-10:00 PM"]
friday = ["06:00 PM-10:00 PM"]
saturday = ["02:00 PM-10:00 PM"]
sunday = ["02:00 PM-10:00 PM"]

[lists]
whitelist_enabled = true
whitelist = ["Player1", "Player2", "Player3"]
blacklist_enabled = false
blacklist = []

Commands:

# Set timezone
/hours set timezone America/New_York

# Configure regular hours
/hours set default periods add "06:00 PM-10:00 PM"

# Set weekend hours
/hours set day sat periods add "02:00 PM-10:00 PM"
/hours set day sun periods add "02:00 PM-10:00 PM"

# Add players to whitelist
/hours lists whitelist toggle Player1
/hours lists whitelist toggle Player2
/hours lists whitelist toggle Player3

# Enable whitelist
/hours lists whitelist enable

🚫 Blacklist Server

Problem Player Management

Scenario: A server that needs to block specific players.

Configuration:

[general]
timezone = "America/Chicago"
force_mode = "NORMAL"
closing_threshold_minutes = 0
deny_login_during_threshold = true
kick_exempt = false
warning_minutes = [15, 10, 5, 1]
countdown_seconds = 5
exempt_bypass_schedule = true
exempt_bypass_threshold = true
message_locale = "en_us"
motd_enabled = true

[defaults]
periods = ["12:00 PM-11:59 PM"]

[days]
monday = ["12:00 PM-11:59 PM"]
tuesday = ["12:00 PM-11:59 PM"]
wednesday = ["12:00 PM-11:59 PM"]
thursday = ["12:00 PM-11:59 PM"]
friday = ["12:00 PM-11:59 PM"]
saturday = ["12:00 PM-11:59 PM"]
sunday = ["12:00 PM-11:59 PM"]

[lists]
whitelist_enabled = false
whitelist = []
blacklist_enabled = true
blacklist = ["Griefer123", "Spammer456", "Troll789"]

Commands:

# Set timezone
/hours set timezone America/Chicago

# Configure hours
/hours set default periods add "12:00 PM-11:59 PM"

# Add players to blacklist
/hours lists blacklist toggle Griefer123
/hours lists blacklist toggle Spammer456
/hours lists blacklist toggle Troll789

# Enable blacklist
/hours lists blacklist enable

🔧 Maintenance Mode

Server Maintenance

Scenario: A server that needs to enter maintenance mode.

Commands:

# Enter maintenance mode
/hours force close

# Check status
/hours status

# Exit maintenance mode
/hours force normal

Configuration:

[general]
force_mode = "FORCE_CLOSED"  # Maintenance mode

🌍 Multi-Language Server

International Server

Scenario: A server with international players using different languages.

Configuration:

[general]
timezone = "UTC"
force_mode = "NORMAL"
closing_threshold_minutes = 15
deny_login_during_threshold = true
kick_exempt = false
warning_minutes = [15, 10, 5, 1]
countdown_seconds = 5
exempt_bypass_schedule = true
exempt_bypass_threshold = true
message_locale = "en_us"  # or "fr_fr"
motd_enabled = true

[defaults]
periods = ["12:00 PM-11:59 PM"]

[days]
monday = ["12:00 PM-11:59 PM"]
tuesday = ["12:00 PM-11:59 PM"]
wednesday = ["12:00 PM-11:59 PM"]
thursday = ["12:00 PM-11:59 PM"]
friday = ["12:00 PM-11:59 PM"]
saturday = ["12:00 PM-11:59 PM"]
sunday = ["12:00 PM-11:59 PM"]

Commands:

# Set UTC timezone
/hours set timezone UTC

# Configure 24/7 operation
/hours set default periods add "12:00 PM-11:59 PM"

# Set language
/hours set message_locale en_us  # or fr_fr

📢 MOTD Examples

Basic MOTD

Configuration:

[motd]
show_status = true
show_next_open = true
show_next_close = true
use_colors = true
open_color = "green"
closed_color = "red"

Display:

🟢 Open | Closes at 10:00 PM

Custom MOTD

Configuration:

[motd]
custom_format = "Status: %status% - Next: %openday% at %opentime%"
use_colors = true
open_color = "green"
closed_color = "red"

Display:

Status: Closed - Next: Monday at 9:00 AM

Branded MOTD

Configuration:

[motd]
custom_lines = [
    "🎮 My Game Server",
    "Status: %status%",
    "Next open: %openday% at %opentime%"
]
use_colors = true
open_color = "green"
closed_color = "red"

Display:

🎮 My Game Server
Status: Open
Next open: Monday at 9:00 AM

🔄 Configuration Updates

Hot Reload Examples

After editing config file:

/hours reload

After changing timezone:

/hours set timezone Europe/London
/hours reload

After modifying schedule:

/hours set day mon periods add "09:00 AM-06:00 PM"
/hours reload

🚨 Emergency Scenarios

Server Emergency

Immediate closure:

/hours force close

Emergency maintenance:

/hours force close
# Perform maintenance
/hours force normal

Player Issues

Block problematic player:

/hours lists blacklist toggle ProblemPlayer

Temporary maintenance:

/hours force close
# Fix issues
/hours force normal

Configuration Guide - Detailed configuration options
Commands Reference - All available commands
Features Overview - How features work
MOTD System - MOTD configuration

For more configuration options, see the Configuration Guide.

12 KiB Raw Permalink Blame History

Usage Examples

🏢 Business Server

Standard Business Hours

🎮 Gaming Server

Extended Gaming Hours

🎓 Educational Server

School Hours with Breaks

🏥 Healthcare Server

24/7 with Maintenance Windows

🎉 Event Server

Special Event Hours

🛡️ Whitelist Server

Invitation-Only Server

🚫 Blacklist Server

Problem Player Management

🔧 Maintenance Mode

Server Maintenance

🌍 Multi-Language Server

International Server

📢 MOTD Examples

Basic MOTD

Custom MOTD

Branded MOTD

🔄 Configuration Updates

Hot Reload Examples

🚨 Emergency Scenarios

Server Emergency

Player Issues

📚 Related Documentation

12 KiB

Raw Permalink Blame History