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
```

---

 4️⃣ Interactive GUI System

 Dashboard GUI (`/stafftime`)

**Layout Design:**
```
┌─────────────────────────────────────┐
│  [Filler]  [Clock]   [Filler]      │
│  [Filler]  [Book]    [Filler]      │
│  [Filler]  [Paper]   [Filler]      │
└─────────────────────────────────────┘
```

**Slot 2: Current Session Stats (Clock Item)**
```yaml
Display Information:
  - Status Indicator: ✓ Active / ⏸ Idle
  - Session Duration: "2h 34m 12s"
  - Active Time: "2h 15m 30s" (Green)
  - Idle Time: "18m 42s" (Yellow)
  - Activity Rate: "87.5%" (Color-coded)
  - Real-time Updates: Every 2 seconds

Color Coding:
  ├── Green (80-100%): Excellent activity
  ├── Yellow (50-79%): Moderate activity
  └── Red (0-49%): Low activity

Click Action: Refresh data
```

**Slot 4: Session History (Book Item)**
```yaml
Features:
  - Shows last 5 completed sessions
  - Date format: "Jan 15, 2026 14:30"
  - Duration breakdown per session
  - Activity percentage trends
  - Total time statistics

Click Action: Opens History GUI

Lore Preview:
  "Recent Sessions:"
  "━━━━━━━━━━━━━━"
  "Jan 15 - 3h 45m (92% active)"
  "Jan 14 - 5h 12m (78% active)"
  "Jan 13 - 2h 30m (95% active)"
```

**Slot 6: Session Notes (Paper Item)**
```yaml
Note Display:
  - Last 5 notes shown
  - Timestamped entries: "[14:35:22] Handled player reports"
  - Total note count indicator
  - Add instructions in lore

Click Action: View-only (add via command)

Example Lore:
  "📝 Session Notes (3)"
  "━━━━━━━━━━━━━━"
  "[14:35:22] Handled 5 player reports"
  "[15:10:45] Reviewed ban appeals"
  "[16:22:11] Assisted with server event"
  ""
  "Add notes: /stafftime addnote <message>"
```

---

 History GUI (`Click book in dashboard`)

**Layout:**
```
┌─────────────────────────────────────────────────┐
│  [Glass]  [Glass]  [Glass]  [Glass]  [Glass]   │
│  [Session1] [Session2] [Session3] [Session4]   │
│  [Session5] [Glass]    [Glass]    [Glass]      │
│  [Glass]  [Glass]  [Glass]  [Back Button]      │
└─────────────────────────────────────────────────┘
```

**Session Item Details:**
```yaml
Item Type: Writable Book
Display Name: "Session 1" (Gold, Bold)

Lore Information:
  ├── 📅 Date: "Jan 15, 2026 09:30"
  ├── ⏰ Duration: "3h 45m 30s"
  ├── ⚡ Active Time: "3h 28m 15s"
  ├── ⏸ Idle Time: "17m 15s"
  ├── 📊 Activity: "92.3%"
  └── 📝 Notes: "(3)" - Shows first 3 notes

Click: View full session details (future feature)
```

**Navigation:**
- Slot 26: Back arrow (returns to dashboard)
- Pagination (future): Next/Previous page buttons

---

 Staff List GUI (`/stafftime list` - Admin)

**Layout:**
```
┌──────────────────────────────────────────────────┐
│  [Glass] [Glass] [Glass] [Glass] [Glass] [Glass]│
│  [Staff1] [Staff2] [Staff3] [Staff4] [Staff5]   │
│  [Staff6] [Staff7] [Staff8] [Glass] [Glass]     │
│  [Glass] [Glass] [Glass] [Refresh] [Glass]      │
└──────────────────────────────────────────────────┘
```

**Staff Member Item:**
```yaml
Item Type: Player Head (shows player skin)
Display Name: "PlayerName ✔" (Active) / "PlayerName ⏸" (Idle)

