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
428
docs/PERMISSIONS.md
Normal file
428
docs/PERMISSIONS.md
Normal file
@@ -0,0 +1,428 @@
|
||||
# Permissions System
|
||||
|
||||
PlayHours includes a comprehensive permission system with LuckPerms integration and vanilla ops fallback support.
|
||||
|
||||
## 🔑 Permission Nodes
|
||||
|
||||
### Core Permissions
|
||||
|
||||
| Permission | Description | Default Level |
|
||||
|------------|-------------|---------------|
|
||||
| `playhours.admin` | Full administrative access | Ops Level 2+ |
|
||||
| `playhours.view` | Read-only status access | Ops Level 1+ |
|
||||
| `playhours.exempt` | Bypass all schedule restrictions | Ops Level 2+ |
|
||||
|
||||
### Permission Details
|
||||
|
||||
#### `playhours.admin`
|
||||
**Full administrative access including:**
|
||||
- All `/hours` commands
|
||||
- Force mode changes
|
||||
- Configuration modifications
|
||||
- Schedule management
|
||||
- Exception handling
|
||||
- List management
|
||||
- MOTD control
|
||||
|
||||
#### `playhours.view`
|
||||
**Read-only access including:**
|
||||
- `/hours status` command
|
||||
- View current server status
|
||||
- Check schedule information
|
||||
- View force mode status
|
||||
|
||||
#### `playhours.exempt`
|
||||
**Bypass all schedule restrictions:**
|
||||
- Join server when closed
|
||||
- Join during closing threshold
|
||||
- Stay connected during kicks
|
||||
- Override blacklist restrictions
|
||||
|
||||
## 🔌 LuckPerms Integration
|
||||
|
||||
### Automatic Detection
|
||||
|
||||
PlayHours automatically detects and integrates with LuckPerms:
|
||||
|
||||
- **Soft dependency** - Works with or without LuckPerms
|
||||
- **Automatic detection** - Detected at server startup
|
||||
- **Graceful fallback** - Falls back to vanilla ops if LuckPerms unavailable
|
||||
- **No configuration required** - Works out of the box
|
||||
|
||||
### LuckPerms Setup
|
||||
|
||||
#### Basic Permission Setup
|
||||
|
||||
```bash
|
||||
# Grant view permission to all players
|
||||
/lp group default permission set playhours.view true
|
||||
|
||||
# Grant admin permission to admin group
|
||||
/lp group admin permission set playhours.admin true
|
||||
/lp group admin permission set playhours.exempt true
|
||||
|
||||
# Grant exempt permission to specific players
|
||||
/lp user PlayerName permission set playhours.exempt true
|
||||
```
|
||||
|
||||
#### Advanced Permission Setup
|
||||
|
||||
```bash
|
||||
# Create custom groups
|
||||
/lp creategroup moderator
|
||||
/lp creategroup admin
|
||||
|
||||
# Grant permissions to groups
|
||||
/lp group moderator permission set playhours.view true
|
||||
/lp group admin permission set playhours.admin true
|
||||
/lp group admin permission set playhours.exempt true
|
||||
|
||||
# Add players to groups
|
||||
/lp user PlayerName parent add moderator
|
||||
/lp user AdminName parent add admin
|
||||
```
|
||||
|
||||
#### Permission Inheritance
|
||||
|
||||
```bash
|
||||
# Set up permission inheritance
|
||||
/lp group moderator permission set playhours.view true
|
||||
/lp group admin permission set playhours.admin true
|
||||
/lp group admin permission set playhours.exempt true
|
||||
|
||||
# Admin inherits from moderator
|
||||
/lp group admin parent add moderator
|
||||
```
|
||||
|
||||
### LuckPerms Commands
|
||||
|
||||
#### User Management
|
||||
|
||||
```bash
|
||||
# Grant permissions to specific users
|
||||
/lp user PlayerName permission set playhours.view true
|
||||
/lp user PlayerName permission set playhours.admin true
|
||||
/lp user PlayerName permission set playhours.exempt true
|
||||
|
||||
# Remove permissions
|
||||
/lp user PlayerName permission unset playhours.view
|
||||
/lp user PlayerName permission unset playhours.admin
|
||||
/lp user PlayerName permission unset playhours.exempt
|
||||
```
|
||||
|
||||
#### Group Management
|
||||
|
||||
```bash
|
||||
# Grant permissions to groups
|
||||
/lp group default permission set playhours.view true
|
||||
/lp group moderator permission set playhours.view true
|
||||
/lp group admin permission set playhours.admin true
|
||||
/lp group admin permission set playhours.exempt true
|
||||
|
||||
# Remove permissions from groups
|
||||
/lp group default permission unset playhours.view
|
||||
/lp group admin permission unset playhours.admin
|
||||
```
|
||||
|
||||
#### Permission Checking
|
||||
|
||||
```bash
|
||||
# Check user permissions
|
||||
/lp user PlayerName permission check playhours.admin
|
||||
/lp user PlayerName permission check playhours.view
|
||||
/lp user PlayerName permission check playhours.exempt
|
||||
|
||||
# Check group permissions
|
||||
/lp group admin permission check playhours.admin
|
||||
/lp group admin permission check playhours.exempt
|
||||
```
|
||||
|
||||
## 🔄 Vanilla Ops Fallback
|
||||
|
||||
### When LuckPerms is Not Available
|
||||
|
||||
PlayHours automatically falls back to vanilla operator levels:
|
||||
|
||||
- **Level 0** - No access
|
||||
- **Level 1+** - `playhours.view` permission
|
||||
- **Level 2+** - `playhours.admin` and `playhours.exempt` permissions
|
||||
|
||||
### Ops Level Configuration
|
||||
|
||||
```bash
|
||||
# Grant ops level 1 (view access)
|
||||
/op PlayerName 1
|
||||
|
||||
# Grant ops level 2 (admin access)
|
||||
/op PlayerName 2
|
||||
|
||||
# Grant ops level 3 (admin access)
|
||||
/op PlayerName 3
|
||||
|
||||
# Remove ops
|
||||
/deop PlayerName
|
||||
```
|
||||
|
||||
### Ops Level Examples
|
||||
|
||||
```bash
|
||||
# Give view access to a player
|
||||
/op PlayerName 1
|
||||
|
||||
# Give admin access to a player
|
||||
/op PlayerName 2
|
||||
|
||||
# Give admin access to multiple players
|
||||
/op Player1 2
|
||||
/op Player2 2
|
||||
/op Player3 2
|
||||
```
|
||||
|
||||
## ⚡ Performance Considerations
|
||||
|
||||
### Permission Checking
|
||||
|
||||
PlayHours optimizes permission checking for performance:
|
||||
|
||||
- **Cached results** - Permission results are cached
|
||||
- **Timeout protection** - Prevents blocking on permission checks
|
||||
- **Efficient queries** - Minimal database queries
|
||||
- **Fallback handling** - Graceful degradation on errors
|
||||
|
||||
### Timeout Configuration
|
||||
|
||||
```java
|
||||
// Default timeout: 2 seconds
|
||||
public static final int LUCKPERMS_TIMEOUT_SECONDS = 2;
|
||||
```
|
||||
|
||||
### Performance Tips
|
||||
|
||||
1. **Use groups** - Grant permissions to groups rather than individual users
|
||||
2. **Limit exempt players** - Only grant exempt permission to necessary players
|
||||
3. **Cache permissions** - LuckPerms handles caching automatically
|
||||
4. **Monitor performance** - Check server logs for permission-related delays
|
||||
|
||||
## 🔧 Permission Scenarios
|
||||
|
||||
### Basic Server Setup
|
||||
|
||||
**All players can view status:**
|
||||
```bash
|
||||
/lp group default permission set playhours.view true
|
||||
```
|
||||
|
||||
**Admins have full access:**
|
||||
```bash
|
||||
/lp group admin permission set playhours.admin true
|
||||
/lp group admin permission set playhours.exempt true
|
||||
```
|
||||
|
||||
### Moderator Setup
|
||||
|
||||
**Moderators can view but not modify:**
|
||||
```bash
|
||||
/lp group moderator permission set playhours.view true
|
||||
# No admin or exempt permissions
|
||||
```
|
||||
|
||||
**Admins have full control:**
|
||||
```bash
|
||||
/lp group admin permission set playhours.admin true
|
||||
/lp group admin permission set playhours.exempt true
|
||||
```
|
||||
|
||||
### Custom Roles
|
||||
|
||||
**Create custom permission groups:**
|
||||
```bash
|
||||
# Create custom groups
|
||||
/lp creategroup helper
|
||||
/lp creategroup moderator
|
||||
/lp creategroup admin
|
||||
|
||||
# Grant appropriate permissions
|
||||
/lp group helper permission set playhours.view true
|
||||
/lp group moderator permission set playhours.view true
|
||||
/lp group admin permission set playhours.admin true
|
||||
/lp group admin permission set playhours.exempt true
|
||||
```
|
||||
|
||||
### Player-Specific Permissions
|
||||
|
||||
**Grant permissions to specific players:**
|
||||
```bash
|
||||
# Grant view access to specific player
|
||||
/lp user PlayerName permission set playhours.view true
|
||||
|
||||
# Grant admin access to specific player
|
||||
/lp user PlayerName permission set playhours.admin true
|
||||
/lp user PlayerName permission set playhours.exempt true
|
||||
```
|
||||
|
||||
## 🚨 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Permission Denied Errors
|
||||
|
||||
**Error:** `You do not have permission to use this command`
|
||||
|
||||
**Solutions:**
|
||||
1. Check if player has required permission
|
||||
2. Verify LuckPerms is working correctly
|
||||
3. Check if player is in correct group
|
||||
4. Verify permission syntax is correct
|
||||
|
||||
#### LuckPerms Not Working
|
||||
|
||||
**Symptoms:**
|
||||
- Permissions not being recognized
|
||||
- Commands not working
|
||||
- Fallback to vanilla ops
|
||||
|
||||
**Solutions:**
|
||||
1. Check if LuckPerms is loaded
|
||||
2. Verify LuckPerms configuration
|
||||
3. Check server logs for errors
|
||||
4. Restart server if necessary
|
||||
|
||||
#### Permission Inheritance Issues
|
||||
|
||||
**Symptoms:**
|
||||
- Players not inheriting group permissions
|
||||
- Inconsistent permission behavior
|
||||
|
||||
**Solutions:**
|
||||
1. Check group inheritance setup
|
||||
2. Verify parent-child relationships
|
||||
3. Check for conflicting permissions
|
||||
4. Use `/lp user PlayerName permission check` to debug
|
||||
|
||||
### Debug Commands
|
||||
|
||||
#### Check User Permissions
|
||||
|
||||
```bash
|
||||
# Check specific permission
|
||||
/lp user PlayerName permission check playhours.admin
|
||||
|
||||
# Check all permissions
|
||||
/lp user PlayerName permission check
|
||||
|
||||
# Check group permissions
|
||||
/lp group admin permission check playhours.admin
|
||||
```
|
||||
|
||||
#### Debug Permission Issues
|
||||
|
||||
```bash
|
||||
# Check user's groups
|
||||
/lp user PlayerName info
|
||||
|
||||
# Check group inheritance
|
||||
/lp group admin info
|
||||
|
||||
# Check permission inheritance
|
||||
/lp user PlayerName permission check playhours.admin
|
||||
```
|
||||
|
||||
### Log Analysis
|
||||
|
||||
Look for these log messages:
|
||||
|
||||
```
|
||||
[INFO] PlayHours: LuckPerms integration enabled
|
||||
[WARN] PlayHours: LuckPerms not found, using ops fallback
|
||||
[ERROR] PlayHours: Permission check timeout for user PlayerName
|
||||
[DEBUG] PlayHours: Permission check result: true for playhours.admin
|
||||
```
|
||||
|
||||
## 🔄 Permission Updates
|
||||
|
||||
### Hot Reload
|
||||
|
||||
Permissions are checked in real-time:
|
||||
|
||||
- **No restart required** - Changes take effect immediately
|
||||
- **Automatic updates** - LuckPerms changes are detected
|
||||
- **Cached results** - Permission results are cached for performance
|
||||
- **Fallback handling** - Graceful degradation on errors
|
||||
|
||||
### Permission Changes
|
||||
|
||||
```bash
|
||||
# Grant permission (takes effect immediately)
|
||||
/lp user PlayerName permission set playhours.admin true
|
||||
|
||||
# Remove permission (takes effect immediately)
|
||||
/lp user PlayerName permission unset playhours.admin
|
||||
|
||||
# Change group membership (takes effect immediately)
|
||||
/lp user PlayerName parent add admin
|
||||
```
|
||||
|
||||
## 📚 Permission Examples
|
||||
|
||||
### Server Owner Setup
|
||||
|
||||
```bash
|
||||
# Grant full access to server owner
|
||||
/lp user ServerOwner permission set playhours.admin true
|
||||
/lp user ServerOwner permission set playhours.exempt true
|
||||
```
|
||||
|
||||
### Admin Team Setup
|
||||
|
||||
```bash
|
||||
# Create admin group
|
||||
/lp creategroup admin
|
||||
|
||||
# Grant admin permissions
|
||||
/lp group admin permission set playhours.admin true
|
||||
/lp group admin permission set playhours.exempt true
|
||||
|
||||
# Add admins to group
|
||||
/lp user Admin1 parent add admin
|
||||
/lp user Admin2 parent add admin
|
||||
/lp user Admin3 parent add admin
|
||||
```
|
||||
|
||||
### Moderator Setup
|
||||
|
||||
```bash
|
||||
# Create moderator group
|
||||
/lp creategroup moderator
|
||||
|
||||
# Grant view permission
|
||||
/lp group moderator permission set playhours.view true
|
||||
|
||||
# Add moderators to group
|
||||
/lp user Mod1 parent add moderator
|
||||
/lp user Mod2 parent add moderator
|
||||
```
|
||||
|
||||
### Helper Setup
|
||||
|
||||
```bash
|
||||
# Create helper group
|
||||
/lp creategroup helper
|
||||
|
||||
# Grant view permission
|
||||
/lp group helper permission set playhours.view true
|
||||
|
||||
# Add helpers to group
|
||||
/lp user Helper1 parent add helper
|
||||
/lp user Helper2 parent add helper
|
||||
```
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- **[Commands Reference](COMMANDS.md)** - Permission requirements for commands
|
||||
- **[Features Overview](FEATURES.md)** - How permissions affect features
|
||||
- **[Configuration Guide](CONFIGURATION.md)** - Permission-related configuration
|
||||
- **[Usage Examples](EXAMPLES.md)** - Real-world permission scenarios
|
||||
|
||||
---
|
||||
|
||||
*For command-specific permission requirements, see the [Commands Reference](COMMANDS.md).*
|
||||
Reference in New Issue
Block a user