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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

/lp group default permission set playhours.view true

Admins have full access:

/lp group admin permission set playhours.admin true
/lp group admin permission set playhours.exempt true

Moderator Setup

Moderators can view but not modify:

/lp group moderator permission set playhours.view true
# No admin or exempt permissions

Admins have full control:

/lp group admin permission set playhours.admin true
/lp group admin permission set playhours.exempt true

Custom Roles

Create custom permission groups:

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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 - Permission requirements for commands
• Features Overview - How permissions affect features
• Configuration Guide - Permission-related configuration
• Usage Examples - Real-world permission scenarios

---

For command-specific permission requirements, see the Commands Reference.