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
467
docs/COMMANDS.md
Normal file
467
docs/COMMANDS.md
Normal file
@@ -0,0 +1,467 @@
|
||||
# Commands Reference
|
||||
|
||||
This guide covers all available commands in PlayHours, their usage, permissions, and examples.
|
||||
|
||||
## 📋 Command Overview
|
||||
|
||||
All PlayHours commands use the `/hours` root command. Permission checks are applied automatically.
|
||||
|
||||
### Permission Requirements
|
||||
|
||||
| Permission | Level | Description |
|
||||
|------------|-------|-------------|
|
||||
| `playhours.view` | Ops ≥1 | Read-only access to status |
|
||||
| `playhours.admin` | Ops ≥2 | Full administrative access |
|
||||
| `playhours.exempt` | Ops ≥2 | Bypass all schedule restrictions |
|
||||
|
||||
## 🔍 Status Commands
|
||||
|
||||
### `/hours status`
|
||||
|
||||
Shows current server status and schedule information.
|
||||
|
||||
**Permission:** `playhours.view` (ops ≥1)
|
||||
|
||||
**Output Example:**
|
||||
```
|
||||
Mode: NORMAL. Server open. Next close: 10:00 PM. Next open: Monday at 9:00 AM.
|
||||
Today's periods: 09:00 AM-06:00 PM, 11:00 PM-01:00 AM
|
||||
```
|
||||
|
||||
**Information Displayed:**
|
||||
- Current force mode
|
||||
- Server open/closed status
|
||||
- Next closing time (if open)
|
||||
- Next opening time (if closed)
|
||||
- Today's schedule periods
|
||||
|
||||
## 🔧 Force Mode Commands
|
||||
|
||||
### `/hours force normal`
|
||||
### `/hours force open`
|
||||
### `/hours force close`
|
||||
|
||||
Override the normal schedule enforcement.
|
||||
|
||||
**Permission:** `playhours.admin` (ops ≥2)
|
||||
|
||||
**Modes:**
|
||||
- `normal` - Follow configured schedule
|
||||
- `open` - Always allow access (24/7)
|
||||
- `close` - Always deny access (maintenance mode)
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
/hours force open # Enable 24/7 access
|
||||
/hours force close # Maintenance mode
|
||||
/hours force normal # Return to normal schedule
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- Force modes override schedule but not blacklist
|
||||
- Exempt players can still join in FORCE_CLOSED mode
|
||||
- Changes take effect immediately
|
||||
|
||||
## 🔄 Configuration Commands
|
||||
|
||||
### `/hours reload`
|
||||
|
||||
Reloads configuration from `config/playhours.toml` without restarting the server.
|
||||
|
||||
**Permission:** `playhours.admin` (ops ≥2)
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/hours reload
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
- Reloads all configuration settings
|
||||
- Rebuilds schedule cache
|
||||
- Reloads message translations
|
||||
- Applies changes immediately
|
||||
|
||||
**When to use:**
|
||||
- After editing `config/playhours.toml`
|
||||
- After changing timezone settings
|
||||
- After modifying schedule configuration
|
||||
|
||||
## ⚙️ Settings Commands
|
||||
|
||||
### `/hours set timezone <timezone>`
|
||||
|
||||
Change the server timezone.
|
||||
|
||||
**Permission:** `playhours.admin` (ops ≥2)
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/hours set timezone America/New_York
|
||||
/hours set timezone Europe/London
|
||||
/hours set timezone Asia/Tokyo
|
||||
```
|
||||
|
||||
**Valid Timezones:**
|
||||
- `America/New_York` (Eastern Time)
|
||||
- `America/Chicago` (Central Time)
|
||||
- `America/Denver` (Mountain Time)
|
||||
- `America/Los_Angeles` (Pacific Time)
|
||||
- `Europe/London` (GMT/BST)
|
||||
- `Europe/Paris` (CET/CEST)
|
||||
- `Asia/Tokyo` (JST)
|
||||
- `Australia/Sydney` (AEST/AEDT)
|
||||
|
||||
### `/hours set threshold <minutes>`
|
||||
|
||||
Set the closing threshold in minutes.
|
||||
|
||||
**Permission:** `playhours.admin` (ops ≥2)
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/hours set threshold 20
|
||||
```
|
||||
|
||||
**Effect:**
|
||||
- Denies new logins X minutes before close
|
||||
- Existing players can stay connected
|
||||
- Exempt players can bypass if configured
|
||||
|
||||
### `/hours set warnings <minutes...>`
|
||||
|
||||
Configure warning broadcast times.
|
||||
|
||||
**Permission:** `playhours.admin` (ops ≥2)
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/hours set warnings 30 15 10 5 1
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
- `15 10 5 1` - Warn at 15, 10, 5, and 1 minutes before close
|
||||
- `30 15 5` - Warn at 30, 15, and 5 minutes before close
|
||||
- `60 30 15 10 5 1` - Extended warning sequence
|
||||
|
||||
### `/hours set countdown <seconds>`
|
||||
|
||||
Set countdown duration before closing.
|
||||
|
||||
**Permission:** `playhours.admin` (ops ≥2)
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/hours set countdown 10
|
||||
```
|
||||
|
||||
**Range:** 0-60 seconds (0 = disabled)
|
||||
|
||||
**Effect:**
|
||||
- Sends "Closing in Xs" messages every second
|
||||
- Only active during the last X seconds before close
|
||||
- Provides final warning to players
|
||||
|
||||
### `/hours set exempt_bypass_schedule <true|false>`
|
||||
### `/hours set exempt_bypass_threshold <true|false>`
|
||||
|
||||
Control exempt player behavior.
|
||||
|
||||
**Permission:** `playhours.admin` (ops ≥2)
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/hours set exempt_bypass_schedule true
|
||||
/hours set exempt_bypass_threshold false
|
||||
```
|
||||
|
||||
**Settings:**
|
||||
- `exempt_bypass_schedule` - Allow exempt players to join when closed
|
||||
- `exempt_bypass_threshold` - Allow exempt players during threshold
|
||||
|
||||
## 📅 Schedule Commands
|
||||
|
||||
### `/hours set default periods add "<time_range>"`
|
||||
### `/hours set default periods clear`
|
||||
|
||||
Manage default schedule periods.
|
||||
|
||||
**Permission:** `playhours.admin` (ops ≥2)
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/hours set default periods add "09:00 AM-06:00 PM"
|
||||
/hours set default periods add "11:00 PM-01:00 AM"
|
||||
/hours set default periods clear
|
||||
```
|
||||
|
||||
**Time Format:** 12-hour AM/PM format with quotes
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
/hours set default periods add "09:00 AM-06:00 PM"
|
||||
/hours set default periods add "10:00 PM-02:00 AM" # Midnight span
|
||||
/hours set default periods clear # Remove all periods
|
||||
```
|
||||
|
||||
### `/hours set day <day> periods add "<time_range>"`
|
||||
### `/hours set day <day> periods clear`
|
||||
|
||||
Manage per-day schedule periods.
|
||||
|
||||
**Permission:** `playhours.admin` (ops ≥2)
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/hours set day mon periods add "09:00 AM-06:00 PM"
|
||||
/hours set day fri periods add "11:00 PM-01:00 AM"
|
||||
/hours set day tue periods clear
|
||||
```
|
||||
|
||||
**Day Names:** `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
/hours set day mon periods add "09:00 AM-06:00 PM"
|
||||
/hours set day fri periods add "11:00 PM-01:00 AM"
|
||||
/hours set day sat periods add "02:00 PM-11:59 PM"
|
||||
/hours set day sun periods clear
|
||||
```
|
||||
|
||||
## 📅 Exception Commands
|
||||
|
||||
### `/hours exceptions add-open "<date_time_range>"`
|
||||
### `/hours exceptions add-closed "<date>"`
|
||||
### `/hours exceptions clear`
|
||||
|
||||
Manage date exceptions.
|
||||
|
||||
**Permission:** `playhours.admin` (ops ≥2)
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/hours exceptions add-open "2025-12-31 08:00 PM-11:59 PM"
|
||||
/hours exceptions add-closed "2025-12-25"
|
||||
/hours exceptions clear
|
||||
```
|
||||
|
||||
**Date Formats:**
|
||||
- **Open dates:** `YYYY-MM-DD hh:mm AM-hh:mm PM`
|
||||
- **Closed dates:** `YYYY-MM-DD`
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
/hours exceptions add-open "2025-12-31 08:00 PM-11:59 PM" # New Year's Eve
|
||||
/hours exceptions add-closed "2025-12-25" # Christmas Day
|
||||
/hours exceptions add-open "2025-07-04 12:00 PM-11:59 PM" # Independence Day
|
||||
/hours exceptions clear # Remove all exceptions
|
||||
```
|
||||
|
||||
## 👥 List Commands
|
||||
|
||||
### `/hours lists whitelist toggle <player>`
|
||||
### `/hours lists blacklist toggle <player>`
|
||||
|
||||
Toggle players in/out of lists.
|
||||
|
||||
**Permission:** `playhours.admin` (ops ≥2)
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/hours lists whitelist toggle PlayerName
|
||||
/hours lists blacklist toggle PlayerName
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
- Automatically enables the list if not already enabled
|
||||
- Case-insensitive player name matching
|
||||
- Toggle: Add if not present, remove if present
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
/hours lists whitelist toggle Steve
|
||||
/hours lists blacklist toggle Griefer123
|
||||
```
|
||||
|
||||
### `/hours lists whitelist enable`
|
||||
### `/hours lists whitelist disable`
|
||||
### `/hours lists blacklist enable`
|
||||
### `/hours lists blacklist disable`
|
||||
|
||||
Enable or disable lists.
|
||||
|
||||
**Permission:** `playhours.admin` (ops ≥2)
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/hours lists whitelist enable
|
||||
/hours lists blacklist disable
|
||||
```
|
||||
|
||||
## 📢 MOTD Commands
|
||||
|
||||
### `/hours motd toggle`
|
||||
|
||||
Enable or disable MOTD schedule display.
|
||||
|
||||
**Permission:** `playhours.admin` (ops ≥2)
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/hours motd toggle
|
||||
```
|
||||
|
||||
**Effect:**
|
||||
- Toggles MOTD feature on/off
|
||||
- Changes take effect immediately
|
||||
- Server list will show/hide schedule information
|
||||
|
||||
### `/hours motd status`
|
||||
|
||||
View current MOTD settings.
|
||||
|
||||
**Permission:** `playhours.admin` (ops ≥2)
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/hours motd status
|
||||
```
|
||||
|
||||
**Output:**
|
||||
- MOTD enabled/disabled status
|
||||
- Current MOTD configuration
|
||||
- Update frequency settings
|
||||
|
||||
## 💬 Message Commands
|
||||
|
||||
### `/hours messages reload`
|
||||
|
||||
Reload message translations.
|
||||
|
||||
**Permission:** `playhours.admin` (ops ≥2)
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/hours messages reload
|
||||
```
|
||||
|
||||
**Effect:**
|
||||
- Reloads message translations from language files
|
||||
- Applies any config overrides
|
||||
- Updates all player-facing messages
|
||||
|
||||
## 🔧 Advanced Commands
|
||||
|
||||
### Command Chaining
|
||||
|
||||
Some commands support chaining for efficiency:
|
||||
|
||||
```
|
||||
/hours set day mon periods add "09:00 AM-06:00 PM"
|
||||
/hours set day tue periods add "09:00 AM-06:00 PM"
|
||||
/hours set day wed periods add "09:00 AM-06:00 PM"
|
||||
```
|
||||
|
||||
### Batch Operations
|
||||
|
||||
Use multiple commands for complex setups:
|
||||
|
||||
```
|
||||
/hours set default periods clear
|
||||
/hours set day mon periods add "09:00 AM-06:00 PM"
|
||||
/hours set day fri periods add "11:00 PM-01:00 AM"
|
||||
/hours exceptions add-closed "2025-12-25"
|
||||
```
|
||||
|
||||
## 🚨 Error Handling
|
||||
|
||||
### Common Errors
|
||||
|
||||
**Permission Denied:**
|
||||
```
|
||||
You do not have permission to use this command
|
||||
```
|
||||
**Solution:** Check your permission level or LuckPerms configuration
|
||||
|
||||
**Invalid Time Format:**
|
||||
```
|
||||
Invalid time range. Use: hh:mm AM-hh:mm PM
|
||||
```
|
||||
**Solution:** Use proper 12-hour AM/PM format with quotes
|
||||
|
||||
**Config Not Ready:**
|
||||
```
|
||||
PlayHours config not ready yet. Try again in a moment.
|
||||
```
|
||||
**Solution:** Wait for server startup to complete
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
1. **Check permissions:** Ensure you have the required permission level
|
||||
2. **Verify format:** Use correct time format and quotes
|
||||
3. **Wait for startup:** Allow server to fully initialize
|
||||
4. **Check logs:** Look for error messages in server logs
|
||||
|
||||
## 📚 Command Examples
|
||||
|
||||
### Basic Server Setup
|
||||
|
||||
```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 hours
|
||||
/hours set day sat periods add "02:00 PM-11:59 PM"
|
||||
/hours set day sun periods add "02:00 PM-10:00 PM"
|
||||
|
||||
# Configure warnings
|
||||
/hours set warnings 15 10 5 1
|
||||
/hours set countdown 5
|
||||
```
|
||||
|
||||
### Holiday Configuration
|
||||
|
||||
```bash
|
||||
# Add holiday closures
|
||||
/hours exceptions add-closed "2025-12-25"
|
||||
/hours exceptions add-closed "2026-01-01"
|
||||
|
||||
# Add special event hours
|
||||
/hours exceptions add-open "2025-12-31 08:00 PM-11:59 PM"
|
||||
```
|
||||
|
||||
### Maintenance Mode
|
||||
|
||||
```bash
|
||||
# Enter maintenance mode
|
||||
/hours force close
|
||||
|
||||
# Exit maintenance mode
|
||||
/hours force normal
|
||||
```
|
||||
|
||||
### Player Management
|
||||
|
||||
```bash
|
||||
# Add players to whitelist
|
||||
/hours lists whitelist toggle PlayerName
|
||||
|
||||
# Add players to blacklist
|
||||
/hours lists blacklist toggle Griefer123
|
||||
|
||||
# Enable whitelist
|
||||
/hours lists whitelist enable
|
||||
```
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- **[Configuration Guide](CONFIGURATION.md)** - File-based configuration
|
||||
- **[Features Overview](FEATURES.md)** - How features work
|
||||
- **[Permissions System](PERMISSIONS.md)** - Permission details
|
||||
- **[Usage Examples](EXAMPLES.md)** - Real-world scenarios
|
||||
|
||||
---
|
||||
|
||||
*For configuration file options, see the [Configuration Guide](CONFIGURATION.md).*
|
||||
Reference in New Issue
Block a user