kayjaydee/PlayHours
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

feat(docs): complete PlayHours mod implementation with comprehensive documentation

Browse Source 
- 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
2025-10-23 23:28:20 +02:00
parent 58919ced40
commit c0fd2a2787
63 changed files with 6974 additions and 265 deletions
Download Patch File Download Diff File Expand all files Collapse all files

453
docs/FEATURES.md Normal file
View File

@@ -0,0 +1,453 @@
# Features Overview
This guide provides detailed explanations of all PlayHours features, how they work, and their interactions.
## 🕒 Schedule Enforcement
### Core Functionality
PlayHours enforces server operating hours based on configurable schedules with support for:
- **Per-day schedules** - Different hours for each day of the week
- **Multiple periods per day** - Support for split schedules (e.g., morning and evening)
- **Midnight-spanning periods** - Ranges that cross midnight (e.g., 10:00 PM-02:00 AM)
- **Default schedule** - Fallback schedule for days without specific configuration
- **Timezone awareness** - All times are calculated in the configured timezone
### Schedule Logic
The schedule enforcement follows this priority order:
1. **Force Mode** - Override all schedule logic
2. **Blacklist** - Always deny listed players
3. **Whitelist** - Always allow listed players (if enabled)
4. **Date Exceptions** - Special open/closed dates
5. **Daily Schedule** - Per-day time periods
### Time Format
- **Input Format:** 12-hour AM/PM format (`"09:00 AM-06:00 PM"`)
- **Display Format:** Automatically adapts to locale (English: 12-hour, French: 24-hour)
- **Midnight Spanning:** Detected when end time is before start time
- **Validation:** All time ranges are validated for correctness
### Examples
```toml
# Standard business hours
[defaults]
periods = ["09:00 AM-06:00 PM"]
# Weekend with midnight span
[days]
friday = ["06:00 PM-02:00 AM"] # Friday 6 PM to Saturday 2 AM
saturday = ["02:00 PM-02:00 AM"] # Saturday 2 PM to Sunday 2 AM
```
## 🚫 Login Control
### Access Denial
PlayHours prevents players from joining the server when:
- **Server is closed** according to schedule
- **Within closing threshold** (configurable minutes before close)
- **Player is blacklisted** (regardless of schedule)
- **Whitelist is enabled** and player is not whitelisted
### Login Process
1. **Player attempts to join**
2. **Permission check** - Exempt players may bypass restrictions
3. **Schedule check** - Is server currently open?
4. **Threshold check** - Is within closing threshold?
5. **List check** - Is player whitelisted/blacklisted?
6. **Decision** - Allow or deny with appropriate message
### Exempt Players
Players with exempt permission can:
- **Bypass schedule** - Join even when server is closed
- **Bypass threshold** - Join during closing threshold
- **Override blacklist** - Join even if blacklisted
- **Stay connected** - Not kicked at closing time (configurable)
### Messages
Players receive clear messages when denied access:
- **Server closed:** "Server closed. Next open: Monday at 9:00 AM."
- **Closing threshold:** "Server closing soon. Next open: Monday at 9:00 AM."
- **Blacklisted:** "Access denied." (no schedule information)
## ⚠️ Warnings & Auto-Kick
### Warning System
PlayHours broadcasts warnings before server closure:
- **Configurable timing** - Default: 15, 10, 5, 1 minutes before close
- **Broadcast to all players** - Server-wide announcements
- **Include next open time** - Inform players when server reopens
- **Localized messages** - Support for multiple languages
### Countdown System
Second-by-second countdown before closing:
- **Configurable duration** - 0-60 seconds (0 = disabled)
- **Final warning** - "Closing in 5s" messages
- **Precise timing** - Exact second when server closes
### Auto-Kick System
Automatic player removal at closing time:
- **Kick non-exempt players** - Remove players without exempt permission
- **Optional exempt kick** - Configurable whether to kick exempt players
- **Clear messages** - Inform players why they were kicked
- **Next open time** - Tell players when they can return
### Warning Examples
```
[Server] Server closing in 15 minutes at 10:00 PM.
[Server] Server closing in 10 minutes at 10:00 PM.
[Server] Server closing in 5 minutes at 10:00 PM.
[Server] Server closing in 1 minute at 10:00 PM.
[Server] Closing in 5s
[Server] Closing in 4s
[Server] Closing in 3s
[Server] Closing in 2s
[Server] Closing in 1s
```
## 🔧 Force Modes
### NORMAL Mode
Default operational mode:
- **Follows schedule** - Enforces configured hours
- **Respects exceptions** - Honors date exceptions
- **Applies lists** - Whitelist/blacklist in effect
- **Standard behavior** - All features work as configured
### FORCE_OPEN Mode
Always allow access:
- **24/7 access** - Server always open
- **Override schedule** - Ignores all schedule restrictions
- **Respect blacklist** - Blacklisted players still denied
- **Exempt players** - Can still join (redundant but allowed)
- **Use case** - Special events, maintenance overrides
### FORCE_CLOSED Mode
Always deny access:
- **Maintenance mode** - Server always closed
- **Override schedule** - Ignores all schedule restrictions
- **Exempt players** - Can still join (unless kick_exempt=true)
- **Use case** - Server maintenance, emergency closures
### Force Mode Examples
```bash
/hours force open # Enable 24/7 access
/hours force close # Enter maintenance mode
/hours force normal # Return to normal schedule
```
## 👥 Whitelist/Blacklist
### Whitelist System
When enabled, only listed players can join:
- **Always allowed** - Listed players can join anytime
- **Always denied** - Non-listed players denied even during open hours
- **Independent of schedule** - Works regardless of server hours
- **Case insensitive** - Player names matched regardless of case
### Blacklist System
When enabled, listed players are always denied:
- **Always denied** - Listed players cannot join anytime
- **Override schedule** - Denied even during open hours
- **Independent of schedule** - Works regardless of server hours
- **Exempt override** - Exempt players can still join
### List Management
- **Toggle players** - Add/remove players from lists
- **Auto-enable** - Lists automatically enabled when players added
- **Independent operation** - Whitelist and blacklist work separately
- **Permission override** - Exempt players can bypass blacklist
### Examples
```bash
# Add to whitelist
/hours lists whitelist toggle PlayerName
# Add to blacklist
/hours lists blacklist toggle Griefer123
# Enable whitelist
/hours lists whitelist enable
```
## 📅 Date Exceptions
### Closed Dates
Full day closures:
- **Format:** `YYYY-MM-DD` (e.g., `2025-12-25`)
- **Effect:** Server closed all day regardless of schedule
- **Use cases:** Holidays, maintenance days, special events
### Open Dates
Special open windows:
- **Format:** `YYYY-MM-DD hh:mm AM-hh:mm PM` (e.g., `2025-12-31 08:00 PM-11:59 PM`)
- **Effect:** Server open during specified time regardless of schedule
- **Use cases:** Special events, extended hours, one-off openings
### Exception Priority
Exceptions take precedence over normal schedule:
1. **Closed exceptions** - Always deny access
2. **Open exceptions** - Always allow access
3. **Normal schedule** - Follow configured hours
### Examples
```toml
[exceptions]
# Holiday closures
closed_dates = ["2025-12-25", "2026-01-01"]
# Special event windows
open_dates = [
"2025-12-31 08:00 PM-11:59 PM", # New Year's Eve
"2025-07-04 12:00 PM-11:59 PM" # Independence Day
]
```
## 🌍 Multi-Language Support
### Supported Languages
- **English (en_us)** - 12-hour AM/PM format
- **French (fr_fr)** - 24-hour format
### Smart Time Formatting
Time display automatically adapts to locale:
- **English:** "06:00 PM" (12-hour format)
- **French:** "18:00" (24-hour format)
### Message Localization
All player-facing messages are localized:
- **Access denied messages**
- **Warning broadcasts**
- **Kick messages**
- **Status displays**
- **MOTD content**
### Locale Configuration
```toml
[general]
message_locale = "en_us" # or "fr_fr"
```
### Custom Messages
Override default messages with custom text:
```toml
[messages]
kick = "Le serveur est fermé ! Revenez %openday% à %opentime%."
warn = "⚠️ ATTENTION: Server will close in %minutes% minute%s% at %closetime%."
```
## 🔑 Permission System
### Permission Nodes
- **`playhours.admin`** - Full administrative access
- **`playhours.view`** - Read-only status access
- **`playhours.exempt`** - Bypass all schedule restrictions
### LuckPerms Integration
Soft dependency on LuckPerms:
- **Automatic detection** - Works with or without LuckPerms
- **Permission checking** - Uses LuckPerms when available
- **Fallback system** - Falls back to vanilla ops when LuckPerms unavailable
- **Timeout protection** - Prevents blocking on permission checks
### Vanilla Ops Fallback
When LuckPerms is not available:
- **Level 1+** - Can use `/hours status`
- **Level 2+** - Full admin access and exemption
### Permission Examples
```bash
# LuckPerms commands
/lp group default permission set playhours.view true
/lp group admin permission set playhours.admin true
/lp group admin permission set playhours.exempt true
# Vanilla ops
/op PlayerName # Level 2 for admin access
```
## 📢 MOTD System
### Dynamic Server List
The MOTD (Message of the Day) displays real-time schedule information:
- **Server status** - Open/Closed with colors
- **Next open time** - When server will open next
- **Next close time** - When server will close next
- **Countdown timer** - Minutes until close
- **Force mode indicators** - FORCE_OPEN/FORCE_CLOSED status
### MOTD Features
- **Automatic updates** - Refreshes every 60 seconds (configurable)
- **Color support** - Minecraft color codes for status indication
- **Custom formatting** - Flexible format strings with placeholders
- **Multi-language** - Localized content based on server locale
- **Performance optimized** - Efficient updates to minimize server load
### MOTD Configuration
```toml
[motd]
show_status = true # Display Open/Closed status
show_next_open = true # Show next opening time
show_next_close = true # Show next closing time
use_colors = true # Enable colored MOTD
open_color = "green" # Color for "open" status
closed_color = "red" # Color for "closed" status
update_delay_seconds = 60 # Update frequency
```
### MOTD Examples
**When Open:**
```
🟢 Open | Closes at 10:00 PM
```
**When Closed:**
```
🔴 Closed | Opens Monday at 9:00 AM
```
**With Countdown:**
```
🟢 Open | Closing in 15 min | Closes at 10:00 PM
```
## 🔄 Hot Reload
### Configuration Reload
Apply changes without server restart:
- **Command:** `/hours reload`
- **Effect:** Reloads all configuration settings
- **Immediate:** Changes take effect instantly
- **Safe:** No data loss or server interruption
### What Gets Reloaded
- **Schedule configuration** - All time periods and exceptions
- **Message translations** - Language files and custom messages
- **MOTD settings** - Display configuration
- **Permission settings** - Exemption and bypass settings
### When to Use
- **After editing config file** - Apply configuration changes
- **After changing timezone** - Update time calculations
- **After modifying schedule** - Apply new hours
- **After updating messages** - Apply translation changes
## 🚨 Error Handling
### Graceful Degradation
PlayHours handles errors gracefully:
- **Config not ready** - Defers checks until configuration is loaded
- **Permission timeouts** - Falls back to vanilla ops on timeout
- **Invalid configuration** - Uses safe defaults until fixed
- **Network issues** - Continues operation with cached data
### Error Recovery
- **Automatic retry** - Retries failed operations
- **Fallback systems** - Uses alternative methods when primary fails
- **Logging** - Comprehensive error logging for debugging
- **User feedback** - Clear error messages for administrators
## 🔧 Advanced Features
### Midnight Spanning
Support for time ranges that cross midnight:
- **Automatic detection** - When end time is before start time
- **Proper calculation** - Handles day boundaries correctly
- **Schedule logic** - Includes spanning ranges in both days
- **Next open/close** - Calculates correctly across day boundaries
### Timezone Handling
Robust timezone support:
- **IANA identifiers** - Standard timezone names
- **Automatic DST** - Handles daylight saving time changes
- **Local time display** - Times shown in server timezone
- **Consistent calculations** - All time operations use same timezone
### Performance Optimization
Efficient operation:
- **Cached calculations** - Schedule data cached for performance
- **Minimal updates** - MOTD updates only when necessary
- **Efficient checks** - Optimized permission and schedule checks
- **Resource management** - Minimal server resource usage
## 📚 Related Documentation
- **[Configuration Guide](CONFIGURATION.md)** - Detailed configuration options
- **[Commands Reference](COMMANDS.md)** - All available commands
- **[MOTD System](MOTD.md)** - MOTD configuration and customization
- **[Permissions System](PERMISSIONS.md)** - Permission details
- **[Usage Examples](EXAMPLES.md)** - Real-world scenarios
---
*For specific configuration options, see the [Configuration Guide](CONFIGURATION.md).*