Status Colors:
  ├── White & Bold: Player name
  ├── Green ✔: Currently active
  └── Yellow ⏸: Currently idle

Lore Display:
  ├── Status: "Active" (colored)
  ├── ⏱ Session: "1h 23m 45s"
  ├── ⚡ Active: "1h 15m 30s"
  ├── ⏸ Idle: "8m 15s"
  ├── 📊 Activity: "90.1%" (color-coded)
  └── 📝 Notes: "(2)" if notes exist

Real-Time Updates: Auto-refreshes every 2 seconds
```

**Slot 49: Info/Refresh Button**
```yaml
Item: Knowledge Book
Display: "ℹ Information"

Lore:
  "Total Active Staff: 7"
  "Right-click to refresh"

Click: Manual refresh (instant update)
```

---

 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
```

---

 7️⃣ Configuration Deep Dive

 Critical Settings Explained

**afk-timeout-seconds** (Default: 600)
```yaml
Description:
  Time in seconds before a player is marked as IDLE.
  
Values:
  Minimum: 30 (30 seconds)
  Recommended: 300-900 (5-15 minutes)
  Maximum: 3600 (1 hour)
  Default: 600 (10 minutes)

Impact:
  ├── Lower values (30-120): Strict monitoring, more idle time recorded
  ├── Medium values (300-600): Balanced, recommended for most servers
  └── Higher values (900+): Lenient, allows breaks without idle marking

Example Scenarios:
  afk-timeout-seconds: 120
    → Staff marked idle after 2 minutes of no movement
    → Good for: High-activity servers, customer service roles
  
  afk-timeout-seconds: 600
    → Staff marked idle after 10 minutes
    → Good for: General servers, balanced tracking
  
  afk-timeout-seconds: 1800
    → Staff marked idle after 30 minutes
    → Good for: Build servers, relaxed environments
```

**movement-threshold** (Default: 0.1)
```yaml
Description:
  Minimum block movement required to register as activity.

Values:
  0.05: Very sensitive (counts tiny movements)
  0.1: Recommended (balanced sensitivity)
  0.5: Less sensitive (requires larger movements)
  1.0: Minimal sensitivity (only counts significant movement)

Impact on Detection:
  ├── Lower = More sensitive = More active time
  └── Higher = Less sensitive = More idle time

Example:
  movement-threshold: 0.05
    → Even small adjustments count as active
    → May register unintentional movements
  
  movement-threshold: 1.0
    → Only walking/running counts as active
    → AFK mining/fishing marked as idle
```

**rotation-threshold** (Default: 1.0)
```yaml
Description:
  Minimum degrees of head rotation to register as activity.

Values:
  0.5: Very sensitive (slight head turns count)
  1.0: Recommended (normal head movements)
  5.0: Less sensitive (requires deliberate looking)
  10.0: Minimal (only counts large view changes)

Use Cases:
  1.0 degrees:
    → Looking around while standing counts as active
    → Good for: Monitoring roles, ticket handling
  
  5.0 degrees:
    → Only significant head turns count
    → Good for: Strict movement-only tracking
```

**auto-save-interval** (Default: 5)
```yaml
Description:
  How often (in minutes) to save active sessions to database.

Values:
  0: Disabled (only save on logout)
  1-5: Frequent saves (recommended)
  10-30: Infrequent saves (performance mode)
  60+: Minimal saves (not recommended)

Safety vs Performance:
  ├── Lower interval = Safer (less data loss) but more DB writes
  └── Higher interval = Faster but risk losing recent data

Recommendations:
  Small server (< 20 staff): 5 minutes
  Medium server (20-100 staff): 3 minutes
  Large server (100+ staff): 10 minutes + MySQL
```

