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