kayjaydee/PlayHours
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
64edfa4d7373bf9ab359c24af4a1e56fde6e2b78
PlayHours/docs/COMMANDS.md
Mr¤KayJayDee c0fd2a2787 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.
2025-10-23 23:28:20 +02:00

10 KiB
Raw Blame History

Commands Reference

This guide covers all available commands in PlayHours, their usage, permissions, and examples.

📋 Command Overview

All PlayHours commands use the /hours root command. Permission checks are applied automatically.

Permission Requirements

Permission Level Description
playhours.view Ops ≥1 Read-only access to status
playhours.admin Ops ≥2 Full administrative access
playhours.exempt Ops ≥2 Bypass all schedule restrictions

🔍 Status Commands

/hours status

Shows current server status and schedule information.

Permission: playhours.view (ops ≥1)

Output Example:

Mode: NORMAL. Server open. Next close: 10:00 PM. Next open: Monday at 9:00 AM.
Today's periods: 09:00 AM-06:00 PM, 11:00 PM-01:00 AM

Information Displayed:

  • Current force mode
  • Server open/closed status
  • Next closing time (if open)
  • Next opening time (if closed)
  • Today's schedule periods

🔧 Force Mode Commands

/hours force normal

/hours force open

/hours force close

Override the normal schedule enforcement.

Permission: playhours.admin (ops ≥2)

Modes:

  • normal - Follow configured schedule
  • open - Always allow access (24/7)
  • close - Always deny access (maintenance mode)

Examples:

/hours force open          # Enable 24/7 access
/hours force close         # Maintenance mode
/hours force normal        # Return to normal schedule

Notes:

  • Force modes override schedule but not blacklist
  • Exempt players can still join in FORCE_CLOSED mode
  • Changes take effect immediately

🔄 Configuration Commands

/hours reload

Reloads configuration from config/playhours.toml without restarting the server.

Permission: playhours.admin (ops ≥2)

Usage:

/hours reload

What it does:

  • Reloads all configuration settings
  • Rebuilds schedule cache
  • Reloads message translations
  • Applies changes immediately

When to use:

  • After editing config/playhours.toml
  • After changing timezone settings
  • After modifying schedule configuration

⚙️ Settings Commands

/hours set timezone <timezone>

Change the server timezone.

Permission: playhours.admin (ops ≥2)

Usage:

/hours set timezone America/New_York
/hours set timezone Europe/London
/hours set timezone Asia/Tokyo

Valid Timezones:

  • America/New_York (Eastern Time)
  • America/Chicago (Central Time)
  • America/Denver (Mountain Time)
  • America/Los_Angeles (Pacific Time)
  • Europe/London (GMT/BST)
  • Europe/Paris (CET/CEST)
  • Asia/Tokyo (JST)
  • Australia/Sydney (AEST/AEDT)

/hours set threshold <minutes>

Set the closing threshold in minutes.

Permission: playhours.admin (ops ≥2)

Usage:

/hours set threshold 20

Effect:

  • Denies new logins X minutes before close
  • Existing players can stay connected
  • Exempt players can bypass if configured

/hours set warnings <minutes...>

Configure warning broadcast times.

Permission: playhours.admin (ops ≥2)

Usage:

/hours set warnings 30 15 10 5 1

Examples:

  • 15 10 5 1 - Warn at 15, 10, 5, and 1 minutes before close
  • 30 15 5 - Warn at 30, 15, and 5 minutes before close
  • 60 30 15 10 5 1 - Extended warning sequence

/hours set countdown <seconds>

Set countdown duration before closing.

Permission: playhours.admin (ops ≥2)

Usage:

/hours set countdown 10

Range: 0-60 seconds (0 = disabled)

Effect:

  • Sends "Closing in Xs" messages every second
  • Only active during the last X seconds before close
  • Provides final warning to players

/hours set exempt_bypass_schedule <true|false>

/hours set exempt_bypass_threshold <true|false>

Control exempt player behavior.

Permission: playhours.admin (ops ≥2)

Usage:

/hours set exempt_bypass_schedule true
/hours set exempt_bypass_threshold false

Settings:

  • exempt_bypass_schedule - Allow exempt players to join when closed
  • exempt_bypass_threshold - Allow exempt players during threshold

📅 Schedule Commands

/hours set default periods add "<time_range>"

/hours set default periods clear

Manage default schedule periods.

Permission: playhours.admin (ops ≥2)

Usage:

/hours set default periods add "09:00 AM-06:00 PM"
/hours set default periods add "11:00 PM-01:00 AM"
/hours set default periods clear

Time Format: 12-hour AM/PM format with quotes

Examples:

/hours set default periods add "09:00 AM-06:00 PM"
/hours set default periods add "10:00 PM-02:00 AM"  # Midnight span
/hours set default periods clear                     # Remove all periods

/hours set day <day> periods add "<time_range>"

/hours set day <day> periods clear

Manage per-day schedule periods.

Permission: playhours.admin (ops ≥2)

Usage:

/hours set day mon periods add "09:00 AM-06:00 PM"
/hours set day fri periods add "11:00 PM-01:00 AM"
/hours set day tue periods clear