**max-session-duration** (Default: 24)
```yaml
Description:
  Maximum hours before auto-ending a session.
  Prevents infinitely running sessions from AFK players.

Values:
  0: Unlimited (not recommended)
  8: 8-hour work shift
  12: Half-day maximum
  24: Full day (recommended default)

Example:
  max-session-duration: 8
    → After 8 hours, session auto-ends
    → Player must manually clock back in
    → Good for: Enforcing shift limits
```

---

 Message Customization (MiniMessage)

**Supported Formats:**

**Colors:**
```yaml
<red>Error message</red>
<green>Success message</green>
<yellow>Warning message</yellow>
<blue>Info message</blue>
<gold>Special message</gold>
<aqua>Highlight</aqua>
<gray>Subtle text</gray>
<dark_gray>Very subtle</dark_gray>
<white>Default text</white>
```

**Formatting:**
```yaml
<bold>Bold text</bold>
<italic>Italic text</italic>
<underlined>Underlined</underlined>
<strikethrough>Strikethrough</strikethrough>
<obfuscated>Obfuscated</obfuscated>
```

**Gradients:**
```yaml
<gradient:red:blue>Gradient text</gradient>
<gradient:gold:yellow:green>Multi-color gradient</gradient>
<gradient:FF0000:00FF00>Hex gradients</gradient>
```

**Hover Text:**
```yaml
<hover:show_text:'Hover to see this!'>Main text</hover>
<hover:show_text:'<green>Colored hover text'>Hover me</hover>
```

**Click Actions:**
```yaml
<click:run_command:'/stafftime'>Click to run</click>
<click:suggest_command:'/stafftime '>Click to suggest</click>
<click:open_url:'https://example.com'&gt;Click to open</click>
```

**Combined Example:**
```yaml
messages:
  session-started: >
    <gradient:green:aqua><bold>✓ SESSION STARTED</bold></gradient>
    <newline>
    <gray>Your time is being tracked.</gray>
    <newline>
    <hover:show_text:'<green>Click to view dashboard'>
      <click:run_command:'/stafftime'>
        <aqua>→ View Stats</aqua>
      </click>
    </hover>
```

---

 8️⃣ Use Cases & Scenarios

 Scenario 1: Professional Roleplay Server

**Server Type:** Roleplay/Economy  
**Staff Size:** 15 moderators, 5 admins  
**Requirement:** Track moderation hours for monthly payments

**Configuration:**
```yaml
afk-timeout-seconds: 300   5 minutes (strict)
max-session-duration: 8    8-hour shifts
auto-save-interval: 3      Frequent saves

notifications:
  hourly-updates: true     Remind staff of hours worked
  admin-notifications: true   Notify admins of clock-ins
```

**Permissions:**
```bash
 Moderators get auto-tracking
/lp group moderator permission set usm.track true

 Admins can view leaderboards
/lp group admin permission set usm.admin true
```

**Usage Workflow:**
1. Moderator joins server → Auto clock-in
2. Works for 4 hours → Session tracked
3. Moderator leaves → Auto clock-out
4. Admin runs `/stafftime top 30` → View monthly hours
5. Admin exports data → Calculate payments

---

 Scenario 2: Large Network Staff Management

**Server Type:** Multi-server network (Hub + 5 game servers)  
**Staff Size:** 50+ staff across all servers  
**Requirement:** Centralized time tracking

**Configuration:**
```yaml
storage-type: mysql   Centralized database

mysql:
  host: db.network.com
  database: staff_global
  
performance:
  thread-pool-size: 8   Higher for many concurrent users
  cache-enabled: true
  cache-size: 200       Cache more sessions
```

**Database Setup:**
```sql
-- Shared MySQL database accessible by all servers
-- Each server writes to same tables
-- Real-time synchronization
```

**Benefits:**
- Staff can work on any server, time is tracked globally
- Admins see combined hours across all servers
- Single leaderboard for entire network

---

 Scenario 3: Community Event Tracking

**Server Type:** Community server  
**Staff Size:** 10 event coordinators  
**Requirement:** Track event preparation time

