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.
This commit is contained in:
Mr¤KayJayDee
612
docs/EXAMPLES.md
Normal file
612
docs/EXAMPLES.md
Normal file
@@ -0,0 +1,612 @@
|
||||
# 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:**
|
||||
```toml
|
||||
[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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```toml
|
||||
[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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```toml
|
||||
[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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```toml
|
||||
[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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```toml
|
||||
[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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```toml
|
||||
[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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```toml
|
||||
[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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# Enter maintenance mode
|
||||
/hours force close
|
||||
|
||||
# Check status
|
||||
/hours status
|
||||
|
||||
# Exit maintenance mode
|
||||
/hours force normal
|
||||
```
|
||||
|
||||
**Configuration:**
|
||||
```toml
|
||||
[general]
|
||||
force_mode = "FORCE_CLOSED" # Maintenance mode
|
||||
```
|
||||
|
||||
## 🌍 Multi-Language Server
|
||||
|
||||
### International Server
|
||||
|
||||
**Scenario:** A server with international players using different languages.
|
||||
|
||||
**Configuration:**
|
||||
```toml
|
||||
[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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```toml
|
||||
[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:**
|
||||
```toml
|
||||
[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:**
|
||||
```toml
|
||||
[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:**
|
||||
```bash
|
||||
/hours reload
|
||||
```
|
||||
|
||||
**After changing timezone:**
|
||||
```bash
|
||||
/hours set timezone Europe/London
|
||||
/hours reload
|
||||
```
|
||||
|
||||
**After modifying schedule:**
|
||||
```bash
|
||||
/hours set day mon periods add "09:00 AM-06:00 PM"
|
||||
/hours reload
|
||||
```
|
||||
|
||||
## 🚨 Emergency Scenarios
|
||||
|
||||
### Server Emergency
|
||||
|
||||
**Immediate closure:**
|
||||
```bash
|
||||
/hours force close
|
||||
```
|
||||
|
||||
**Emergency maintenance:**
|
||||
```bash
|
||||
/hours force close
|
||||
# Perform maintenance
|
||||
/hours force normal
|
||||
```
|
||||
|
||||
### Player Issues
|
||||
|
||||
**Block problematic player:**
|
||||
```bash
|
||||
/hours lists blacklist toggle ProblemPlayer
|
||||
```
|
||||
|
||||
**Temporary maintenance:**
|
||||
```bash
|
||||
/hours force close
|
||||
# Fix issues
|
||||
/hours force normal
|
||||
```
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- **[Configuration Guide](CONFIGURATION.md)** - Detailed configuration options
|
||||
- **[Commands Reference](COMMANDS.md)** - All available commands
|
||||
- **[Features Overview](FEATURES.md)** - How features work
|
||||
- **[MOTD System](MOTD.md)** - MOTD configuration
|
||||
|
||||
---
|
||||
|
||||
*For more configuration options, see the [Configuration Guide](CONFIGURATION.md).*
|
||||
Reference in New Issue
Block a user