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 idle/AFK 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 - Multi-Session Support: Sessions start automatically when players with `usm.track` permission join the server - Multi-Session Support: Sessions end gracefully when players disconnect or when the server shuts down - Multi-Session Support: Staff can manually clock in/out using commands for flexible scheduling - Multi-Session Support: 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:

World Changes - World Changes - Detects physical movement (0.1 block precision) - World Changes - Tracks left/right head movement (1° precision) - World Changes - 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 - Configurable Thresholds: Checks every 20 ticks (1 second) for optimal performance - Configurable Thresholds: Every second adds 1000ms to either active or idle counter - Configurable Thresholds: Status changes are reflected immediately in GUIs - Configurable Thresholds: Fully customizable sensitivity settings

---

 3️⃣ Enterprise Database Management

 SQLite Support (Default)

Automatic Backups: - ✅ Automatic Backups: Works immediately after installation - ✅ Automatic Backups: Single database file, easy to backup - ✅ Automatic Backups: No external database server required - ✅ Automatic Backups: 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

Configurable pool sizing - ⚡ Configurable pool sizing - 🔄 Configurable pool sizing - 🛡️ Configurable pool sizing - 📊 Configurable pool sizing - 🔧 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: [Opens 9-slot GUI] ```

 `/stafftime clockin` (Manual Session Start) ```yaml Permission: usm.use Aliases: /st clockin, /clock in

Usage: /stafftime clockin

Description:   Manually starts a new time tracking session for the player.   Useful for staff who don't have auto-tracking enabled.

Validation Checks:   ├── Already has session? → Error message   ├── Permission check: usm.use   └── Player-only command

Success Message:   "═══════════════════════════════"   "   ✓ Clock-In Successful"   "═══════════════════════════════"   "Your work session has started."   "Session will be tracked until you clock out or disconnect."   ""   "View your stats: /stafftime"

Sound Effect: BLOCK_NOTE_BLOCK_PLING (1.0 volume, 2.0 pitch)

Database Action: Creates new session record (async) ```

 `/stafftime clockout` (Manual Session End) ```yaml Permission: usm.use Aliases: /st clockout, /clock out

Usage: /stafftime clockout

Description:   Manually ends the current active session and displays   a detailed summary of the work period.

Validation Checks:   ├── No active session? → Error message   ├── Permission check: usm.use   └── Player-only command

Success Output:   "═══════════════════════════════"   "   ✓ Clock-Out Successful"   "═══════════════════════════════"   ""   "Session Summary:"   ""   "  ⚡ Active Time: 2h 15m 30s"   "  ⏸ Idle Time: 18m 42s"   "  ⏱ Total Time: 2h 34m 12s"   "  📊 Activity: 87.5%"   ""   "Your session has been saved to the database."

Sound Effect: ENTITY_EXPERIENCE_ORB_PICKUP

Database Actions:   ├── Save session to usm_sessions table   ├── Update user totals in usm_users table   └── Remove from active sessions cache ```

 `/stafftime addnote <message>` (Session Annotation) ```yaml Permission: usm.use Aliases: /st addnote, /clock note

Usage: /stafftime addnote <message> Example: /stafftime addnote Handled 5 player reports

Description:   Adds a timestamped note to the current active session.   Notes are saved with the session and visible in history.

Validation Checks:   ├── No active session? → Error message   ├── Message empty? → Show usage   ├── Message > 200 chars? → Error message   ├── Notes > 50 per session? → Error message   └── Permission check: usm.use

Note Format:   Stored: "[14:35:22] Handled 5 player reports"   Timestamp: HH:mm:ss format (configurable)

Success Message:   "═══════════════════════════════"   "   📝 Note Added"   "═══════════════════════════════"   ""   "Note: Handled 5 player reports"   ""   "This note will be saved with your session."

Sound Effect: ENTITY_ITEM_PICKUP (0.5 volume, 1.5 pitch)

Use Cases:   ├── Document player reports handled   ├── Record ban appeals reviewed   ├── Note server events assisted   ├── Log important decisions made   └── Track tickets resolved ```

---

 Admin Commands (Detailed)

 `/stafftime top [days]` (Leaderboard) ```yaml Permission: usm.admin Aliases: /st top, /clock leaderboard

