PlayHours/docs/INSTALLATION.md

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

[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:

[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)

/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 for detailed setup
2. Check the Commands Reference for available commands
3. Review Features Overview for advanced functionality
4. See Usage Examples for real-world scenarios

---

For detailed configuration options, see the Configuration Guide.