**Configuration:**
```yaml
afk-timeout-seconds: 900   15 minutes (lenient for building)
max-note-length: 500       Detailed event notes

notifications:
  session-start: false     Don't spam during events
  session-end: true        Summary at end
```

**Usage:**
```bash
 Event coordinator starts
/stafftime clockin

 Add notes throughout
/stafftime addnote Started building event arena
/stafftime addnote Configured game mechanics
/stafftime addnote Tested event with team

 View hours spent on event
/stafftime clockout
```

**Exported Data:**
```json
{
  "session_id": 12345,
  "coordinator": "EventStaff",
  "duration": "5h 30m",
  "notes": [
    "[10:00:00] Started building event arena",
    "[11:30:00] Configured game mechanics",
    "[14:15:00] Tested event with team"
  ]
}
```

---

 Scenario 4: Performance Monitoring

**Server Type:** Competitive server  
**Staff Size:** 20 helpers  
**Requirement:** Identify most active staff for promotions

**Commands Used:**
```bash
 Weekly leaderboard
/stafftime top 7

 Monthly review
/stafftime top 30

 Check current availability
/stafftime list

 View individual performance
/stafftime (player opens own dashboard)
```

**Metrics Tracked:**
```yaml
Promotion Criteria:
  ├── Total active hours > 40h per month
  ├── Activity percentage > 85%
  ├── Consistent daily presence
  └── Low idle time ratio

Evaluation Process:
  1. Run /stafftime top 30
  2. Export top performers
  3. Review session notes for quality
  4. Check activity percentage
  5. Make promotion decisions
```

---

 9️⃣ Performance Optimization

 Server Performance Impact

**CPU Usage:**
```yaml
AFK Detection Task (per 20 ticks):
  ├── Players Tracked: 50 staff
  ├── Checks per Second: 50 location comparisons
  ├── CPU Impact: < 0.1% on modern servers
  └── Optimization: Uses efficient location caching

Database Operations:
  ├── All writes: Asynchronous (no TPS impact)
  ├── Reads: Cached (minimal DB hits)
  └── Connection Pooling: HikariCP (sub-ms acquisition)

Total Impact:
  ├── TPS Impact: None (< 0.01ms per tick)
  ├── Memory: ~50MB for 100 active sessions
  └── Recommended: 512MB RAM allocation minimum
```

**Optimization Settings:**

For **Small Servers** (< 50 players):
```yaml
performance:
  async-database: true
  cache-enabled: true
  cache-size: 50
  thread-pool-size: 2

afk:
  check-interval-ticks: 20   Standard 1-second checks
```

For **Large Servers** (100+ players):
```yaml
performance:
  async-database: true
  cache-enabled: true
  cache-size: 200            Cache more sessions
  thread-pool-size: 8        More async threads
  batch-size: 100            Larger batch inserts

afk:
  check-interval-ticks: 20   Keep responsive

mysql:
  pool:
    maximum-pool-size: 20    More DB connections
    minimum-idle: 5
```

For **Networks** (Multi-server):
```yaml
storage-type: mysql          Required for multi-server

mysql:
  host: dedicated-db-server.com
  pool:
    maximum-pool-size: 30
    minimum-idle: 10

performance:
  cache-duration-minutes: 60   Longer caching
  thread-pool-size: 16         Network-grade threading
```

---

 🔟 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️⃣1️⃣ Troubleshooting Guide

 Common Issues & Solutions

**Issue 1: "Sessions not being tracked"**

**Symptoms:**
- Player joins but no session starts
- `/stafftime` shows "No active session"

**Diagnosis:**
```bash
 Check permission
/lp user <player> permission check usm.track
 Should show: true

 Check console logs
 Look for: "[ADJUST] Auto-started session for <player>"
```