Usage:    /stafftime top          (defaults to 7 days)   /stafftime top 30       (last 30 days)   /stafftime top 1        (last 24 hours)

Description:   Displays a ranked leaderboard of staff members by   ACTIVE time (idle time excluded) for the specified period.

Parameters:   ├── days: Integer (1-365)   ├── Default: 7 days   └── Shows top 10 results

Output Format:   "═══════════════════════════════════════"   "   🏆 Top Staff - Last 7 Days"   "═══════════════════════════════════════"   ""   "🥇 1 PlayerOne - 45h 30m 15s"   "🥈 2 PlayerTwo - 38h 15m 42s"   "🥉 3 PlayerThree - 32h 45m 10s"   "   4 PlayerFour - 28h 20m 30s"   "   5 PlayerFive - 25h 55m 18s"   "   6 PlayerSix - 22h 10m 45s"   "   7 PlayerSeven - 20h 30m 22s"   "   8 PlayerEight - 18h 45m 50s"   "   9 PlayerNine - 15h 20m 12s"   "   10 PlayerTen - 12h 35m 40s"   ""   "═══════════════════════════════════════"   "Showing top 10 staff members"

Medal Icons:   ├── 🥇 1st Place (Gold)   ├── 🥈 2nd Place (Silver)   └── 🥉 3rd Place (Bronze)

Database Query:   SELECT u.name, SUM(s.active_millis) as total   FROM usm_sessions s   JOIN usm_users u ON s.uuid = u.uuid   WHERE s.start_timestamp >= [cutoff]   GROUP BY s.uuid   ORDER BY total DESC   LIMIT 10

Processing: Async (displays loading message) ```

 `/stafftime list` (Live Staff Monitor) ```yaml Permission: usm.admin Aliases: /st list, /clock active

Usage: /stafftime list

Description:   For players: Opens an interactive GUI with player heads   For console: Displays formatted chat list

GUI Features:   ├── Player heads with skins   ├── Real-time status indicators   ├── Session duration displays   ├── Activity percentages (color-coded)   ├── Note counts   └── Manual refresh button

Console Output:   "═══════════════════════════════════════"   "   📋 Currently Active Staff"   "═══════════════════════════════════════"   ""   "1. PlayerOne - 2h 34m (Activity: 92.3%)"   "   Active: 2h 15m | Idle: 18m"   ""   "2. PlayerTwo - 1h 45m (Activity: 78.5%)"   "   Active: 1h 22m | Idle: 22m"   ""   "═══════════════════════════════════════"   "Total: 2 staff member(s) active"

Use Cases:   ├── Monitor current staff availability   ├── Check who's actively working   ├── Identify idle staff members   ├── Plan shift coverage   └── Performance oversight ```

 `/stafftime adjust <player> <add|remove> <amount> <active|idle>` (Time Adjustment) ```yaml Permission: usm.admin (requires usm.adjust) Aliases: /st adjust, /clock modify

Usage:    /stafftime adjust <player> <add|remove> <amount> <active|idle>

Examples:   /stafftime adjust Steve add 3600000 active     → Adds 1 hour to Steve's active time      /stafftime adjust Alex remove 1800000 idle     → Removes 30 minutes from Alex's idle time      /stafftime adjust Bob add 7200000 active     → Adds 2 hours to Bob's active time

Parameters:   ├── player: Player name (online or offline)   ├── operation: "add" or "remove"   ├── amount: Milliseconds (1 hour = 3600000)   └── type: "active" or "idle"

Time Conversions:   ├── 1 minute  = 60,000 ms   ├── 5 minutes = 300,000 ms   ├── 10 minutes = 600,000 ms   ├── 30 minutes = 1,800,000 ms   ├── 1 hour = 3,600,000 ms   ├── 2 hours = 7,200,000 ms   └── 24 hours = 86,400,000 ms

Validation:   ├── Player exists check   ├── Amount > 0 check   ├── Valid operation check   ├── Valid type check   └── Permission verification

Confirmation Display:   "═══════════════════════════════════"   "   Time Adjustment"   "═══════════════════════════════════"   ""   "Player: Steve"   "Operation: ADD"   "Amount: 1h 0m 0s"   "Type: ACTIVE"   ""   "⏳ Processing adjustment..."   "✓ Time adjustment applied successfully!"

Logging:   Logs to console:   "[ADJUST] AdminName added 1h 0m 0s active time for Steve"

Use Cases:   ├── Correct tracking errors   ├── Compensate for server downtime   ├── Reward bonus time   ├── Fix database issues   └── Manual corrections ```

