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
434
docs/MOTD.md
Normal file
434
docs/MOTD.md
Normal file
@@ -0,0 +1,434 @@
|
||||
# MOTD System
|
||||
|
||||
The MOTD (Message of the Day) system displays real-time schedule information in the Minecraft server list, providing players with up-to-date information about server availability.
|
||||
|
||||
## 🎯 Overview
|
||||
|
||||
The MOTD system automatically updates the server list description to show:
|
||||
|
||||
- **Server status** (Open/Closed) with color coding
|
||||
- **Next opening time** when the server is closed
|
||||
- **Next closing time** when the server is open
|
||||
- **Countdown timer** when closing soon
|
||||
- **Force mode indicators** for maintenance or special modes
|
||||
- **Custom information** with flexible formatting
|
||||
|
||||
## ⚙️ Basic Configuration
|
||||
|
||||
### Enabling MOTD
|
||||
|
||||
```toml
|
||||
[general]
|
||||
motd_enabled = true # Enable MOTD feature
|
||||
```
|
||||
|
||||
### Basic Display Settings
|
||||
|
||||
```toml
|
||||
[motd]
|
||||
show_status = true # Display Open/Closed status
|
||||
show_next_open = true # Show next opening time when closed
|
||||
show_next_close = true # Show next closing time when open
|
||||
show_schedule_times = false # Show detailed schedule summary
|
||||
show_on_second_line = true # Place info on second MOTD line
|
||||
separator = " | " # Separator between elements
|
||||
```
|
||||
|
||||
## 🎨 Visual Configuration
|
||||
|
||||
### Colors
|
||||
|
||||
```toml
|
||||
[motd]
|
||||
use_colors = true # Enable colored MOTD
|
||||
open_color = "green" # Color for "open" status
|
||||
closed_color = "red" # Color for "closed" status
|
||||
info_color = "gray" # Color for informational text
|
||||
```
|
||||
|
||||
### Supported Colors
|
||||
|
||||
| Color | Code | Description |
|
||||
|-------|------|-------------|
|
||||
| `black` | `§0` | Black text |
|
||||
| `dark_blue` | `§1` | Dark blue text |
|
||||
| `dark_green` | `§2` | Dark green text |
|
||||
| `dark_aqua` | `§3` | Dark aqua text |
|
||||
| `dark_red` | `§4` | Dark red text |
|
||||
| `dark_purple` | `§5` | Dark purple text |
|
||||
| `gold` | `§6` | Gold text |
|
||||
| `gray` | `§7` | Gray text |
|
||||
| `dark_gray` | `§8` | Dark gray text |
|
||||
| `blue` | `§9` | Blue text |
|
||||
| `green` | `§a` | Green text |
|
||||
| `aqua` | `§b` | Aqua text |
|
||||
| `red` | `§c` | Red text |
|
||||
| `light_purple` | `§d` | Light purple text |
|
||||
| `yellow` | `§e` | Yellow text |
|
||||
| `white` | `§f` | White text |
|
||||
|
||||
### Color Examples
|
||||
|
||||
```toml
|
||||
[motd]
|
||||
use_colors = true
|
||||
open_color = "green" # Green for open status
|
||||
closed_color = "red" # Red for closed status
|
||||
info_color = "yellow" # Yellow for informational text
|
||||
```
|
||||
|
||||
## 📝 Custom Formatting
|
||||
|
||||
### Custom Format String
|
||||
|
||||
```toml
|
||||
[motd]
|
||||
custom_format = "Status: %status% - Next: %openday% at %opentime%"
|
||||
```
|
||||
|
||||
### Available Placeholders
|
||||
|
||||
| Placeholder | Description | Example |
|
||||
|-------------|-------------|---------|
|
||||
| `%status%` | Current server status | "Open" or "Closed" |
|
||||
| `%openday%` | Day when server next opens | "Monday" |
|
||||
| `%opentime%` | Time when server next opens | "9:00 AM" |
|
||||
| `%closetime%` | Time when server closes | "10:00 PM" |
|
||||
| `%nextopen%` | Combined next open info | "Monday at 9:00 AM" |
|
||||
| `%nextclose%` | Next close time | "10:00 PM" |
|
||||
| `%minutes%` | Minutes until close (countdown) | "15" |
|
||||
| `%mode%` | Current force mode | "NORMAL", "FORCE_OPEN", or "FORCE_CLOSED" |
|
||||
| `%isopen%` | Whether server is currently open | "yes" or "no" |
|
||||
|
||||
### Format Examples
|
||||
|
||||
```toml
|
||||
# Simple status
|
||||
custom_format = "Status: %status%"
|
||||
|
||||
# Detailed information
|
||||
custom_format = "Status: %status% - Next: %openday% at %opentime%"
|
||||
|
||||
# With countdown
|
||||
custom_format = "Status: %status% - Closing in %minutes% min"
|
||||
```
|
||||
|
||||
## 📋 Custom Lines
|
||||
|
||||
### Static Text Lines
|
||||
|
||||
```toml
|
||||
[motd]
|
||||
custom_lines = [
|
||||
"🎮 My Game Server",
|
||||
"Status: %status%",
|
||||
"Next open: %openday% at %opentime%"
|
||||
]
|
||||
```
|
||||
|
||||
### Multi-Line Examples
|
||||
|
||||
```toml
|
||||
# Server branding with status
|
||||
custom_lines = [
|
||||
"🌟 Welcome to My Server!",
|
||||
"Status: %status% | Next: %openday%"
|
||||
]
|
||||
|
||||
# Detailed information
|
||||
custom_lines = [
|
||||
"🎮 My Game Server",
|
||||
"Status: %status%",
|
||||
"Next open: %openday% at %opentime%",
|
||||
"Visit: example.com"
|
||||
]
|
||||
```
|
||||
|
||||
## 🔄 Advanced Features
|
||||
|
||||
### Force Mode Display
|
||||
|
||||
```toml
|
||||
[motd]
|
||||
show_force_mode = true # Show FORCE_OPEN/FORCE_CLOSED indicator
|
||||
```
|
||||
|
||||
**Display Examples:**
|
||||
- `⚠️ Always Open` (FORCE_OPEN mode)
|
||||
- `⚠️ Maintenance` (FORCE_CLOSED mode)
|
||||
|
||||
### Countdown Display
|
||||
|
||||
```toml
|
||||
[motd]
|
||||
show_countdown = true # Show countdown when closing soon
|
||||
countdown_threshold_minutes = 30 # Minutes before close to show countdown
|
||||
```
|
||||
|
||||
**Display Examples:**
|
||||
- `Closing in 15 min` (when within threshold)
|
||||
- `Closing in 5 min` (when very close)
|
||||
|
||||
### Update Frequency
|
||||
|
||||
```toml
|
||||
[motd]
|
||||
update_delay_seconds = 60 # Delay between MOTD updates (1-600)
|
||||
```
|
||||
|
||||
**Update Intervals:**
|
||||
- **Fast (10-30 seconds)** - Near real-time updates
|
||||
- **Default (60 seconds)** - Good balance of accuracy and performance
|
||||
- **Slow (120+ seconds)** - Reduced server load
|
||||
|
||||
## 🎭 MOTD Examples
|
||||
|
||||
### Example 1: Default 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:**
|
||||
```
|
||||
[Your Server Name]
|
||||
🟢 Open | Closes at 10:00 PM
|
||||
```
|
||||
|
||||
### Example 2: Custom Format
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
### Example 3: Custom Lines
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
### Example 4: Force Mode Display
|
||||
|
||||
**Configuration:**
|
||||
```toml
|
||||
[motd]
|
||||
show_force_mode = true
|
||||
show_status = true
|
||||
use_colors = true
|
||||
```
|
||||
|
||||
**Display (FORCE_OPEN):**
|
||||
```
|
||||
⚠️ Always Open | Open
|
||||
```
|
||||
|
||||
**Display (FORCE_CLOSED):**
|
||||
```
|
||||
⚠️ Maintenance | Closed
|
||||
```
|
||||
|
||||
### Example 5: Countdown Display
|
||||
|
||||
**Configuration:**
|
||||
```toml
|
||||
[motd]
|
||||
show_countdown = true
|
||||
countdown_threshold_minutes = 30
|
||||
show_status = true
|
||||
show_next_close = true
|
||||
```
|
||||
|
||||
**Display:**
|
||||
```
|
||||
🟢 Open | Closing in 15 min | Closes at 10:00 PM
|
||||
```
|
||||
|
||||
## 🔧 Performance Optimization
|
||||
|
||||
### Update Frequency Guidelines
|
||||
|
||||
| Server Size | Recommended Interval | Reason |
|
||||
|-------------|---------------------|---------|
|
||||
| Small (10-50 players) | 10-30 seconds | Near real-time updates |
|
||||
| Medium (50-150 players) | 30-60 seconds | Good balance |
|
||||
| Large (150+ players) | 60-120 seconds | Reduce server load |
|
||||
| Very Large (300+ players) | 120-300 seconds | Minimal impact |
|
||||
|
||||
### Configuration Examples
|
||||
|
||||
**High-Traffic Server:**
|
||||
```toml
|
||||
[motd]
|
||||
update_delay_seconds = 120 # Update every 2 minutes
|
||||
```
|
||||
|
||||
**Real-Time Updates:**
|
||||
```toml
|
||||
[motd]
|
||||
update_delay_seconds = 10 # Update every 10 seconds
|
||||
```
|
||||
|
||||
**Minimal Impact:**
|
||||
```toml
|
||||
[motd]
|
||||
update_delay_seconds = 300 # Update every 5 minutes
|
||||
```
|
||||
|
||||
## 🚫 Minecraft Limitations
|
||||
|
||||
### Hard Limits
|
||||
|
||||
The MOTD display in Minecraft has strict limitations:
|
||||
|
||||
- **Maximum 2 lines** - Only 2 lines are displayed in the server list
|
||||
- **Character limit** - ~59 characters per line
|
||||
- **Total limit** - ~118 characters across both lines
|
||||
- **Color codes count** - Color codes count toward character limit
|
||||
|
||||
### What Gets Truncated
|
||||
|
||||
- **Lines beyond 2nd** - Automatically removed
|
||||
- **Lines exceeding 59 characters** - Automatically truncated
|
||||
- **Long placeholder values** - May cause truncation
|
||||
|
||||
### Best Practices
|
||||
|
||||
1. **Keep it concise** - Use short, informative text
|
||||
2. **Test in-game** - Verify MOTD displays correctly
|
||||
3. **Use abbreviations** - "Mon" instead of "Monday"
|
||||
4. **Avoid redundancy** - Don't repeat information
|
||||
5. **Consider timezone** - Times can vary in length
|
||||
|
||||
### Good MOTD Examples
|
||||
|
||||
**Concise and Informative:**
|
||||
```
|
||||
Open | Next: Monday at 09:00 AM
|
||||
```
|
||||
(~41 characters - well under limit)
|
||||
|
||||
**With Status:**
|
||||
```
|
||||
Status: Open | Closing at 11:59 PM
|
||||
```
|
||||
(~39 characters per line)
|
||||
|
||||
**With Countdown:**
|
||||
```
|
||||
Open | Closing in 15 min | Next: Mon
|
||||
```
|
||||
(~35 characters per line)
|
||||
|
||||
## 🌍 Multi-Language Support
|
||||
|
||||
### Language-Specific Formatting
|
||||
|
||||
The MOTD system automatically adapts to the configured locale:
|
||||
|
||||
**English (en_us):**
|
||||
- Time format: 12-hour AM/PM (`09:00 AM`)
|
||||
- Day names: Full names (`Monday`)
|
||||
|
||||
**French (fr_fr):**
|
||||
- Time format: 24-hour (`18:00`)
|
||||
- Day names: French names (`Lundi`)
|
||||
|
||||
### Locale Configuration
|
||||
|
||||
```toml
|
||||
[general]
|
||||
message_locale = "en_us" # or "fr_fr"
|
||||
```
|
||||
|
||||
### Localized Examples
|
||||
|
||||
**English MOTD:**
|
||||
```
|
||||
🟢 Open | Closes at 10:00 PM
|
||||
```
|
||||
|
||||
**French MOTD:**
|
||||
```
|
||||
🟢 Ouvert | Ferme à 22:00
|
||||
```
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**MOTD Not Updating:**
|
||||
- Check if `motd_enabled = true`
|
||||
- Verify update frequency settings
|
||||
- Check server logs for errors
|
||||
|
||||
**Truncated Display:**
|
||||
- Reduce text length
|
||||
- Use abbreviations
|
||||
- Test in-game to verify
|
||||
|
||||
**Color Issues:**
|
||||
- Verify color names are correct
|
||||
- Check for invalid color codes
|
||||
- Test with `use_colors = false`
|
||||
|
||||
### Debug Commands
|
||||
|
||||
```bash
|
||||
/hours motd status # View current MOTD settings
|
||||
/hours motd toggle # Toggle MOTD on/off
|
||||
/hours reload # Reload configuration
|
||||
```
|
||||
|
||||
### Log Messages
|
||||
|
||||
Look for these log messages:
|
||||
|
||||
```
|
||||
[INFO] MOTD updated: Status: Open | Closes at 10:00 PM
|
||||
[WARN] MOTD truncated: Line exceeds 59 characters
|
||||
[ERROR] MOTD error: Invalid color code
|
||||
```
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- **[Configuration Guide](CONFIGURATION.md)** - MOTD configuration options
|
||||
- **[Commands Reference](COMMANDS.md)** - MOTD commands
|
||||
- **[Features Overview](FEATURES.md)** - MOTD feature details
|
||||
- **[Usage Examples](EXAMPLES.md)** - Real-world MOTD scenarios
|
||||
|
||||
---
|
||||
|
||||
*For configuration file options, see the [Configuration Guide](CONFIGURATION.md).*
|
||||
Reference in New Issue
Block a user