feat(docs): complete PlayHours mod implementation with comprehensive documentation
- 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.
This commit is contained in:
Mr¤KayJayDee
202
docs/INSTALLATION.md
Normal file
202
docs/INSTALLATION.md
Normal file
@@ -0,0 +1,202 @@
|
||||
# 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).*
|
||||
Reference in New Issue
Block a user