PlayHours/docs/PERMISSIONS.md

# 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).*