c0fd2a2787
- 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.
203 lines
5.8 KiB
Markdown
203 lines
5.8 KiB
Markdown
# 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).*
|