---

 6️⃣ Permission System (Complete)

 Permission Hierarchy Tree ``` usm.* (OP) │ ├─ usm.use (TRUE) ─────────────────┐ │  ├─ usm.clockin                  │ PLAYER │  ├─ usm.clockout                 │ PERMISSIONS │  ├─ usm.addnote                  │ │  └─ usm.history                  │ │                                   │ ├─ usm.track (FALSE) ──────────────┤ STAFF │  └─ [Enables auto-tracking]      │ PERMISSION │                                   │ └─ usm.admin.* (OP) ───────────────┘    ├─ usm.admin    ├─ usm.top    ├─ usm.list    └─ usm.adjust ```

 Permission Descriptions

usm.* (Parent Permission) ```yaml Description: Grants all plugin permissions Default: OP only Children:   - usm.use   - usm.track   - usm.admin   - usm.adjust

Grant Command (LuckPerms):   /lp user <name> permission set usm.*

Use Case: Server owners and senior administrators ```

usm.use (Basic Access) ```yaml Description: Access to dashboard and basic commands Default: True (all players) Allows:   - /stafftime (dashboard)   - /stafftime clockin   - /stafftime clockout   - /stafftime addnote

Does NOT Allow:   - Auto-tracking on join   - Admin commands

Grant Command:   /lp group default permission set usm.use true

Use Case: All players (for personal time tracking) ```

usm.track (Auto-Tracking) ```yaml Description: Enables automatic session tracking Default: False (must be granted) Behavior:   - Auto clock-in on join   - Auto clock-out on quit   - Requires usm.use permission also

Grant Command:   /lp user <name> permission set usm.track true

Use Case: ONLY grant to actual staff members

Example Setup:   1. Create staff group: /lp creategroup staff   2. Grant tracking: /lp group staff permission set usm.track true   3. Add user: /lp user PlayerName parent add staff ```

usm.admin (Admin Commands) ```yaml Description: Access to administrative features Default: OP only Allows:   - /stafftime top   - /stafftime list   - View all player data

Does NOT Allow:   - Time adjustments (requires usm.adjust)

Grant Command:   /lp user <name> permission set usm.admin true

Use Case: Server moderators and administrators ```

usm.adjust (Time Modification) ```yaml Description: Ability to modify player time records Default: OP only Allows:   - /stafftime adjust command   - Add/remove time from any player

Security Warning:   Only grant to highly trusted administrators!

Grant Command:   /lp user <name> permission set usm.adjust true

Use Case: Senior admins for corrections only ```

 Recommended Permission Setups

Setup 1: Small Server (10-50 players) ```yaml Default Group (All Players):   - usm.use: true

Staff Group (Moderators):   - Inherits: default   - usm.track: true

Admin Group (Administrators):   - Inherits: staff   - usm.admin: true   - usm.adjust: true

Commands:   /lp creategroup staff   /lp group staff parent add default   /lp group staff permission set usm.track true      /lp creategroup admin   /lp group admin parent add staff   /lp group admin permission set usm.admin true   /lp group admin permission set usm.adjust true ```