**Solutions:**
```yaml
1. Verify Permission:
   /lp user <player> permission set usm.track true

2. Check Auto-Tracking Config:
    In config.yml
   notifications:
     session-start: true   Must be true

3. Check Plugin Loaded:
   /plugins
    UltimateStaffManagement should be GREEN

4. Test Manual Clock-In:
   /stafftime clockin
    If this works, permission issue confirmed
```

---

**Issue 2: "Database connection failed"**

**Error Message:**
```
[ERROR] [DB] Failed to create tables: Communications link failure
```

**For SQLite:**
```bash
 Check file permissions
ls -la plugins/UltimateStaffManagement/
 Should show: -rw-r--r-- staffdata.db

 Fix permissions
chmod 644 plugins/UltimateStaffManagement/staffdata.db

 Delete and regenerate
rm plugins/UltimateStaffManagement/staffdata.db
/reload confirm
```

**For MySQL:**
```yaml
 Test connection manually
mysql -h localhost -u username -p database_name

 Common fixes:
mysql:
  host: 127.0.0.1   Try IP instead of localhost
  use-ssl: false    Disable SSL if having issues

 Grant proper permissions
GRANT ALL PRIVILEGES ON ultimatestaff.* TO 'minecraft'@'%';
FLUSH PRIVILEGES;
```

---

**Issue 3: "AFK detection not working"**

**Symptoms:**
- Player moving but still marked as idle
- Player AFK but marked as active

**Debug Steps:**
```yaml
1. Enable Debug Mode:
   config.yml:
     debug-mode: true

2. Check Console:
    Should see every second:
   "[AFK] Checking 5 players..."
   "[AFK] PlayerName is now ACTIVE"

3. Verify Settings:
   afk-timeout-seconds: 600
   movement-threshold: 0.1
   rotation-threshold: 1.0
   check-interval-ticks: 20

4. Test Sensitivity:
    Lower for more sensitive
   movement-threshold: 0.05
   rotation-threshold: 0.5
```

---

**Issue 4: "Server lag when using plugin"**

**Symptoms:**
- TPS drops when staff join
- Lag spikes every few seconds

**Diagnosis:**
```bash
 Check TPS
/tps   Should be 20.0

 Check timings
/timings on
 Wait 5 minutes
/timings paste
```

**Solutions:**
```yaml
1. Verify Async Enabled:
   performance:
     async-database: true

2. Reduce Check Frequency:
   check-interval-ticks: 40   Check every 2 seconds instead

3. Increase Thread Pool:
   performance:
     thread-pool-size: 8

4. Enable Caching:
   performance:
     cache-enabled: true
     cache-size: 200

5. Use MySQL for Large Servers:
   storage-type: mysql
```

---

**Issue 5: "Data not saving on server crash"**

**Symptoms:**
- Session lost after server crash
- Hours not recorded

**Prevention:**
```yaml
1. Enable Auto-Save:
   auto-save-interval: 3   Save every 3 minutes

2. Enable Backups:
   advanced:
     auto-backup: true
     backup-interval-hours: 6

3. Use WAL Mode (SQLite):
   sqlite:
     wal-mode: true

4. Test Manual Save:
   /stafftime clockout
    Then check database
```

---

 1️⃣2️⃣ Support & Resources

 Official Resources

**🐛 Bug Reporting:**
- [Discord](geturplugins)

---

 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:

✅ **Precision Tracking** - Millisecond-accurate time tracking with active/idle differentiation  
✅ **Zero Performance Impact** - Fully asynchronous operations with HikariCP pooling  
✅ **Beautiful GUIs** - Interactive dashboards with real-time updates  
✅ **Enterprise Database** - SQLite and MySQL support with automatic backups  
✅ **Powerful Analytics** - Leaderboards, performance metrics, and detailed reports  
✅ **Flexible Configuration** - 100+ config options for complete customization  
✅ **Developer Friendly** - 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

---

<div align="center">

**🏆 The Ultimate Solution for Staff Management 🏆**

</div>