UltimateStaffManagement

** 📘 UltimateStaffManagement - Complete Documentation --- 🎯 Plugin Overview What is UltimateStaffManagement? **UltimateStaffManagement** is an enterprise-grade staff time tracking plugin designed specifically for Minecraft Paper servers running versions 1.21 through 1.21.11. It provides server administrators with powerful tools to monitor, analyze, and manage staff member activity with precision and ease. Unlike basic time-tracking solutions, UltimateStaffManagement intelligently differentiates between **active work time** and **idle/AFK time**, giving you accurate insights into actual staff productivity rather than just login duration. --- 🌟 Key Features (Complete List) 1️⃣ Intelligent Session Management Automatic Session Tracking - **Auto Clock-In:** Sessions start automatically when players with `usm.track` permission join the server - **Auto Clock-Out:** Sessions end gracefully when players disconnect or when the server shuts down - **Manual Override:** Staff can manually clock in/out using commands for flexible scheduling - **Session Persistence:** All active sessions are immediately saved during unexpected server crashes - **Multi-Session Support:** Tracks unlimited historical sessions per player Session Data Captured ```yaml For Each Session: ├── Unique Session ID ├── Player UUID & Name ├── Start Timestamp (millisecond precision) ├── End Timestamp (millisecond precision) ├── Total Active Time (milliseconds) ├── Total Idle Time (milliseconds) ├── Session Notes (timestamped entries) └── Activity Percentage Calculation ``` --- 2️⃣ Advanced AFK/Activity Detection Movement-Based Detection The plugin uses a sophisticated multi-factor detection system: **Tracked Parameters:** - **X, Y, Z Coordinates** - Detects physical movement (0.1 block precision) - **Yaw (Head Rotation Horizontal)** - Tracks left/right head movement (1° precision) - **Pitch (Head Rotation Vertical)** - Tracks up/down head movement (1° precision) - **World Changes** - Instant detection of teleportation/dimension changes **Detection Algorithm:** ```java Movement Detected IF: ├── X/Y/Z change > 0.1 blocks OR ├── Yaw change > 1.0 degrees OR ├── Pitch change > 1.0 degrees OR └── World change detected Status Update: ├── ACTIVE: Any movement detected within timeout period └── IDLE: No movement for configured duration (default: 600 seconds) ``` Time Tracking Mechanism - **Tick Rate:** Checks every 20 ticks (1 second) for optimal performance - **Time Accumulation:** Every second adds 1000ms to either active or idle counter - **Real-Time Updates:** Status changes are reflected immediately in GUIs - **Configurable Thresholds:** Fully customizable sensitivity settings --- 3️⃣ Enterprise Database Management SQLite Support (Default) **Advantages:** - ✅ **Zero Configuration:** Works immediately after installation - ✅ **Portable:** Single database file, easy to backup - ✅ **No Dependencies:** No external database server required - ✅ **WAL Mode:** Write-Ahead Logging for data integrity - ✅ **Automatic Backups:** Daily backup rotation (configurable) ``` MySQL Support (Optional) **Perfect For:** - Multi-server networks (BungeeCord/Velocity) - Centralized data management - Advanced querying and reporting - Large player bases (500+ concurrent) **Configuration Example:** ```yaml storage-type: mysql mysql: host: db.yournetwork.com port: 3306 database: staff_tracking username: minecraft password: securePassword123 pool: maximum-pool-size: 10 Max concurrent connections minimum-idle: 2 Idle connections maintained connection-timeout: 30000 30 seconds idle-timeout: 600000 10 minutes max-lifetime: 1800000 30 minutes use-ssl: true Encrypted connections ``` HikariCP Connection Pooling **Performance Benefits:** - ⚡ **Sub-millisecond connection acquisition** - 🔄 **Automatic connection recycling** - 🛡️ **Connection leak detection** - 📊 **Real-time pool statistics** - 🔧 **Configurable pool sizing** **Async Architecture:** ``` Player Action ↓ Main Thread (No Blocking) ↓ Async Task Queue ↓ HikariCP Thread Pool ↓ Database Operation ↓ Callback to Main Thread ↓ Result Displayed ``` 5️⃣ Comprehensive Command System Player Commands (Detailed) `/stafftime` (Main Dashboard) ```yaml Permission: usm.use Aliases: /st, /clock, /staffclock Usage: /stafftime Description: Opens the main interactive dashboard GUI showing: - Current session statistics - Real-time activity status - Quick access to history and notes Behavior: ├── If Active Session: Shows live stats ├── If No Session: Displays "Not clocked in" with instructions └── Permission Check: Requires usm.use Sound Effect: BLOCK_CHEST_OPEN (0.5 volume) Example Output: ``` `/stafftime clockin` (Manual Session Start) ```yaml Permission: usm.use Aliases: /st clockin, /clock in Usage: /stafftime clock