Setup 2: Large Network (100+ players) ```yaml Groups:   default:     - No USM permissions (not tracked)      helper:     - usm.use: true     - usm.track: true      moderator:     - Inherits: helper     - usm.admin: true      admin:     - Inherits: moderator     - usm.adjust: true      owner:     - usm.*: true

Commands:   /lp creategroup helper   /lp group helper permission set usm.use true   /lp group helper permission set usm.track true      /lp creategroup moderator   /lp group moderator parent add helper   /lp group moderator permission set usm.admin true      /lp creategroup admin   /lp group admin parent add moderator   /lp group admin permission set usm.adjust true ```  🔟 Integration & API

 PlaceholderAPI Support (Planned v1.1)

Planned Placeholders: ```yaml %usm_session_duration%        → "2h 34m 12s" %usm_session_active%          → "2h 15m 30s" %usm_session_idle%            → "18m 42s" %usm_session_activity%        → "87.5%" %usm_session_status%          → "Active" / "Idle" %usm_total_active%            → "145h 30m 15s" %usm_total_idle%              → "12h 45m 20s" %usm_rank_position%           → "3" %usm_notes_count%             → "5"

Usage Example (Scoreboard):   - &aSession: &f%usm_session_duration%   - &aStatus: &f%usm_session_status%   - &aActivity: &f%usm_session_activity% ```

 1️⃣2️⃣ Support & Resources

 Official Resources

🐛 Bug Reporting: - 🐛 Bug Reporting:

---

 1️⃣3️⃣ Technical Specifications

Plugin Information: ```yaml Name: UltimateStaffManagement Version: 1.0.0 Author: geturplugins License: AllRightsReserved Language: Java 21

Dependencies:   ├── Paper API: 1.21-1.21.11 (Required)   ├── HikariCP: 5.1.0 (Bundled)   ├── SQLite JDBC: 3.45.1.0 (Bundled)   ├── MySQL Connector: 8.3.0 (Optional)   └── Adventure API: 4.x (Provided by Paper)

File Size:   ├── JAR Size: ~1.5 MB   ├── With Dependencies: ~3.2 MB   └── Database (SQLite): Grows ~50KB per 1000 sessions

Performance:   ├── RAM Usage: 30-50MB (100 active sessions)   ├── CPU Impact: < 0.1% per 50 tracked players   ├── TPS Impact: None (async operations)   └── Database Speed: < 10ms per query (SSD)

Compatibility:   ✅ Paper 1.21 - 1.21.11   ✅ Purpur 1.21+   ⚠️  Spigot 1.21 (Limited Adventure API)   ❌ Bukkit (Not supported)   ❌ Folia (Not yet supported) ```

---

📊 Statistics (Example Server)

Server Profile: - Type: Roleplay Server - Players: 150 concurrent - Staff: 25 tracked members - Database: MySQL - Uptime: 99.8%

Results: ```yaml Performance Metrics:   ├── Average Session Length: 3h 15m   ├── Total Sessions Tracked: 12,450   ├── Database Size: 145 MB   ├── Query Response Time: < 5ms   └── Zero TPS impact

Staff Insights:   ├── Most Active Staff: 45h/week   ├── Average Activity Rate: 82.3%   ├── Total Hours Tracked: 15,230h   └── Notes Recorded: 3,847

Resource Usage:   ├── Plugin RAM: 42 MB   ├── Database Connections: 8 active   ├── Thread Pool: 4 threads   └── CPU Usage: 0.08% ```

---

 🎓 Summary

UltimateStaffManagement is the most comprehensive staff tracking solution for Minecraft servers, offering:

✅ Production Ready - Millisecond-accurate time tracking with active/idle differentiation   ✅ Production Ready - Fully asynchronous operations with HikariCP pooling   ✅ Production Ready - Interactive dashboards with real-time updates   ✅ Production Ready - SQLite and MySQL support with automatic backups   ✅ Production Ready - Leaderboards, performance metrics, and detailed reports   ✅ Production Ready - 100+ config options for complete customization   ✅ Production Ready - Full Java API with extensive documentation   ✅ Production Ready - Battle-tested architecture with comprehensive error handling  

Perfect for: - Roleplay servers requiring staff hour tracking - Networks needing centralized time management - Communities managing volunteer staff - Professional servers with paid staff positions - Any server wanting detailed activity analytics

---

🏆 The Ultimate Solution for Staff Management 🏆