# Installation Guide

This guide covers the installation and initial setup of the PlayHours mod for Minecraft Forge servers.

## 📋 Requirements

### System Requirements
- **Java:** 17 or 23 (recommended: 17 LTS)
- **Minecraft:** 1.20.1
- **Forge:** 47.4.10 or higher
- **Server:** Dedicated server (not single-player)

### Mod Requirements
- **Server-side only** - No client mod required
- **Forge mod loader** - Not compatible with Fabric or other loaders
- **Dedicated server** - Single-player mode not supported

## 🚀 Installation Steps

### 1. Download the Mod

1. Navigate to the `build/libs/` directory in this repository
2. Download `playhours-1.0.0.jar`
3. Verify the file size and integrity

### 2. Install on Server

1. **Stop your Minecraft server** if it's running
2. Navigate to your server's root directory
3. Locate the `mods/` folder (create it if it doesn't exist)
4. Copy `playhours-1.0.0.jar` into the `mods/` folder
5. Ensure no other version of PlayHours is present

### 3. First Startup

1. **Start your server** with the Forge mod loader
2. **Wait for complete startup** - the mod will generate default configuration
3. **Check the logs** for any error messages
4. **Verify installation** by looking for:
   ```
   [INFO] PlayHours loading... (modId=playhours)
   [INFO] PlayHours common setup initialized
   ```

### 4. Configuration Setup

1. **Locate the config file:** `config/playhours.toml`
2. **Edit the configuration** to match your server's needs
3. **Use `/hours reload`** to apply changes without restart
4. **Or restart the server** to load new configuration

## ⚙️ Initial Configuration

### Basic Setup Example

```toml
[general]
timezone = "America/New_York"
force_mode = "NORMAL"
closing_threshold_minutes = 0
deny_login_during_threshold = true
kick_exempt = false
warning_minutes = [15, 10, 5, 1]
countdown_seconds = 5
exempt_bypass_schedule = true
exempt_bypass_threshold = true
message_locale = "en_us"
motd_enabled = true

[defaults]
periods = ["09:00 AM-06:00 PM"]

[days]
monday = ["09:00 AM-06:00 PM"]
tuesday = ["09:00 AM-06:00 PM"]
wednesday = ["09:00 AM-06:00 PM"]
thursday = ["09:00 AM-06:00 PM"]
friday = ["09:00 AM-06:00 PM"]
saturday = []
sunday = []
```

### Timezone Configuration

Set your server's timezone using IANA timezone identifiers:

```toml
[general]
timezone = "America/New_York"    # Eastern Time
timezone = "Europe/London"       # GMT/BST
timezone = "Asia/Tokyo"          # JST
timezone = "Australia/Sydney"    # AEST/AEDT
```

## 🔧 Post-Installation

### 1. Test Basic Functionality

1. **Check status:** `/hours status`
2. **Test force modes:** `/hours force open` then `/hours force normal`
3. **Verify permissions:** Ensure you have `playhours.admin` permission

### 2. Configure Permissions

#### With LuckPerms (Recommended)
```bash
/lp group default permission set playhours.view true
/lp group admin permission set playhours.admin true
/lp group admin permission set playhours.exempt true
```

#### With Vanilla Ops
- **Level 1+:** Can use `/hours status`
- **Level 2+:** Full admin access and exemption

### 3. Set Up Schedule

1. **Configure default hours** in the `[defaults]` section
2. **Set per-day overrides** in the `[days]` section
3. **Add exceptions** for holidays and special events
4. **Test the schedule** by checking status at different times

## 🚨 Troubleshooting

### Common Issues

#### Mod Not Loading
- **Check Forge version:** Must be 47.4.10 or higher
- **Check Java version:** Must be Java 17 or 23
- **Check server logs** for error messages
- **Verify file integrity:** Re-download if corrupted

#### Configuration Errors
- **Check TOML syntax:** Use a TOML validator
- **Check timezone format:** Must be valid IANA identifier
- **Check time format:** Must use 12-hour AM/PM format
- **Use `/hours reload`** to test configuration

#### Permission Issues
- **Check LuckPerms integration:** Ensure LuckPerms is loaded first
- **Check ops levels:** Verify operator permissions
- **Check permission nodes:** Use correct permission names

### Log Analysis

Look for these log messages:

```
[INFO] PlayHours loading... (modId=playhours)           # Successful loading
[ERROR] PlayHours config error: ...                     # Configuration issue
[WARN] PlayHours: LuckPerms not found, using ops fallback # Permission fallback
[DEBUG] PlayHours: Config not ready yet                 # Normal during startup
```

### Getting Help

1. **Check the logs** for specific error messages
2. **Verify configuration** using `/hours status`
3. **Test with minimal config** to isolate issues
4. **Check Forge compatibility** and Java version

## 🔄 Updates

### Updating the Mod

1. **Stop the server**
2. **Backup your configuration** (`config/playhours.toml`)
3. **Remove the old mod file** from `mods/` folder
4. **Install the new version**
5. **Start the server**
6. **Verify configuration** is still valid
7. **Use `/hours reload`** if needed

### Configuration Migration

- **Automatic:** Most configuration changes are backward compatible
- **Manual:** Check changelog for breaking changes
- **Backup:** Always backup your config before updates

## ✅ Verification

After installation, verify everything works:

1. **Server starts without errors**
2. **`/hours status` command works**
3. **Configuration file is generated**
4. **Schedule enforcement works** (test with force modes)
5. **Permissions work correctly**
6. **MOTD updates** (if enabled)

## 📚 Next Steps

After successful installation:

1. **Read the [Configuration Guide](CONFIGURATION.md)** for detailed setup
2. **Check the [Commands Reference](COMMANDS.md)** for available commands
3. **Review [Features Overview](FEATURES.md)** for advanced functionality
4. **See [Usage Examples](EXAMPLES.md)** for real-world scenarios

---

*For detailed configuration options, see the [Configuration Guide](CONFIGURATION.md).*