PlayHours/docs/FEATURES.md

# 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).*