c0fd2a2787
- 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.
613 lines
12 KiB
Markdown
613 lines
12 KiB
Markdown
# 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).*
|