Day Names: mon, tue, wed, thu, fri, sat, sun

Examples:

/hours set day mon periods add "09:00 AM-06:00 PM"
/hours set day fri periods add "11:00 PM-01:00 AM"
/hours set day sat periods add "02:00 PM-11:59 PM"
/hours set day sun periods clear

📅 Exception Commands

/hours exceptions add-open "<date_time_range>"

/hours exceptions add-closed "<date>"

/hours exceptions clear

Manage date exceptions.

Permission: playhours.admin (ops ≥2)

Usage:

/hours exceptions add-open "2025-12-31 08:00 PM-11:59 PM"
/hours exceptions add-closed "2025-12-25"
/hours exceptions clear

Date Formats:

  • Open dates: YYYY-MM-DD hh:mm AM-hh:mm PM
  • Closed dates: YYYY-MM-DD

Examples:

/hours exceptions add-open "2025-12-31 08:00 PM-11:59 PM"  # New Year's Eve
/hours exceptions add-closed "2025-12-25"                  # Christmas Day
/hours exceptions add-open "2025-07-04 12:00 PM-11:59 PM"  # Independence Day
/hours exceptions clear                                     # Remove all exceptions

👥 List Commands

/hours lists whitelist toggle <player>

/hours lists blacklist toggle <player>

Toggle players in/out of lists.

Permission: playhours.admin (ops ≥2)

Usage:

/hours lists whitelist toggle PlayerName
/hours lists blacklist toggle PlayerName

Behavior:

  • Automatically enables the list if not already enabled
  • Case-insensitive player name matching
  • Toggle: Add if not present, remove if present

Examples:

/hours lists whitelist toggle Steve
/hours lists blacklist toggle Griefer123

/hours lists whitelist enable

/hours lists whitelist disable

/hours lists blacklist enable

/hours lists blacklist disable

Enable or disable lists.

Permission: playhours.admin (ops ≥2)

Usage:

/hours lists whitelist enable
/hours lists blacklist disable

📢 MOTD Commands

/hours motd toggle

Enable or disable MOTD schedule display.

Permission: playhours.admin (ops ≥2)

Usage:

/hours motd toggle

Effect:

  • Toggles MOTD feature on/off
  • Changes take effect immediately
  • Server list will show/hide schedule information

/hours motd status

View current MOTD settings.

Permission: playhours.admin (ops ≥2)

Usage:

/hours motd status

Output:

  • MOTD enabled/disabled status
  • Current MOTD configuration
  • Update frequency settings

💬 Message Commands

/hours messages reload

Reload message translations.

Permission: playhours.admin (ops ≥2)

Usage:

/hours messages reload

Effect:

  • Reloads message translations from language files
  • Applies any config overrides
  • Updates all player-facing messages

🔧 Advanced Commands

Command Chaining

Some commands support chaining for efficiency:

/hours set day mon periods add "09:00 AM-06:00 PM"
/hours set day tue periods add "09:00 AM-06:00 PM"
/hours set day wed periods add "09:00 AM-06:00 PM"

Batch Operations

Use multiple commands for complex setups:

/hours set default periods clear
/hours set day mon periods add "09:00 AM-06:00 PM"
/hours set day fri periods add "11:00 PM-01:00 AM"
/hours exceptions add-closed "2025-12-25"

🚨 Error Handling

Common Errors

Permission Denied:

You do not have permission to use this command

Solution: Check your permission level or LuckPerms configuration

Invalid Time Format:

Invalid time range. Use: hh:mm AM-hh:mm PM

Solution: Use proper 12-hour AM/PM format with quotes

Config Not Ready:

PlayHours config not ready yet. Try again in a moment.

Solution: Wait for server startup to complete

Troubleshooting

  1. Check permissions: Ensure you have the required permission level
  2. Verify format: Use correct time format and quotes
  3. Wait for startup: Allow server to fully initialize
  4. Check logs: Look for error messages in server logs

📚 Command Examples

Basic Server Setup

# Set timezone
/hours set timezone America/New_York

# Configure default hours
/hours set default periods add "09:00 AM-06:00 PM"

# Set weekend hours
/hours set day sat periods add "02:00 PM-11:59 PM"
/hours set day sun periods add "02:00 PM-10:00 PM"

# Configure warnings
/hours set warnings 15 10 5 1
/hours set countdown 5

Holiday Configuration

# Add holiday closures
/hours exceptions add-closed "2025-12-25"
/hours exceptions add-closed "2026-01-01"

# Add special event hours
/hours exceptions add-open "2025-12-31 08:00 PM-11:59 PM"

Maintenance Mode

# Enter maintenance mode
/hours force close

# Exit maintenance mode
/hours force normal

Player Management

# Add players to whitelist
/hours lists whitelist toggle PlayerName

# Add players to blacklist
/hours lists blacklist toggle Griefer123

# Enable whitelist
/hours lists whitelist enable

📚 Related Documentation

For configuration file options, see the Configuration Guide.

Reference in New Issue View Git Blame Copy Permalink